X-Git-Url: https://git.whamcloud.com/?p=fs%2Flustre-release.git;a=blobdiff_plain;f=lustre%2Fdoc%2Flctl.8;h=58a18c3b5304ab787e34bdb195210376d6192c20;hp=a9bc9a070a8d46bec48f63b4003d6930ae895cfc;hb=956eeec06548f85c249b5a7495dc9bbdcb30b86b;hpb=041e699daec9e22a60ce8daf97a118933df031d4 diff --git a/lustre/doc/lctl.8 b/lustre/doc/lctl.8 index a9bc9a0..58a18c3 100644 --- a/lustre/doc/lctl.8 +++ b/lustre/doc/lctl.8 @@ -1,4 +1,4 @@ -.TH lctl 1 "2003 Oct 8" Lustre "configuration utilities" +.TH lctl 8 "2017 Jan 12" Lustre "configuration utilities" .SH NAME lctl \- Low level Lustre filesystem configuration utility .SH SYNOPSIS @@ -7,44 +7,47 @@ lctl \- Low level Lustre filesystem configuration utility .br .B lctl --device .br +.B lctl --version +.br +.B lctl --list-commands +.br .SH DESCRIPTION .B lctl is used to directly control Lustre via an ioctl interface, allowing various configuration, maintenance, and debugging features to be accessed. - + .B lctl can be invoked in interactive mode by issuing lctl command. After that, commands are issued as below. The most common commands in lctl are -.B dl -, -.B dk -, -.B device -, -.B network -.I -, -.B list_nids -, +.BR dl , +.BR dk , +.BR device , +.B network +.IR , +.BR list_nids , .B ping -.I nid -, -.B help -, -.B quit. +.IR nid , +.BR help , +.BR quit . To get a complete listing of available commands, type -.B help +.B --list-commands at the lctl prompt. To get basic help on the meaning and syntax of a -command, type -.B help +command, type +.B help .I command -. Command completion is activated with the TAB key, and command history is available via the up- and down-arrow keys. +. Command completion is activated with the TAB key, and command history is available via the up- and down-arrow keys. -For non-interactive use, one uses the second invocation, which runs command after connecting to the device. +For non-interactive use, one uses the second invocation, which runs command after connecting to the device. + +.SS System Configuration +The on-line tool set for backup or removal of Lustre system configuration. For detail, please see: +.PP +\fBlctl-lcfg\fR(8) +.RS 4 .SS Network Configuration .TP -.BI network " |" +.BR network " <" up / down >|< tcp / o2ib > Start or stop LNET, or select a network type for other .I lctl LNET commands @@ -56,7 +59,7 @@ Print all Network Identifiers on the local node. LNET must be running. From a list of nids for a remote node, show which interface communication will take place on. .TP -.BI replace_nids " [,nid2,nid3 ...]" +.BI replace_nids " [,nid2,nid3:nid4,nid5:nid6 ...]" Replace the LNET Network Identifiers for a given device, as when the server's IP address has changed. This command must be run on the MGS node. @@ -65,176 +68,58 @@ in another cases). To start the MGS service only: mount -t lustre -o nosvc Note the replace_nids command skips any invalidated records in the configuration log. The previous log is backed up with the suffix '.bak'. +Failover nids must be passed after ':' symbol. More then +one failover can be set (every failover nids after ':' symbol). .TP -.BI ping " " +.BI ping " timeout" Check LNET connectivity via an LNET ping. This will use the fabric -appropriate to the specified NID. +appropriate to the specified NID. By default lctl will attempt to +reach the remote node up to 120 seconds and then timeout. To disable +the timeout just specify an negative timeout value. .TP -.BI interface_list -Print the network interface information for a given +.BI interface_list +Print the network interface information for a given .B network type. .TP -.BI peer_list -Print the known peers for a given +.BI peer_list +Print the known peers for a given .B network type. .TP -.BI conn_list +.BI conn_list Print all the connected remote NIDs for a given .B network type. .TP -.BI active_tx -This command should print active transmits, and it is only used for elan network type. -.TP -.BI route_list +.BI route_list Print the complete routing table. .PP .SS Device Selection -.TP -.BI device " " -This will select the specified OBD device. All other commands depend on the device being set. -.TP -.BI device_list -Show all the local Lustre OBDs. AKA +.TP +.BI device " " +This will select the specified OBD device. All other commands depend on the device being set. +.TP +.BI device_list +Show all the local Lustre OBDs. AKA .B dl .PP .SS Device Operations -.TP -.BI list_param " [-F|-R] " -List the Lustre or LNet parameter name -.B -F -Add '/', '@' or '=' for dirs, symlinks and writeable files, respectively. -.br -.B -R -Recursively list all parameters under the specified parameter search string. If -.I param_search -is unspecified, all the parameters will be shown. -.br -.B Examples: -.br -.B -# lctl list_param ost.* -.br - ost.OSS -.br - ost.num_refs -.br -.B -# lctl list_param -F ost.* debug -.br - ost.OSS/ -.br - ost.num_refs -.br - debug= -.br -.B -# lctl list_param -R mdt -.br - mdt -.br - mdt.lustre-MDT0000 -.br - mdt.lustre-MDT0000.capa -.br - mdt.lustre-MDT0000.capa_count -.br - mdt.lustre-MDT0000.capa_key_timeout -.br - mdt.lustre-MDT0000.capa_timeout -.br - mdt.lustre-MDT0000.commit_on_sharing -.br - mdt.lustre-MDT0000.evict_client -.br - ... -.TP -.BI get_param " [-n|-N|-F] " -Get the value of Lustre or LNET parameter. -.br -.B -n -Print only the value and not parameter name. -.br -.B -N -Print only matched parameter names and not the values. (Especially useful when using patterns.) -.br -.B -F -When -N specified, add '/', '@' or '=' for directories, symlinks and writeable files, respectively. -.br -.B Examples: -.br -.B -# lctl get_param ost.* -.br - ost.OSS -.br - ost.num_refs -.br -.B -# lctl get_param -n debug timeout -.br - super warning dlmtrace error emerg ha rpctrace vfstrace config console -.br - 20 -.br -.B -# lctl get_param -N ost.* debug -.br - ost.OSS -.br - ost.num_refs -.br - debug -.br -lctl "get_param -NF" is equivalent to "list_param -F". -.TP -.BI set_param " [-n] [-P] [-d] " -Set the value of Lustre or LNET parameter. -.br -.B -n -Disable printing of the key name when printing values. -.br -.B -P -Set the parameter permanently, filesystem-wide. -This parameters are only visible to 2.5.0 and later clients, older clients will not see these parameters. -.br -.B -d -Remove the permanent setting (only with -P option) -.br -.B Examples: -.br -.B -# lctl set_param fail_loc=0 timeout=20 -.br - fail_loc=0 -.br - timeout=20 -.br -.B -# lctl set_param -n fail_loc=0 timeout=20 -.br - 0 -.br - 20 -.br -.B -# lctl set_param -P osc.*.max_dirty_mb=32 -.br .TP .BI conf_param " [-d] .=" Set a permanent configuration parameter for any device via the MGS. This command must be run on the MGS node. .br .B -d . -Delete a parameter setting (use the default value at the next restart). A null value for also deletes the parameter setting. +Delete a parameter setting (use the default value at the next restart). +A null value for also deletes the parameter setting. This is +useful if an incorrect or obsolete parameter is in the configuration. .br .B Parameters: .br -All of the writable parameters under +All of the writable parameters under .B lctl list_param -(e.g. +(e.g. .I lctl list_param -F osc.*.* | grep = ) can be permanently set using .B lctl conf_param @@ -243,167 +128,290 @@ All of the writable parameters under Additionally, failover nodes may be added (or removed), and some system-wide parameters may be set as well (sys.at_max, sys.at_min, sys.at_extra, sys.at_early_margin, sys.at_history, sys.timeout, sys.ldlm_timeout.) is ignored for system wide parameters. .br .B Examples: -.br +.br # lctl conf_param testfs.sys.at_max=1200 .br -# lctl conf_param testfs.llite.max_read_ahead_mb=16 +# lctl conf_param testfs.llite.max_read_ahead_mb=16 .br # lctl conf_param testfs-MDT0000.lov.stripesize=2M .br -# lctl conf_param lustre-OST0001.osc.active=0 +# lctl conf_param lustre-OST0001.osc.active=0 .br -# lctl conf_param testfs-OST0000.osc.max_dirty_mb=29.15 +# lctl conf_param testfs-OST0000.osc.max_dirty_mb=29.15 .br -# lctl conf_param testfs-OST0000.ost.client_cache_seconds=15 +# lctl conf_param testfs-OST0000.ost.client_cache_seconds=15 .br # lctl conf_param testfs-OST0000.failover.node=1.2.3.4@tcp1 -.TP -.BI activate -Reactivate an import after deactivating, below. This setting is only effective until the next restart (see +.br +# lctl conf_param -d testfs-OST0000.bad_param +.TP +.BI activate +Reactivate an import after deactivating, below. This setting is only effective until the next restart (see .B conf_param ). -.TP -.BI deactivate +.TP +.BI deactivate Deactivate an import, in particular meaning do not assign new file stripes to an OSC. This command should be used on the OSC in the MDT LOV corresponding to a failed OST device, to prevent further attempts at communication with the failed OST. -.TP -.BI abort_recovery -Abort the recovery process on a restarting MDT or OST device -.PP -.SS Virtual Block Device Operation -Lustre is able to emulate a virtual block device upon regular file. It is necessary to be used when you are trying to setup a swap space via file. -.TP -.BI blockdev_attach " " -Attach the lustre regular file to a block device. If the device node is not existent, lctl will create it \- it is recommended to create it by lctl since the emulator uses a dynamical major number. -.TP -.BI blockdev_detach " " -Detach the virtual block device. .TP -.BI blockdev_info " " -Acquire which lustre file was attached to the device node. +.BI abort_recovery +Abort the recovery process on a restarting MDT or OST device .PP .SS Changelogs .TP -.BI changelog_register +.BI changelog_register " [-n]" Register a new changelog user for a particular device. Changelog entries will not be purged beyond any registered users' set point. (See lfs changelog_clear.) +.br +.B -n +Print only the ID of the newly registered user. .TP .BI changelog_deregister " " Unregister an existing changelog user. If the user's "clear" record number is the minimum for the device, changelog records will be purged until the next minimum. .PP +.SS Nodemap +An identity mapping feature that facilitates mapping of client UIDs and GIDs to +local file system UIDs and GIDs, while maintaining POSIX ownership, permissions, +and quota. + +While the nodemap feature is enabled, all client file system access is subject +to the nodemap identity mapping policy, which consists of the 'default' catchall +nodemap, and any user-defined nodemaps. The 'default' nodemap maps all client +identities to 99:99 (nobody:nobody). Administrators can define nodemaps for a +range of client NIDs which map identities, and these nodemaps can be flagged as + 'trusted' so identities are accepted without translation, as well as flagged +as 'admin' meaning that root is not squashed for these nodes. + +Note: In the current phase of implementation, to use the nodemap functionality +you only need to enable and define nodemaps on the MDS. The MDSes must also be +in a nodemap with the admin and trusted flags set. To use quotas with nodemaps, +you must also use set_param to enable and define nodemaps on the OSS (matching +what is defined on the MDS). Nodemaps do not currently persist, unless you +define them with set_param and use the -P flag. Note that there is a hard limit +to the number of changes you can persist over the lifetime of the file system. + +See also: + +.PP +\fBlctl-nodemap-activate\fR(8) +.RS 4 +Activate/deactivate the nodemap feature. +.RE +.PP +\fBlctl-nodemap-add\fR(8) +.RS 4 +Add a new nodemap, to which NID ranges, identities, and properties can be added. +.RE +.PP +\fBlctl-nodemap-del\fR(8) +.RS 4 +Delete an existing nodemap. +.RE +.PP +\fBlctl-nodemap-add-range\fR(8) +.RS 4 +Define a range of NIDs for a nodemap. +.RE +.PP +\fBlctl-nodemap-del-range\fR(8) +.RS 4 +Delete an existing NID range from a nodemap. +.RE +.PP +\fBlctl-nodemap-add-idmap\fR(8) +.RS 4 +Add a UID or GID mapping to a nodemap. +.RE +.PP +\fBlctl-nodemap-del-idmap\fR(8) +.RS 4 +Delete an existing UID or GID mapping from a nodemap. +.RE +.PP +\fBlctl-nodemap-modify\fR(8) +.RS 4 +Modify a nodemap property. +.RE +.PP +\fBlctl-nodemap-set-fileset\fR(8) +.RS 4 +Add a fileset to a nodemap. +.RE +.PP +\fBlctl-nodemap-set-sepol\fR(8) +.RS 4 +Set SELinux policy info on a nodemap. +.RE +.SS Configuration logs +.TP +.BI clear_conf " " +This command runs on MGS node having MGS device mounted with -o +nosvc. It cleans up configuration files stored in the CONFIGS/ directory +of any records marked SKIP. If the device name is given, then the +specific logs for that filesystem (e.g. testfs-MDT0000) is processed. +Otherwise, if a filesystem name is given then all configuration files for the +specified filesystem are cleared. +.PP .SS LFSCK -An on-line Lustre consistency check and repair tool. -.TP -.B lfsck_start \fR<-M | --device [MDT,OST]_device> - \fR[-e | --error ] - \fR[-h | --help] - \fR[-n | --dryrun ] - \fR[-r | --reset] - \fR[-s | --speed ] - \fR[-A | --all] - \fR[-t | --type ] - \fR[-w | --windows ] - \fR[-o | --orphan] -.br +An on-line Lustre consistency check and repair tool. It is used for totally +replacing the old lfsck tool for kinds of Lustre inconsistency verification, +including: corrupted or lost OI mapping, corrupted or lost link EA, corrupted +or lost FID in name entry, dangling name entry, multiple referenced name entry, +unmatched MDT-object and name entry pairs, orphan MDT-object, incorrect +MDT-object links count, corrupted namespace, corrupted or lost lov EA, lost +OST-object, multiple referenced OST-object, unmatched MDT-object and OST-object +pairs, orphan OST-object, and so on. + +See also: + +.PP +\fBlctl-lfsck-start\fR(8) +.RS 4 Start LFSCK on the specified MDT or OST device with specified parameters. -.TP - -M, --device -The MDT or OST device to start LFSCK/scrub on. -.TP - -e, --error -With error_handle as 'abort' LFSCK will stop if a repair is impossible. If no -value is specified, the saved value will be used if resuming from a checkpoint. -Otherwise the default behavior is to 'continue' if a repair is impossible. -.TP - -h, --help -Show this help. -.TP - -n, --dryrun -Perform a trial run with no changes made. Default is 'off' -.TP - -r, --reset -Set the current position of object iteration to the beginning of the specified -MDT. By default the iterator will resume scanning from the last checkpoint -(saved periodically by LFSCK) provided it is available. -.TP - -s, --speed -Set the upper limit of LFSCK processing in objects per second. If no value is -specified the saved value is used (if resuming from a check point). Otherwise -the default value of 0 is used. 0 means run as fast as possible. -.TP - -A, --all -Start LFSCK on all devices. -.TP - -t, --type -The type of LFSCK checking/repair to execute. By default, the LFSCK -component(s) which ran last time and did not finish or the component(s) -corresponding to some known system inconsistency, will be started. Anytime -LFSCK is triggered on an ldiskfs MDT or OST, the OI Scrub is executed. -Alternative types include FID-in-dirent and linkEA (namespace) and MDT-OST -inconsistency (layout). -.TP - -w, --windows -The window size for async requests pipeline. -.TP - -o, --orphan -Handle orphan objects, such as orphan OST-objects for layout LFSCK. -.TP -.B lfsck_stop \fR<-M | --device [MDT,OST]_device> - \fR[-A | --all] - \fR[-h | --help] +.RE +.PP +\fBlctl-lfsck-stop\fR(8) +.RS 4 Stop LFSCK on the specified MDT or OST device. -.TP - -M, --device <[MDT,OST]_device> -The MDT or OST device to stop LFSCK/scrub on. -.TP - -A, --all -Stop LFSCK on all devices. -.TP - -h, --help -Show this help. +.RE +.PP +\fBlctl-lfsck-query\fR(8) +.RS 4 +Get the LFSCK global status via the specified MDT device. +.RE + +.SS BARRIER +The tools set for write (modify) barrier on all MDTs. For detail, please see: +.PP +\fBlctl-barrier\fR(8) +.RS 4 + +.SS SNAPSHOT +ZFS backend based snapshot tools set. The tool loads system configuration +from the file +.B /etc/ldev.conf +on the MGS, and call related ZFS commands to +maintain Lustre snapshot pieces on all targets (MGS/MDT/OST). +The configuration file +.B /etc/ldev.conf +is not only for snapshot, but also +for other purpose. The format is: + foreign/-