X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=lustre%2Fdoc%2Flctl.8;h=7954b7ca5feebdb5923c1f873b9f5994ef005ce5;hb=09427dbf40ca6895e8f9a78324eec0a048a98684;hp=fca7631bd2e742ecb6949ece5d6fbf666454090a;hpb=2c74bfcb7a06addb42e79c1f561afb0acfaaa7d0;p=fs%2Flustre-release.git diff --git a/lustre/doc/lctl.8 b/lustre/doc/lctl.8 index fca7631..7954b7c 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,121 +59,482 @@ 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 ping " " +.BI replace_nids " [,nid2,nid3 ...]" +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. +Only MGS server should be started (command execution returns error +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'. +.TP +.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 conf_param " " +.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 " [-F|-n|-N|-R] " +Get the value of Lustre or LNET parameter. +.br +.B -F +When -N specified, add '/', '@' or '=' for directories, symlinks and writeable files, respectively. +.br +.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 -R +Print all of the parameter names below the specified name. +.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 "set_param -F " +.br +Apply configuration file specified by +.br +File is in YAML format, created as an output from +\fBlctl --device MGS llog_print -client\fR or any other valid +llog_file from the output of \fBlctl --device MGS llog_catlist\fR +.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. -.TP -.BI activate -Reactivate an import after deactivating, below. -.TP -.BI deactivate +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. This is +useful if an incorrect or obsolete parameter is in the configuration. +.br +.B Parameters: +.br +All of the writable parameters under +.B lctl list_param +(e.g. +.I lctl list_param -F osc.*.* | grep = +) can be permanently set using +.B lctl conf_param +, but the format is slightly different. For conf_param, the device is specified first, then the obdtype. (See examples below.) Wildcards are not supported. +.br +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 +# lctl conf_param testfs.sys.at_max=1200 +.br +# 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 +.br +# lctl conf_param testfs-OST0000.osc.max_dirty_mb=29.15 +.br +# lctl conf_param testfs-OST0000.ost.client_cache_seconds=15 +.br +# lctl conf_param testfs-OST0000.failover.node=1.2.3.4@tcp1 +.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 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. +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 +.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. 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. +.RE .PP +\fBlctl-lfsck-stop\fR(8) +.RS 4 +Stop LFSCK on the specified MDT or OST device. +.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/-