-.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
.br
.B lctl --device <devno> <command [args]>
.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 <up/down>
-,
-.B list_nids
-,
+.BR dl ,
+.BR dk ,
+.BR device ,
+.B network
+.IR <up/down> ,
+.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 " <up/down>|<tcp/elan/myrinet>"
+.BR network " <" up / down >|< tcp / o2ib >
Start or stop LNET, or select a network type for other
.I lctl
LNET commands
From a list of nids for a remote node, show which interface communication
will take place on.
.TP
-.BI replace_nids " <devicename> <nid1>[,nid2,nid3 ...]"
+.BI replace_nids " <devicename> <nid1>[,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.
mount -t lustre <MDT partition> -o nosvc <mount point>
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 " <nid> "
+.BI ping " <nid> 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 " <devname> "
-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 " <devname> "
+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] <param_search ...>"
-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] <parameter ...>"
-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] <parameter=value ...>"
-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] <device|fsname>.<parameter>=<value>"
Set a permanent configuration parameter for any device via the MGS. This
command must be run on the MGS node.
.br
.B -d <device|fsname>.<parameter>
-Delete a parameter setting (use the default value at the next restart). A null value for <value> also deletes the parameter setting.
+Delete a parameter setting (use the default value at the next restart).
+A null value for <value> 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
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.) <device> 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 " <file name> <device node>"
-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 " <device node>"
-Detach the virtual block device.
.TP
-.BI blockdev_info " <device node>"
-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 " <id>"
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 " <device|fsname>"
+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 <error_handle>]
- \fR[-h | --help]
- \fR[-n | --dryrun <switch>]
- \fR[-r | --reset]
- \fR[-s | --speed <speed_limit>]
- \fR[-A | --all]
- \fR[-t | --type <lfsck_type[,lfsck_type...]>]
- \fR[-w | --windows <win_size>]
- \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 <MDT,OST_device>
-The MDT or OST device to start LFSCK/scrub on.
-.TP
- -e, --error <error_handle>
-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 <on|off>
-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 <speed_limit>
-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 <lfsck_type[,lfsck_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:
+ <host> foreign/- <label> <device> [journal-path]/- [raidtab]
+
+The format of
+.I <label>
+is:
+ fsname-<role><index> or <role><index>
+
+The format of
+.I <device>
+is:
+ [md|zfs:][pool_dir/]<pool>/<filesystem>
+
+Snapshot only uses the fields <host>, <label> and <device>.
+
+.br
+.B Example:
+.br
+.B
+# cat /etc/ldev.conf
+.br
+ host-mdt1 - myfs-MDT0000 zfs:/tmp/myfs-mdt1/mdt1
+ host-mdt2 - myfs-MDT0001 zfs:myfs-mdt2/mdt2
+ host-ost1 - OST0000 zfs:/tmp/myfs-ost1/ost1
+ host-ost2 - OST0001 zfs:myfs-ost2/ost2
+
+See also:
+
+.PP
+\fBlctl-snapshot-create\fR(8)
+.RS 4
+Create snapshot with the given name.
+.RE
+.PP
+\fBlctl-snapshot-destroy\fR(8)
+.RS 4
+Destroy the specified snapshot.
+.RE
+.PP
+\fBlctl-snapshot-modify\fR(8)
+.RS 4
+Modify the specified snapshot.
+.RE
+.PP
+\fBlctl-snapshot-list\fR(8)
+.RS 4
+Query the snapshot information.
+.RE
+.PP
+\fBlctl-snapshot-mount\fR(8)
+.RS 4
+Mount the specified snapshot.
+.RE
+.PP
+\fBlctl-snapshot-umount\fR(8)
+.RS 4
+Umount the specified snapshot.
+.RE
+
.SS Debug
-.TP
-.BI debug_daemon
+.TP
+.BI debug_daemon
Start and stop the debug daemon, and control the output filename and size.
-.TP
-.BI debug_kernel " [file] [raw]"
+.TP
+.BI debug_kernel " [file] [raw]"
Dump the kernel debug buffer to stdout or file.
-.TP
+.TP
.BI debug_file " <input> [output]"
Convert kernel-dumped debug log from binary to plain text format.
-.TP
-.BI clear
+.TP
+.BI clear
Clear the kernel debug buffer.
-.TP
-.BI mark " <text>"
+.TP
+.BI mark " <text>"
Insert marker text in the kernel debug buffer.
-.TP
-.BI filter " <subsystem id/debug mask>"
+.TP
+.BI filter " <subsystem id/debug mask>"
Filter kernel debug messages by subsystem or mask.
-.TP
-.BI show " <subsystem id/debug mask>"
+.TP
+.BI show " <subsystem id/debug mask>"
Show specific type of messages.
-.TP
-.BI debug_list " <subs/types>"
+.TP
+.BI debug_list " <subs/types>"
List all the subsystem and debug types.
.TP
-.BI modules " <path>"
+.BI modules " <path>"
Provide gdb-friendly module information.
.SH OPTIONS
-The following options can be used to invoke lctl.
+The following options can be used to invoke lctl.
.TP
-.B --device
+.B --device
The device to be used for the operation. This can be specified by name or
-number. See
+number. See
.B device_list
.TP
-.B --ignore_errors | ignore_errors
+.B --ignore_errors | ignore_errors
Ignore errors during script processing
+.TP
+.B lustre_build_version
+Output the build version of the Lustre kernel modules
+.TP
+.B --version
+Output the build version of the lctl utility
+.TP
+.B --list-commands
+Output a list of the commands supported by the lctl utility
+.TP
+.B help
+Provides brief help on the various arguments
+.TP
+.B exit/quit
+Quit the interactive lctl session
.SH EXAMPLES
# lctl
.SH AVAILABILITY
.B lctl
-is part of the
-.BR Lustre (7)
+is part of the
+.BR lustre (7)
filesystem package.
.SH SEE ALSO
-.BR Lustre (7),
+.BR lustre (7),
.BR mkfs.lustre (8),
.BR mount.lustre (8),
.BR lctl (8),
+.BR lctl-barrier (8),
+.BR lctl-lcfg (8),
+.BR lctl-get_param (8),
+.BR lctl-lfsck-start (8),
+.BR lctl-lfsck-stop (8),
+.BR lctl-lfsck-query (8),
+.BR lctl-list_param (8),
+.BR lctl-set_param (8),
+.BR lctl-snapshot-create (8),
+.BR lctl-snapshot-destroy (8),
+.BR lctl-snapshot-modify (8),
+.BR lctl-snapshot-list (8),
+.BR lctl-snapshot-mount (8),
+.BR lctl-snapshot-umount (8),
+.BR lctl-llog_catlist (8),
+.BR lctl-llog_info (8),
+.BR lctl-llog_print (8),
+.BR lctl-network (8),
+.BR lctl-nodemap-activate (8),
+.BR lctl-nodemap-add-idmap (8),
+.BR lctl-nodemap-add-range (8),
+.BR lctl-nodemap-add (8),
+.BR lctl-nodemap-del-idmap (8),
+.BR lctl-nodemap-del-range (8),
+.BR lctl-nodemap-del (8),
+.BR lctl-nodemap-modify (8),
+.BR lctl-pcc (8),
.BR lfs (1)
git://git.whamcloud.com / fs / lustre-release.git / blobdiff