umount

title: umount(8)

summary: unmount filesystems

text:
# umount(8)

## NAME
umount - unmount filesystems

## SYNOPSIS
umount -a [-dflnrv] [-t fstype] [-O option...]

umount [-dflnrv] {directory|device}

umount -h|-V

## DESCRIPTION
The umount command detaches the mentioned filesystem(s) from the file hierarchy. A filesystem is specified by giving the directory where it has been mounted. Giving the special device on which the filesystem lives may also work, but is obsolete, mainly because it will fail in case this device was mounted on more than one directory.

Note that a filesystem cannot be unmounted when it is 'busy' - for example, when there are open files on it, or when some process has its working directory there, or when a swap file on it is in use. The offending process could even be umount itself - it opens libc, and libc in its turn may open for example locale files. A lazy unmount avoids this problem, but it may introduce other issues. See --lazy description below.

## OPTIONS
-a, --all

All of the filesystems described in /proc/self/mountinfo (or in deprecated /etc/mtab) are unmounted, except the proc, devfs, devpts, sysfs, rpc_pipefs and nfsd filesystems. This list of the filesystems may be replaced by --types umount option.

-A, --all-targets

Unmount all mountpoints in the current mount namespace for the specified filesystem. The filesystem can be specified by one of the mountpoints or the device name (or UUID, etc.). When this option is used together with --recursive, then all nested mounts within the filesystem are recursively unmounted. This option is only supported on systems where /etc/mtab is a symlink to /proc/mounts.

-c, --no-canonicalize

Do not canonicalize paths. The paths canonicalization is based on stat(2) and readlink(2) system calls. These system calls may hang in some cases (for example on NFS if server is not available). The option has to be used with canonical path to the mount point. This option is silently ignored by umount for non-root users.

For more details about this option see the mount(8) man page. Note that umount does not pass this option to the /sbin/umount.type helpers.

-d, --detach-loop

When the unmounted device was a loop device, also free this loop device. This option is unnecessary for devices initialized by mount(8), in this case "autoclear" functionality is enabled by default.

--fake

Causes everything to be done except for the actual system call or umount helper execution; this 'fakes' unmounting the filesystem. It can be used to remove entries from the deprecated /etc/mtab that were unmounted earlier with the -n option.

-f, --force

Force an unmount (in case of an unreachable NFS system). Note that this option does not guarantee that umount command does not hang. It’s strongly recommended to use absolute paths without symlinks to avoid unwanted readlink(2) and stat(2) system calls on unreachable NFS in umount.

-i, --internal-only

Do not call the /sbin/umount.filesystem helper even if it exists. By default such a helper program is called if it exists.

-l, --lazy

Lazy unmount. Detach the filesystem from the file hierarchy now, and clean up all references to this filesystem as soon as it is not busy anymore. A system reboot would be expected in near future if you’re going to use this option for network filesystem or local filesystem with submounts. The recommended use-case for umount -l is to prevent hangs on shutdown due to an unreachable network share where a normal umount will hang due to a downed server or a network partition. Remounts of the share will not be possible.

-N, --namespace ns

Perform umount in the mount namespace specified by ns. ns is either PID of process running in that namespace or special file representing that namespace. umount switches to the namespace when it reads /etc/fstab, writes /etc/mtab (or writes to /run/mount) and calls umount(2) system call, otherwise it runs in the original namespace. It means that the target mount namespace does not have to contain any libraries or other requirements necessary to execute umount(2) command.

See mount_namespaces(7) for more information.

-n, --no-mtab

Unmount without writing in /etc/mtab.

-O, --test-opts option...

Unmount only the filesystems that have the specified option set in /etc/fstab. More than one option may be specified in a comma-separated list. Each option can be prefixed with no to indicate that no action should be taken for this option.

-q, --quiet

Suppress "not mounted" error messages.

-R, --recursive

Recursively unmount each specified directory. Recursion for each directory will stop if any unmount operation in the chain fails for any reason. The relationship between mountpoints is determined by /proc/self/mountinfo entries. The filesystem must be specified by mountpoint path; a recursive unmount by device name (or UUID) is unsupported. Since version 2.37 it umounts also all over-mounted filesystems (more filesystems on the same mountpoint).

-r, --read-only

When an unmount fails, try to remount the filesystem read-only.

-t, --types type...

Indicate that the actions should only be taken on filesystems of the specified type. More than one type may be specified in a comma-separated list. The list of filesystem types can be prefixed with no to indicate that no action should be taken for all of the mentioned types. Note that umount reads information about mounted filesystems from kernel (/proc/mounts) and filesystem names may be different than filesystem names used in the /etc/fstab (e.g., "nfs4" vs. "nfs").

-v, --verbose

Verbose mode.

-h, --help

Display help text and exit.

-V, --version

Print version and exit.

## NON-SUPERUSER UMOUNTS
Normally, only the superuser can umount filesystems. However, when fstab contains the user option on a line, anybody can umount the corresponding filesystem. For more details see mount(8) man page.

Since version 2.34 the umount command can be used to perform umount operation also for fuse filesystems if kernel mount table contains user’s ID. In this case fstab user= mount option is not required.

Since version 2.35 umount command does not exit when user permissions are inadequate by internal libmount security rules. It drops suid permissions and continue as regular non-root user. This can be used to support use-cases where root permissions are not necessary (e.g., fuse filesystems, user namespaces, etc).

## LOOP DEVICE
The umount command will automatically detach loop device previously initialized by mount(8) command independently of /etc/mtab.

In this case the device is initialized with "autoclear" flag (see losetup(8) output for more details), otherwise it’s necessary to use the option --detach-loop or call losetup -d device. The autoclear feature is supported since Linux 2.6.25.

## EXTERNAL HELPERS
The syntax of external unmount helpers is:

umount.suffix {directory|device} [-flnrv] [-N namespace] [-t type.subtype]

where suffix is the filesystem type (or the value from a uhelper= or helper= marker in the mtab file). The -t option can be used for filesystems that have subtype support. For example:

umount.fuse -t fuse.sshfs

A uhelper=something marker (unprivileged helper) can appear in the /etc/mtab file when ordinary users need to be able to unmount a mountpoint that is not defined in /etc/fstab (for example for a device that was mounted by udisks(1)).

A helper=type marker in the mtab file will redirect all unmount requests to the /sbin/umount.type helper independently of UID.

Note that /etc/mtab is currently deprecated and helper= and other userspace mount options are maintained by libmount.

## ENVIRONMENT
LIBMOUNT_FSTAB=<path>

overrides the default location of the fstab file (ignored for suid)

LIBMOUNT_DEBUG=all

enables libmount debug output

## FILES
/etc/mtab

table of mounted filesystems (deprecated and usually replaced by symlink to /proc/mounts)

/etc/fstab

table of known filesystems

/proc/self/mountinfo

table of mounted filesystems generated by kernel.

## HISTORY
A umount command appeared in Version 6 AT&T UNIX.

## SEE ALSO
umount(2), losetup(8), mount_namespaces(7), mount(8)

## REPORTING BUGS
For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>.

## AVAILABILITY
The umount command is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.


mpt-status

package: mpt-status

title: mpt-status(8)

text:
# mpt-status(8)

## NAME
mpt-status - retrieve configuration and health status from LSI hardware RAID controllers

## SYNOPSIS
mpt-status [ options ]

## DESCRIPTION
The mpt-status software is a query tool to access the running configuration and status of LSI SCSI HBAs. mpt-status allows you to monitor the health and status of your RAID setup.

## OPTIONS
--autoload

This will try to automatically load the mptctl kernel module.

-u --controller <int>

Set the IOC unit (controller).

-h --help

Print some help information.

-n --newstyle

Use the new style output. This parameter was introduced to retain backwards compatibility. If not set, you get the old style output. It is very likely that the output of the newstyle format will change heavily in the future, so do not rely on it when writing plugins for monitoring software, for example.

-i --set_id <int>

Set id of primary device (check README).

-p --probe_id

Use this to probe SCSI id's when not on id 0.

-q --quiet

Do not display any warnings.

-s --status_only

Only print the status information. This can be used for easy scripting

-v --verbose

Print verbose information, such as warnings

-V --version

Print version information

-d --debug [<int>]

Enable debugging and set level optionally. NOTE: This is not fully implemented yet.

## DIAGNOSTICS
The program's exit(2) status is meant to be interpreted as a bit mask. If everything went well, zero is returned. If not (i.e. if for example an error or unknown condition is detected), the bits of the return value shall be interpreted as:

Bit

Value

Meaning

0

1

Abnormal condition / unknown error

1

2

A logical volume has failed

2

4

A logical volume is degraded

3

8

A logical volume is resyncing

4

16

At least one physical disk failed

5

32

At least one physical disk is in warning condition

## REPORTING BUGS
Report bugs to your linux distribution or software vendor, if mpt-status was bundled on your installation. If you have been compiling mpt-status from the vanilla sources and experience problems, redirect them to preferably <ratz@drugphish.ch> or <rnibali@pyx.ch>.

## BUGS
Besides design bugs, gross software engineering and missing features, this software is considered pretty stable and can be used in production environments.

## FILES
/dev/mptctl

## SEE ALSO
LSI Logic provides CLI tools for megaraid controllers which you can find on their webpage, following http://www.lsil.com/cm/DownloadSearch.do

## AUTHOR
mpt-status was written by Roberto Nibali <ratz@drugphish.ch>.

This manual page was written by Steffen Joeris <steffen.joeris@skolelinux.de>, for the Debian project (but may be used by others).


mstpctl

package: mstpd

title: mstpctl(8)

summary: mstpd configuration

text:
# mstpctl(8)

## NAME
mstpctl - mstpd configuration

## SYNOPSIS
mstpctl [command]

## DESCRIPTION
mstpctl is used to configure Multiple Spanning Tree daemon (mstpd). MSTPCTL is used for configuring STP parameters on bridges which have user-space STP enabled. Currently, STP is disabled by default on the bridge. To enable user-space STP, configure "brctl stp <bridge> on" or "ip link set <bridge> type bridge stp_state 1" while ensuring that /sbin/bridge-stp kernel helper script will return success (0) for this operation.

## SPANNING TREE PROTOCOL CONFIGURATION
mstpctl(8) can be used for configuring certain spanning tree protocol parameters. For an explanation of these parameters, see the IEEE 802.1D-2004 and 802.1Q-2005(-2011) standards.

mstpctl setmaxage <bridge> <max_age> sets the <bridge>'s 'maximum age' to <max_age> seconds, default is 20.

mstpctl setfdelay <bridge> <time> sets the <bridge>'s 'forward delay' to <time> seconds, default is 15.

mstpctl setmaxhops <bridge> <max_hops> sets the <bridge>'s 'maximum hops' to <max_hops>, default is 20.

mstpctl setforcevers <bridge> {mstp|rstp|stp} forces the <bridge> to use specific STP protocol version. mstp is the default.

mstpctl settxholdcount <bridge> <tx_hold_count> sets the <bridge>'s 'transmit hold count' to <tx_hold_count>.

mstpctl settreeprio <bridge> <mstid> <priority> set <bridge>'s priority for the tree with id = <mstid>, <priority> is between 0 and 15. Bridge priority affects bridge id, lowest priority bridge will be the (regional) root. Note that traditionally bridge priority is a multiple of 4096 and ranges from 0 to 15*4096 = 61440. mstpd is different - it throws out that useless "multiple of 4096" rule and expresses bridge priority in natural units (0-15). Default is 8.

mstpctl setportpathcost <bridge> <port> <cost> sets the port cost of the <port> in <bridge> to <cost>. Default is 0 (= auto).

mstpctl setportadminedge <bridge> <port> {yes|no} Enables/disables the admin edge state of the <port> in <bridge>, default is no.

mstpctl setportautoedge <bridge> <port> {yes|no} Enables/disables the auto transition to/from edge state of the <port> in <bridge>, default is yes.

mstpctl setportp2p <bridge> <port> {yes|no|auto} Enables/disables the point2point detection mode of the <port> in <bridge>, default is auto.

mstpctl setportrestrrole <bridge> <port> {yes|no} Enables/disables the restrictions on the <port>'s ability to take root role in <bridge>, default is no (i.e. no restrictions on the port's role).

mstpctl setportrestrtcn <bridge> <port> {yes|no} Enables/disables the restrictions on the <port>'s ability to propagate received topology change notification in <bridge>, default is no (i.e. no restrictions on the TCN propagation).

mstpctl setbpduguard <bridge> <port> {yes|no} Enables/disables the bpduguard configuration of the <port> in <bridge>, default is no.

mstpctl settreeportprio <bridge> <port> <mstid> <priority> sets the <port>'s priority in <bridge> to <priority> for the MSTI with id = <mstid>. The priority value is a number between 0 and 15. Note that traditionally port priority is a multiple of 16 and ranges from 0 to 15*16 = 240. mstpd is different - it throws out that useless "multiple of 16" rule and expresses port priority in natural units (0-15). Default is 8.

mstpctl sethello <bridge> <time> sets the <bridge>'s 'hello time' to <time> seconds, default is 2.

mstpctl setageing <bridge> <time> sets the ethernet (MAC) address ageing <time>, in seconds, for the <bridge>. Used only when protocol version is forced to STP, default is 300s. Note that this parameter differs from the other ones: it is only informational parameter. By setting it in the mstpd one do not change the real bridge's Ageing Time; it is supposed to be set as information to the mstpd that real Ageing Time in the real bridge was changed.

mstpctl setportnetwork <bridge> <port> {yes|no} Enables/disables the bridge assurance capability for a <port> in <bridge>, default is no.

mstpctl setportbpdufilter <bridge> <port> {yes|no} Enables/disables the BPDU filter capability for a port <port> in bridge <bridge>, i.e. discard any ingress BPDUs and do not issue any BPDUs for this port. The default is no.

## SPANNING TREE PROTOCOL SHOW COMMANDS
mstpctl showbridge [<bridge>] will show information of the <bridge>'s CIST instance. If <bridge> parameter is omitted - shows info for all bridges.

mstpctl showport <bridge> [<port>] will show short (one-line) information about the <port> of the <bridge>'s CIST instance. If <port> parameters is omitted - shows info for all ports.

mstpctl showportdetail <bridge> [<port>] will show detailed information about the <port> of the <bridge>'s CIST instance. If <port> parameters is omitted - shows info for all ports.

mstpctl showtree <bridge> <mstid> will show information of the <bridge>'s MST instance with id = <mstid>.

mstpctl showtreeport <bridge> <port> <mstid> will show detailed information about the <port> of the <bridge>'s MST instance with id = <mstid>.

## SEE ALSO
brctl(8) ip(8)

## AUTHOR
The source code for mstpctl was written by Vitalii Demianets <dvitasgs@gmail.com>. This manpage was written by Satish Ashok <sashok@cumulusnetworks.com> based on brctl(8).


sulogin

package: msulogin

title: sulogin(8)

summary: the single user mode login program

text:
# sulogin(8)

## NAME
sulogin - the single user mode login program

## SYNOPSIS
sulogin [-p] [-t timeout]

## DESCRIPTION
sulogin is a program to force the console user to login under a root account before a shell is started. Unlike other implementations of sulogin, this one supports having multiple root accounts on a system.

sulogin is typically invoked from an inittab(5) entry for single user mode or from the system's startup scripts.

It is important to understand that the use of sulogin alone may be insufficient to prevent unauthorized access to the system from the console. The firmware (BIOS) and the boot loader may by default provide user interaction capabilities that enable access to the system bypassing its regular startup.

## OPTIONS
The supported command line options match those used with Miquel van Smoorenburg's implementation of sulogin.

-p

Make the shell started by sulogin a login shell by setting the first character of its argument zero to a dash ('-'). Typically, a login shell will process local profile files such as /etc/profile.

-t timeout

Request that sulogin will timeout and exit if there's no input to a prompt in the specified number of seconds.

## EXIT CODE
The exit code of sulogin upon its successful completion is that of the shell started. Other possible exit codes are: 64 on system failure or misconfiguration, 65 on timeout, and 66 on EOF (Ctrl-D).

## HISTORY
Implementations of sulogin exist in multiple commercial and free Unix flavors, although sulogin was not a part of AT&T System V.

This implementation with its support for multiple root accounts originates in Openwall GNU/*/Linux.

## AUTHORS
Solar Designer <solar at owl.openwall.com>

## SEE ALSO
inittab(5), init(8)

http://www.openwall.com/msulogin/


stinit

package: mt-st

title: stinit(8)

summary: initialize SCSI magnetic tape drives

text:
# stinit(8)

## NAME
stinit - initialize SCSI magnetic tape drives

## SYNOPSIS
stinit [-f conf-file] [-h] [-p] [-r] [-v] [devices...]

## DESCRIPTION
This manual page documents the tape control program stinit can used to initialize SCSI tape drive modes at system startup, after loading the tape driver as module, or after introduction of new device to the SCSI subsystem at run-time. The initialization is performed by sending ioctl commands to the drive. The commands are defined in a text file that is indexed using the inquiry data the drive returns (manufacturer, device, revision). Values for all of the general and mode-specific SCSI tape parameters up to Linux version 2.6.0 can be initialized.

## OPTIONS
-f conf-file

Specifies the name of the text file containing the definitions for different tape drive types. By default stinit tries to find the definition file stinit.def or /etc/stinit.def (in this order).

-h

Print the usage information.

-p

The definition file is parsed but no tape drive initialization is attempted. This option can be used for testing the integrity of a definition file after changes have been made.

-r

Rewind every device being initialized.

-v

The more -v options (currently up to two), the more verbose output.

--version

Print the program version.

## THE DEVICES BEING INITIALIZED
If the program is started without arguments, it tries to find all accessible SCSI tape devices and the device files for the different modes of the devices. The tape drives are searched in the scanning order of the kernel and searching is stopped at the first non-existing tape. All of the found devices are initialized if a matching description is found from the parameter file. Note that a mode for a device is not initialized if the corresponding device file is not found even if a matching description for the mode exists. The non-rewind device is preferred over the auto-rewind device for each mode. If the directory /dev/tapes is found, the devfs filesystem is assumed to be mounted on /dev. Otherwise, the directories /dev/scsi and /dev are scanned for device files.

SCSI tape drives can be initialized selectively using program arguments. A numeric argument specifies the number of the tape drive in the scanning order of the kernel. A file name specifies that the device corresponding to this name is to be initialized. If the file name is given without the directory specification, the program searches for the name in the device directories /dev/scsi and /dev. Only full path names are supported with devfs.

## THE CONFIGURATION FILE
The configuration file is a simple text file that contains descriptions of tape drives and the corresponding initialization parameters. The parameter definition blocks are delimited by {}. Specification of the drive description is restarted after each parameter definition block.

The drive descriptions and the parameter definitions consist of pairs name = value. The value is either a numeric parameter, a string not containing blanks, or a quoted string. In case of a numeric parameter, the postfix k or M can be used to give the value in units of 1024 or 1024 * 1024, respectively. If the =value -part is omitted, the value "1" is used. If the character # is found from an input line, the rest of the line is discarded. This allows use of comments in the definition file. The following example contains definitions for one type of tape drives:

```
# The XY dat
manufacturer=XY-COMPANY model = "UVW DRIVE" {
scsi2logical=1 # Common definitions for all modes
can-bsr can-partitions auto-lock
# Definition of modes
mode1 blocksize=0 compression=1
mode2 blocksize=1024 compression=1
mode3 blocksize=0 compression=0
mode4 blocksize = 1k compression=0 }
```

The devices are identified using zero or more of the following keywords corresponding to the data returned by the tape device as response to the SCSI INQUIRY command. The matches are case-sensitive and performed up to the length defined in the configuration file (permitting use of partial matches).

manufacturer=

This keyword specifies the string that must match the vendor identification returned by the device.

model=

This keyword defines the string that must match the product identification returned by the device.

revision=

This keyword matched the string that must match the product revision level returned by the device.

All of the matching initializations are collected in the order they are defined in the file. This means that common parameters can be defined for all devices using zero keywords for a definition block. Another consequence is that, for instance, some parameters can be easily given different values for a specific firmware revision without repeating the parameters common to all revisions.

The tape parameters are defined using the following keywords. More thorough description of the parameters can be found from the st(4) man page (not up to date when this is written) or from the file drivers/scsi/README.st in the Linux kernel source tree. The keywords are matched using only the first characters. The part of the keywords not used in matching is enclosed by []. The numeric values may be specified either in decimal notation or hexadecimal notation (using the prefix 0x).

drive-[buffering]=value

The drive's buffering parameter is set to value. This parameter if common for all modes.

cleaning

The cleaning request notifying parameter is set to value

no-w[ait]

The immediate mode is used with commands like rewind if value is non-zero (i.e., the driver does not wait for the command to finish).

mode=value

This keyword starts definition of tape mode value. The number of the mode must be between 1 and 4.

disab[led]=value

This mode is disabled for this device if value is non-zero. Can be used if some mode defined in a more general definition should be disabled by a more specific definition for some device (for example, for a device with buggy firmware level).

block[size]=value

The default tape block size is set to value. bytes. The block size zero means variable block mode.

dens[ity]=value

The tape density code is set to value.

buff[ering]=value

The buffered writes by the driver in fixed block mode are enabled if value is non-zero.

async[-writes]=value

Asynchronous writes by the driver are enabled if value is non-zero.

read[-ahead]=value

Read-ahead by the driver in fixed block mode is allowed if value is non-zero.

two[-fms]=value

Two filemarks are written when a file being written to is closed if value is non-zero. By default, one filemark is written.

comp[ression]=value

Compression of the data by the drive is enabled if value is non-zero. Note that the tape driver can't enable compression for all drives that can compress data. Note also that some drives define compression using density codes.

auto[-lock]=value

The tape drive door is locked automatically when the device file is opened if value is non-zero.

fast[-eom]=value

The MTEOM command is performed using the SCSI command that spaces directly to the end of medium if value is non-zero. The drawback is that the file number in the status becomes invalid. By default, spacing to end of medium is performed by spacing over filemarks until end of medium is detected and the file number remains valid.

can-b[sr]=value

Backspacing over records is used by the driver when repositioning the tape when read-ahead is enabled if value is non-zero.

noblk[limits]=value

The tape driver does not use the READ BLOCK LIMITS SCSI command when the device is being opened if value is non-zero. This is for the drives that do not support this SCSI command.

can-p[artitions]=value

The support for tape partitions is enabled if value is non-zero.

scsi2[logical]=value

Logical block addresses are used in the MTSEEK and MTIOCPOS commands if value is non-zero. The default is to use the device-specific addresses.

sili=value

If value is non-zero, the SILI bit is set when reading in variable block mode. This may speed up reading blocks shorter than the read byte count. Set this only if you know that the drive supports SILI and the HBA reliably returns transfer residual byte counts. Requires kernel version >= 2.6.26.

defs-for-w[rites]=value

The parameters defining the tape format (density, block size, etc.) are forced when writing starts at the beginning of a tape if value is non-zero. The default is to change there parameters each time the device is opened at the beginning of a tape (or the mode is changed in the middle of a tape).

sysv=value

The System V tape semantics are used if value is non-zero. Otherwise the BSD semantics are used.

timeout=value

The normal timeout for the device is set to value seconds.

long-time[out]=value

The long timeout for the device is set to value seconds.

## RETURN VALUE
The program exits with value one if the command line is incorrect, the definition file is not found, or option -p is given and parsing the definition file fails. In all other cases the return value is zero (i.e., failing of initialization is not currently signaled by the return value).

## RESTRICTIONS
With the exception of the -p option, the program can be used only by the superuser. This is because the program uses ioctls allowed only for the superuser.

## AUTHOR
The program is written by Kai Makisara <Kai.Makisara@kolumbus.fi>.

## COPYRIGHT
The program and the manual page are copyrighted by Kai Makisara, 1998-2008. They can be distributed according to the GNU Copyleft.

## SEE ALSO
st(4) mt(1)


lsmtd

package: mtd-utils

title: lsmtd(8)

summary: list memory technology devices

text:
# lsmtd(8)

## NAME
lsmtd - list memory technology devices

## SYNOPSIS
lsmtd [options] [device...]

## DESCRIPTION
lsmtd lists information about all available or the specified MTD and UBI devices. The lsmtd command reads the sysfs filesystem to gather information. Alternatively, the procfs filesystem and ioctl interfaces are used, should the sysfs filesystem not be available.

The command prints all MTD and UBI devices in a pretty-printed list format by default.

The default output is subject to change. So whenever possible, you should avoid using default outputs in your scripts. Always explicitly define expected columns by using --output columns-list in environments where a stable output is required.

Use lsmtd --help to get a list of all available columns.

## OPTIONS
-b, --bytes

Print columns with size quantities (e.g. erase block size) in bytes instead of a human-readable format.

-h, --help

Display a help text and exit.

-i, --ascii

Only use ascii characters for pretty printing.

-J, --json

Use JSON output format. All potentially unsafe characters in string values are escaped with JSON escape sequences or hex-escaped (\u<code>).

-l, --list

Use a pretty-printed list output format (default).

-m, --no-ubi

Do not display information about UBI devices or volumes.

-n, --noheadings

Do not print column headings when using raw or list output format.

-o, --output list

Specify which output columns to print. Use --help to get a list of all supported columns. The default list of columns may be extended if list is specified in the format +list (e.g. lsmtd -o +EB-SIZE).

-O, --output-all

Output all available columns.

-P, --pairs

Produce output in the form of key="value" pairs. All potentially unsafe characters are hex-escaped (\x<code>).

-r, --raw

Produce output in raw format. All potentially unsafe characters are hex-escaped (\x<code>).

-u, --si-units

Display human readable sizes as powers of ten rather than powers of two.

-V, --version

Print version information and exit.

-x, --sort column

Sort output lines by column.

## NOTES
If the --bytes option is not specified, the JSON output format prints sizes as string values even if they do not have a suffix.

## AUTHORS

```
David Oberhollenzer <david.oberhollenzer@sigma-star.at>
```

## REPORTING BUGS
Report mtd-utils bugs to the Linux mtd mailing list.

Linux mtd mailing list: <linux-mtd@lists.infradead.org>

Linux mtd home page: <http://www.linux-mtd.infradead.org/>

## AVAILABILITY
The lsmtd command is part of the mtd-utils package and is available from ftp://ftp.infradead.org/pub/mtd-utils/.

## COPYRIGHT
Copyright © 2017 David Oberhollenzer - sigma star gmbh

License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl2.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

## SEE ALSO
lsblk(8), ls(1)


ubinize

title: ubinize(8)

summary: a tool for generating UBI images

text:
# ubinize(8)

## NAME
ubinize - a tool for generating UBI images

## SYNOPSIS
ubinize [-o filename] [-p <bytes>] [-m <bytes>] [-s <bytes>] [-O <num>] [-e <num>] [-x <num>] [-Q <num>] [-v] [-h] [-V] [--output=<filename>] [--peb-size=<bytes>] [--min-io-size=<bytes>] [--sub-page-size=<bytes>] [--vid-hdr-offset=<num>] [--erase-counter=<num>] [--ubi-ver=<num>] [--image-seq=<num>] [--verbose] [--help] [--version] ini-file

## DESCRIPTION
An UBI image may contain one or more UBI volumes which have to be defined in the input configuration ini-file. The ini file defines all the UBI volumes - their characteristics and the contents, but it does not define the characteristics of the flash the UBI image is generated for. Instead, the flash characteristics are defined via the command-line options. Note, if not sure about some of the command-line parameters, do not specify them and let the utility use default values.

## OPTIONS
-o, --output=file

Specify output file

-p, --peb-size=bytes

Size of the physical eraseblock of the flash this UBI image is created for in bytes, kilobytes (KiB), or megabytes (MiB). This parameter is mandatory.

-m, --min-io-size=bytes

Minimum input/output unit size of the flash in bytes

-s, --sub-page-size=bytes

Minimum input/output unit used for UBI headers, e.g. sub-page size in case of NAND flash (equivalent to the minimum input/output unit size by default).

-O, --vid-hdr-offset=num

Offset if the VID header from start of the physical eraseblock (default is the next minimum I/O unit or sub-page after the EC header)

-e, --erase-counter=num

The erase counter value to put to EC headers (default is 0).

-x, --ubi-ver=num

UBI version number to put to EC headers (default is 1).

-Q, --image-seq=num

32-bit UBI image sequence number to use (by default a random number is picked).

-v, --verbose

Be verbose.

-h, --help

Print a help message and exit.

-V, --version

Print program version and exit.

## EXAMPLE
ubinize -o ubi.img -p 16KiB -m 512 -s 256 cfg.ini

Create UBI image ubi.img as described by configuration file cfg.ini.

A physical erase block on the flash is 16KiB in size and has 512 byte pages with 256 byte sub-pages.

## INI-FILE FORMAT
The input configuration ini-file describes all the volumes which have to be included to the output UBI image. Each volume is described in its own section which may be named arbitrarily. The section consists on "key=value" pairs, for example:

```
[jffs2-volume]
mode=ubi
image=../jffs2.img
vol_id=1
vol_size=30MiB
vol_type=dynamic
vol_name=jffs2_volume
vol_flags=autoresize
vol_alignment=1
```

This example configuration file tells the utility to create an UBI image with one volume with ID 1, volume size 30MiB, the volume is dynamic, has name jffs2_volume, autoresize volume flag, and alignment 1.

The image=../jffs2.img line tells the utility to take the contents of the volume from the ../jffs2.img file. The size of the image file has to be less or equivalent to the volume size (30MiB).

The mode=ubi line is mandatory and just tells that the section describes an UBI volume - other section modes may be added in the future.

Notes:

•

Size in vol_size might be specified kilobytes (KiB), megabytes (MiB), gigabytes (GiB) or bytes (no modifier).

•

If "vol_size" key is absent, the volume size is assumed to be equivalent to the size of the image file (defined by "image" key).

•

If the "image" is absent, the volume is assumed to be empty

•

Volume alignment must not be greater than the logical eraseblock size.

•

One ini file may contain arbitrary number of sections, the utility will put all the volumes which are described by these section to the output UBI image file.

## AUTHORS

```
Man page written by David Oberhollenzer, based on the help text of
the ubinize utility written by Artem Bityutskiy and Oliver Lohmann.
```

## REPORTING BUGS
Report mtd-utils bugs to the Linux mtd mailing list.

Linux mtd mailing list: <linux-mtd@lists.infradead.org>

Linux mtd home page: <http://www.linux-mtd.infradead.org/>

## AVAILABILITY
The ubinize command is part of the mtd-utils package and is available from ftp://ftp.infradead.org/pub/mtd-utils/.

## COPYRIGHT
Copyright © International Business Machines Corp., 2006

Copyright © 2008 Nokia Corporation

Copyright © 2016 sigma star gmbh

License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl2.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

## SEE ALSO
mkfs.jffs2(1)


mtr

package: mtr

title: mtr(8)

summary: a network diagnostic tool

text:
# mtr(8)

## NAME
mtr - a network diagnostic tool

## SYNOPSIS
mtr [-4|-6] [-F FILENAME] [--report] [--report-wide] [--xml] [--gtk] [--curses] [--displaymode MODE] [--raw] [--csv] [--json] [--split] [--no-dns] [--show-ips] [-o FIELDS] [-y IPINFO] [--aslookup] [-i INTERVAL] [-c COUNT] [-s PACKETSIZE] [-B BITPATTERN] [-G GRACEPERIOD] [-Q TOS] [--mpls] [-I NAME] [-a ADDRESS] [-f FIRST-TTL] [-m MAX-TTL] [-U MAX-UNKNOWN] [--udp] [--tcp] [--sctp] [-P PORT] [-L LOCALPORT] [-Z TIMEOUT] [-M MARK] HOSTNAME

## DESCRIPTION
mtr combines the functionality of the traceroute and ping programs in a single network diagnostic tool.

As mtr starts, it investigates the network connection between the host mtr runs on and HOSTNAME by sending packets with purposely low TTLs. It continues to send packets with low TTL, noting the response time of the intervening routers. This allows mtr to print the response percentage and response times of the internet route to HOSTNAME. A sudden increase in packet loss or response time is often an indication of a bad (or simply overloaded) link.

The results are usually reported as round-trip-response times in milliseconds and the percentage of packet loss.

## OPTIONS
-h, --help

Print the summary of command line argument options.

-v, --version

Print the installed version of mtr.

-4

Use IPv4 only.

-6

Use IPv6 only. (IPV4 may be used for DNS lookups.)

-F FILENAME, --filename FILENAME

Reads the list of hostnames from the specified file.

-r, --report

This option puts mtr into report mode. When in this mode, mtr will run for the number of cycles specified by the -c option, and then print statistics and exit.

This mode is useful for generating statistics about network quality.

Note that each running instance of mtr generates a significant amount of network traffic. Using mtr to measure the quality of your network may result in decreased network performance.

-w, --report-wide

This option puts mtr into wide report mode. When in this mode, mtr will not cut hostnames in the report.

-x, --xml

Use this option to tell mtr to use the xml output format. This format is better suited for automated processing of the measurement results.

-t, --curses

Use this option to force mtr to use the curses based terminal interface (if available). In case the list of hops exceeds the height of your terminal, you can use the + and - keys to scroll up and down half a page. Ctrl-L clears spurious error messages that may overwrite other parts of the display.

--displaymode MODE

Use this option to select the initial display mode: 0 (default) selects statistics, 1 selects the stripchart without latency information, and 2 selects the stripchart with latency information.

-g, --gtk

Use this option to force mtr to use the GTK+ based X11 window interface (if available). GTK+ must have been available on the system when mtr was built for this to work. See the GTK+ web page at http://www.gtk.org/ for more information about GTK+.

-l, --raw

Use the raw output format. This format is better suited for archival of the measurement results. It could be parsed to be presented into any of the other display methods.

Example of the raw output format:

```
h 0 10.1.1.1
p 0 339
h 1 46.149.16.4
p 1 530
h 2 172.31.1.16
p 2 531
h 3 82.221.168.236
p 3 1523
h 5 195.130.211.8
p 5 1603
h 6 193.4.58.17
p 6 1127
h 7 193.4.58.17
d 7 www.isnic.is
```

-C, --csv

Use the Comma-Separated-Value (CSV) output format. (Note: The separator is actually a semi-colon ';'.)

Example of the CSV output format:

```
MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;1;r-76520-PROD.greenqloud.internal;288
MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;2;46.149.16.4;2086
MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;3;172.31.1.16;600
MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;4;82.221.168.236;1163
MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;5;???;0
MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;6;rix-k2-gw.isnic.is;1654
MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;7;www.isnic.is;1036
```

-j, --json

Use this option to tell mtr to use the JSON output format. This format is better suited for automated processing of the measurement results. Jansson library must have been available on the system when mtr was built for this to work.

-p, --split

Use this option to set mtr to spit out a format that is suitable for a split-user interface.

-n, --no-dns

Use this option to force mtr to display numeric IP numbers and not try to resolve the host names.

-b, --show-ips

Use this option to tell mtr to display both the host names and numeric IP numbers. In split mode this adds an extra field to the output. In report mode, there is usually too little space to add the IPs, and they will be truncated. Use the wide report (-w) mode to see the IPs in report mode.

-o FIELDS, --order FIELDS

Use this option to specify which fields to display and in which order. You may use one or more space characters to separate fields.

Available fields: L

Loss ratio

D

Dropped packets

R

Received packets

S

Sent Packets

N

Newest RTT(ms)

B

Min/Best RTT(ms)

A

Average RTT(ms)

W

Max/Worst RTT(ms)

V

Standard Deviation

G

Geometric Mean

J

Current Jitter

M

Jitter Mean/Avg.

X

Worst Jitter

I

Interarrival Jitter

Example: -o "LSD NBAW X"

-y n, --ipinfo n

Displays information about each IP hop. Valid values for n are: 0

Display AS number (equivalent to -z)

1

Display IP prefix

2

Display country code of the origin AS

3

Display RIR (ripencc, arin, ...)

4

Display the allocation date of the IP prefix

It is possible to cycle between these fields at runtime (using the y key).

-z, --aslookup

Displays the Autonomous System (AS) number alongside each hop. Equivalent to --ipinfo 0.

Example (columns to the right not shown for clarity):

```
1. AS???   r-76520-PROD.greenqloud.internal
2. AS51969 46.149.16.4
3. AS???   172.31.1.16
4. AS30818 82.221.168.236
5. ???
6. AS???   rix-k2-gw.isnic.is
7. AS1850  www.isnic.is
```

-i SECONDS, --interval SECONDS

Use this option to specify the positive number of seconds between ICMP ECHO requests. The default value for this parameter is one second. The root user may choose values between zero and one.

-c COUNT, --report-cycles COUNT

Use this option to set the number of pings sent to determine both the machines on the network and the reliability of those machines. Each cycle lasts one second.

-s PACKETSIZE, --psize PACKETSIZE

This option sets the packet size used for probing. It is in bytes, inclusive IP and ICMP headers. If set to a negative number, every iteration will use a different, random packet size up to that number.

-B NUM, --bitpattern NUM

Specifies bit pattern to use in payload. Should be within range 0 - 255. If NUM is greater than 255, a random pattern is used.

-G SECONDS, --gracetime SECONDS

Use this option to specify the positive number of seconds to wait for responses after the final request. The default value is five seconds.

-Q NUM, --tos NUM

Specifies value for type of service field in IP header. Should be within range 0 - 255.

-e, --mpls

Use this option to tell mtr to display information from ICMP extensions for MPLS (RFC 4950) that are encoded in the response packets.

-I NAME, --interface NAME

Use the network interface with a specific name for sending network probes. This can be useful when you have multiple network interfaces with routes to your destination, for example both wired Ethernet and WiFi, and wish to test a particular interface.

-a ADDRESS, --address ADDRESS

Use this option to bind the outgoing socket to ADDRESS, so that all packets will be sent with ADDRESS as source address. NOTE that this option doesn't apply to DNS requests (which could be and could not be what you want).

-f NUM, --first-ttl NUM

Specifies with what TTL to start. Defaults to 1.

-m NUM, --max-ttl NUM

Specifies the maximum number of hops (max time-to-live value) traceroute will probe. Default is 30.

-U NUM, --max-unknown NUM

Specifies the maximum unknown host. Default is 5.

-u, --udp

Use UDP datagrams instead of ICMP ECHO.

-T, --tcp

Use TCP SYN packets instead of ICMP ECHO. PACKETSIZE is ignored, since SYN packets can not contain data.

-S, --sctp

Use Stream Control Transmission Protocol packets instead of ICMP ECHO.

-P PORT, --port PORT

The target port number for TCP/SCTP/UDP traces.

-L LOCALPORT, --localport LOCALPORT

The source port number for UDP traces.

-Z SECONDS, --timeout SECONDS

The number of seconds to keep probe sockets open before giving up on the connection. Using large values for this, especially combined with a short interval, will use up a lot of file descriptors.

-M MARK, --mark MARK

Set the mark for each packet sent through this socket similar to the netfilter MARK target but socket-based. MARK is 32 unsigned integer. See socket(7) for full description of this socket option.

## ENVIRONMENT
mtr recognizes a few environment variables.

MTR_OPTIONS

This environment variable allows one to specify options, as if they were passed on the command line. It is parsed before reading the actual command line options, so that options specified in MTR_OPTIONS are overridden by command-line options. Example:

MTR_OPTIONS="-4 -c 1" mtr -6 localhost

would send one probe (because of -c 1) towards ::1 (because of -6, which overrides the -4 passed in MTR_OPTIONS).

MTR_PACKET

A path to the mtr-packet executable, to be used for sending and receiving network probes. If MTR_PACKET is unset, the PATH will be used to search for an mtr-packet executable.

DISPLAY

Specifies an X11 server for the GTK+ frontend.

## INTERACTIVE CONTROL
mtr can be controlled while it is running with the following keys:

?|h help

p pause (SPACE to resume)

d switching display mode

e toggle MPLS information on/off

n toggle DNS on/off

r reset all counters

o str set the columns to display, default str='LRS N BAWV'

j toggle latency(LS NABWV)/jitter(DR AGJMXI) stats

c <n> report cycle n, default n=infinite

i <n> set the ping interval to n seconds, default n=1

f <n> set the initial time-to-live(ttl), default n=1

m <n> set the max time-to-live, default n= # of hops

s <n> set the packet size to n or random(n<0)

b <c> set ping bit pattern to c(0..255) or random(c<0)

Q <t> set ping packet's TOS to t

u switch between ICMP ECHO and UDP datagrams

y switching IP info

z toggle ASN info on/off

q exit

## BUGS
Some modern routers give a lower priority to ICMP ECHO packets than to other network traffic. Consequently, the reliability of these routers reported by mtr will be significantly lower than the actual reliability of these routers.

## CONTACT INFORMATION
For the latest version, see the mtr web page at http://www.bitwizard.nl/mtr/

For patches, bug reports, or feature requests, please open an issue on GitHub at: https://github.com/traviscross/mtr.

## SEE ALSO
mtr-packet(8), traceroute(8), ping(8), socket(7), TCP/IP Illustrated (Stevens, ISBN 0201633469).


mtr-packet

package: mtr-packet

title: mtr-packet(8)

text:
# mtr-packet(8)

## NAME
mtr-packet - send and receive network probes

## DESCRIPTION
mtr-packet is a tool for sending network probes to measure network connectivity and performance. Many network probes can be sent simultaneously by a single process instance of mtr-packet and additional probes can be generated by an instance of mtr-packet which already has network probes in flight. It is intended to be used by programs which invoke it with Unix pipes attached to its standard input and output streams.

mtr-packet reads command requests from stdin, each separated by a newline character, and responds with command replies to stdout, also each separated by a newline character. The syntactic structure of requests and replies are the same. The following format is used:

TOKEN COMMAND [ARGUMENT-NAME ARGUMENT-VALUE ...]

TOKEN is a unique integer value. The same value will be used as the TOKEN for the response. This is necessary for associating replies with requests, as commands may be completed in a different order than they are requested. The invoker of mtr-packet should always use the TOKEN value to determine which command request has completed.

COMMAND is a string identifying the command request type. A common command is send-probe, which will transmit one network probe.

ARGUMENT-NAME strings and ARGUMENT-VALUE strings always come in pairs. It is a syntactic error to provide an ARGUMENT-NAME without a corresponding ARGUMENT-VALUE. Valid ARGUMENT-NAME strings depend on the COMMAND being used.

## REQUESTS
send-probe

Send a network probe to a particular IP address. Either an ip-4 or ip-6 argument must be provided. A valid send-probe command will reply with reply, no-reply, or ttl-expired.

The following arguments may be used:

ip-4 IP-ADDRESS

The Internet Protocol version 4 address to probe.

ip-6 IP-ADDRESS

The Internet Protocol version 6 address to probe.

protocol PROTOCOL

The protocol to use for the network probe. icmp, sctp, tcp, and udp may be used. The default protocol is icmp.

port PORT-NUMBER

The destination port to use for sctp, tcp, or udp probes.

local-ip-4 IP-ADDRESS

The local Internet Protocol version 4 address to use when sending probes.

local-ip-6 IP-ADDRESS

The local Internet Protocol version 6 address to use when sending probes.

local-port PORT-NUMBER

For udp probes, the local port number from which to send probes.

timeout TIMEOUT-SECONDS

The number of seconds to wait for a response to the probe before discarding the probe as lost, and generating a no-reply command reply.

ttl TIME-TO-LIVE

The time-to-live value for the Internet Protocol packet header used in constructing the probe. This value determines the number of network hops through which the probe will travel before a response is generated by an intermediate network host.

size PACKET-SIZE

The size of the packet used to send the probe, in bytes, including the Internet Protocol header and transport protocol header.

bit-pattern PATTERN-VALUE

The packet payload is filled with bytes of the value specified. Valid pattern values are in the range 0 through 255.

tos TYPE-OF-SERVICE

In the case of IPv4, the "type of service" field in the IP header is set to this value. In the case of IPv6, the "traffic class" field is set.

mark ROUTING-MARK

The packet mark value to be used by mark-based routing. (Available only on Linux.)

check-support

Check for support for a particular feature in this version of mtr-packet and in this particular operating environment. check-support will reply with feature-supported. A feature argument is required.

feature FEATURE-NAME

The name of a feature requested.

Some features which can be checked are send-probe, ip-4, ip-6, icmp, sctp, tcp, udp, and mark. The feature version can be checked to retrieve the version of mtr-packet.

## REPLIES
reply

The destination host received the send-probe probe and replied. Arguments of reply are:

ip-4 IP-ADDRESS

The Internet Protocol version 4 address of the host which replied to the probe.

ip-6 IP-ADDRESS

The Internet Protocol version 6 address of the host which replied to the probe.

round-trip-time TIME

The time which passed between the transmission of the probe and its response. The time is provided as a integral number of microseconds elapsed.

no-reply

No response to the probe request was received before the timeout expired.

ttl-expired

The time-to-live value of the transmitted probe expired before the probe arrived at its intended destination. Arguments of ttl-expired are:

ip-4 IP-ADDRESS

The Internet Protocol version 4 address of the host at which the time-to-live value expired.

ip-6 IP-ADDRESS

The Internet Protocol version 6 address of the host at which the time-to-live value expired.

round-trip-time TIME

The time which passed between the transmission of the probe and its response. The time is provided as a integral number of microseconds elapsed.

mpls MPLS-LABEL-LIST

A list of Multiprotocol Label Switching values returned with the probe response. If the mpls argument is present, one or more MPLS labels will be represented by a comma separated list of values. The values are provided in groups of four. The first four values in the list correspond to the first MPLS label, the next four values correspond to the second MPLS label, and so on. The values are provided in this order: label, traffic-class, bottom-of-stack, ttl.

no-route

There was no route to the host used in a send-probe request.

network-down

A probe could not be sent because the network is down.

probes-exhausted

A probe could not be sent because there are already too many unresolved probes in flight.

permission-denied

The operating system denied permission to send the probe with the specified options.

invalid-argument

The command request contained arguments which are invalid.

feature-support

A reply to provided to check-support indicating the availability of a particular feature. The argument provided is:

support PRESENT

In most cases, the PRESENT value will be either ok, indicating the feature is supported, or no, indicating no support for the feature.

In the case that version is the requested FEATURE-NAME, the version of mtr-packet is provided as the PRESENT value.

## EXAMPLES
A controlling program may start mtr-packet as a child process and issue the following command on stdin:

42 send-probe ip-4 127.0.0.1

This will send a network probe to the loopback interface. When the probe completes, mtr-packet will provide a response on stdout such as the following:

42 reply ip-4 127.0.0.1 round-trip-time 126

This indicates that the loopback address replied to the probe, and the round-trip time of the probe was 126 microseconds.

In order to trace the route to a remote host, multiple send-probe commands, each with a different ttl value, are used.

11 send-probe ip-4 8.8.8.8 ttl 1 12 send-probe ip-4 8.8.8.8 ttl 2 13 send-probe ip-4 8.8.8.8 ttl 3 ...

Each intermediate host would respond with a ttl-expired message, and the destination host would respond with a reply:

11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634 12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609 13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643 14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755 15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695 17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077 16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253 18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080 19 reply ip-4 8.8.8.8 round-trip-time 17039

Note that the replies in this example are printed out of order. (The reply to probe 17 arrives prior to the reply to probe 16.) This is the reason that it is important to send commands with unique token values, and to use those token values to match replies with their originating commands.

## LANGUAGE BINDINGS
A Python 3.x package for sending asynchronous network probes using mtr-packet is available. See https://pypi.org/project/mtrpacket/

## CONTACT INFORMATION
For the latest version, see the mtr web page at http://www.bitwizard.nl/mtr/

For patches, bug reports, or feature requests, please open an issue on GitHub at: https://github.com/traviscross/mtr.

## SEE ALSO
mtr(8), icmp(7), tcp(7), udp(7), TCP/IP Illustrated (Stevens, ISBN 0201633469).


mtree

package: mtree

title: mtree(8)

summary: map a directory hierarchy

text:
# mtree(8)

## NAME
mtree — map a directory hierarchy

## SYNOPSIS
mtree

[-cdeilnqrtUux] [-f spec] [-K keywords] [-k keywords] [-p path] [-s seed]

## DESCRIPTION
The utility mtree compares the file hierarchy rooted in the current directory against a specification read from the standard input. Messages are written to the standard output for any files whose characteristics do not match the specification, or which are missing from either the file hierarchy or the specification. For an explanation of the directory hierarchy, see hier(7).

The options are as follows:

-c

Print a specification for the file hierarchy to the standard output.

-d

Ignore everything except directory type files.

-e

Don't complain about files that are in the file hierarchy, but not in the specification.

-f spec

Read the specification from file spec, instead of from the standard input.

-i

Indents the output 4 spaces each time a directory level is descended when creating a specification with the -c option. This does not affect either the /set statements or the comment before each directory. It does however affect the comment before the close of each directory.

-K keywords

Add the specified (whitespace or comma separated) keywords to the current set of keywords.

-k keywords

Use the “type” keyword plus the specified (whitespace or comma separated) keywords instead of the current set of keywords.

-l

Do “loose” permissions checks, in which more stringent permissions will match less stringent ones. For example, a file marked mode 0444 will pass a check for mode 0644. “Loose” checks apply only to read, write and execute permissions -- in particular, if other bits like the sticky bit or suid/sgid bits are set either in the specification or the file, exact checking will be performed. This flag may not be set at the same time as the -u or -U flags.

-n

Do not emit pathname comments when creating a specification. Normally a comment is emitted before each directory and before the close of that directory when using the -c option.

-p path

Use the file hierarchy rooted in path, instead of the current directory.

-q

Quiet mode. Do not complain when a “missing” directory cannot be created because it already exists. This occurs when the directory is a symbolic link.

-r

Remove any files in the file hierarchy that are not described in the specification.

-s seed

Display a single checksum to the standard error output that represents all of the files for which the keyword cksum was specified. The checksum is seeded with the specified value.

-t

If a file's timestamp is different from the specification, “touch” it to match the specification (and list as modified).

-U

Modify the owner, group, and permissions of existing files to match the specification and create any missing directories. User, group, and permissions must all be specified for missing directories to be created. Exit with a status of 0 on success, 1 if any error occurred; a mismatch is not considered an error if it was corrected.

-u

Same as the -U option except a status of 2 is returned if the file hierarchy did not match the specification.

-x

Don't descend below mount points in the file hierarchy.

Specifications are mostly composed of “keywords” (i.e., strings that specify values relating to files). No keywords have default values, and if a keyword has no value set, no checks based on it are performed.

Currently supported keywords are as follows:

cksum

The checksum of the file using the default algorithm specified by the cksum(1) utility.

gid

The file group as a numeric value.

gname

The file group as a symbolic name.

ignore

Ignore any file hierarchy below this file.

md5digest

The MD5 message digest of the file.

mode

The current file's permissions as a numeric (octal) or symbolic value.

nlink

The number of hard links the file is expected to have.

nochange

Do not change the attributes (owner, group, mode, etc) on a file or directory.

optional

The file is optional; don't complain about the file if it's not in the file hierarchy.

rmd160digest

The RIPEMD-160 message digest of the file.

sha1digest

The SHA-1 message digest of the file.

uid

The file owner as a numeric value.

uname

The file owner as a symbolic name.

size

The size, in bytes, of the file.

link

The file the symbolic link is expected to reference.

time

The last modification time of the file.

type

The type of the file; may be set to any one of the following:

block

block special device

char

character special device

dir

directory

fifo

FIFO

file

regular file

link

symbolic link

socket

socket

The default set of keywords are gid, mode, nlink, size, link, time, and uid.

There are four types of lines in a specification.

The first type of line sets a global value for a keyword, and consists of the string “/set” followed by whitespace, followed by sets of keyword/value pairs, separated by whitespace. Keyword/value pairs consist of a keyword, followed by an equals sign (‘=’), followed by a value, without whitespace characters. Once a keyword has been set, its value remains unchanged until either reset or unset.

The second type of line unsets keywords and consists of the string “/unset”, followed by whitespace, followed by one or more keywords, separated by whitespace.

The third type of line is a file specification and consists of a file name, followed by whitespace, followed by zero or more whitespace separated keyword/value pairs. The file name may be preceded by whitespace characters. The file name may contain any of the standard file name matching characters ([“”, “]”, “?”, or “*”), in which case files in the hierarchy will be associated with the first pattern that they match.

Each of the keyword/value pairs consist of a keyword, followed by an equals sign, followed by the keyword's value, without whitespace characters. These values override, without changing, the global value of the corresponding keyword.

All paths are relative. Specifying a directory will cause subsequent files to be searched for in that directory hierarchy. Which brings us to the last type of line in a specification: a line containing only the string “..” causes the current directory path to ascend one level.

Empty lines and lines whose first non-whitespace character is a hash mark (‘#’) are ignored.

The mtree utility exits with a status of 0 on success, 1 if any error occurred, and 2 if the file hierarchy did not match the specification. A status of 2 is converted to a status of 0 if the -U option is used.

## FILES
/etc/mtree

system specification directory

## EXAMPLES
To detect system binaries that have been “trojan horsed”, it is recommended that mtree -cK sha1digest be run on the file systems, and a copy of the results stored on a different machine, or, at least, in encrypted form. The output file itself should be digested using openssl dgst -sha1. Then, periodically, mtree and openssl dgst -sha1 should be run against the on-line specifications. While it is possible for the bad guys to change the on-line specifications to conform to their modified binaries, it is believed to be impractical for them to create a modified specification which has the same SHA1 digest as the original.

The -d and -u options can be used in combination to create directory hierarchies for distributions and other such things; the files in /etc/mtree were used to create almost all directories in a normal binary distribution.

## SEE ALSO
chgrp(1), chmod(1), chown(1), cksum(1), md5sum(1), openssl(1), sha1sum(1), stat(1), stat(2), fts(3), md5(3), ripemd(3), sha(3), hier(7)

## HISTORY
The mtree utility appeared in 4.3BSD-Reno.


mpathconf

package: multipath-tools

title: mpathconf(8)

text:
# mpathconf(8)

## NAME
mpathconf - A tool for configuring device-mapper-multipath

## SYNOPSIS
mpathconf [commands] [options]

## DESCRIPTION
mpathconf is a utility that creates or modifies /etc/multipath.conf. It can enable or disable multipathing and configure some common options. mpathconf can also load the dm_multipath module, start and stop the multipathd daemon, and configure the multipathd service to start automatically or not. If mpathconf is called with no commands, it will display the current configuration, but will not create of modify /etc/multipath.conf

The default options for mpathconf are --with_module The --with_multipathd option is not set by default. Enabling multipathing will load the dm_multipath module but it will not immediately start it. This is so that users can manually edit their config file if necessary, before starting multipathd.

If /etc/multipath.conf already exists, mpathconf will edit it. If it does not exist, mpathconf will create a default file with user_friendly_names set and find_multipaths set to on. To disable these, use the --user_friendly_names n and --find_multipaths off options

## COMMANDS
--enable

Removes any line that blacklists all device nodes from the /etc/multipath.conf blacklist section. Also, creates /etc/multipath.conf if it doesn't exist.

--disable

Adds a line that blacklists all device nodes to the /etc/multipath.conf blacklist section. If no blacklist section exists, it will create one.

--allow <device>

Modifies the /etc/multipath/conf blacklist to blacklist all wwids and the blacklist_exceptions to whitelist <device>. <device> can be in the form of MAJOR:MINOR, a wwid, or the name of a device-mapper device, either a multipath device, or any device on stacked on top of one or more multipath devices. This command can be used multiple times to allow multiple devices. NOTE: This action will create a configuration file that mpathconf will not be able to revert back to its previous state. Because of this, --outfile is required when using --allow.

--user_friendly_names { y | n }

If set to y, this adds the line user_friendly_names yes to the /etc/multipath.conf defaults section. If set to n, this removes the line, if present. This command can be used along with any other command.

--recheck_wwid { y | n }

If set to y, this adds the line recheck_wwid yes to the /etc/multipath.conf defaults section, or sets an existing line to yes. If set to n, this sets an existing recheck_wwid line to no. This command can be used along with any other command.

--find_multipaths { on | yes | y | off | no | n | strict | greedy | smart }

If set to <value>, this adds the line find_multipaths <value> to the /etc/multipath.conf defaults section. This command can be used along with any other command. y and n can be used instead of yes and no.

--property_blacklist { y | n }

If set to y, this adds the line property (SCSI_IDENT_|ID_WWN) to the /etc/multipath.conf blacklist_exceptions section. If set to n, this removes the line, if present. This command can be used along with any other command.

--enable_foreign { y | n }

If set to y, this adds the line enable_foreign .* to the /etc/multipath.conf defaults section. if set to n, this removes the line, if present. This command can be used along with any other command.

--option <option_name>:[<value>]

Sets the defaults section option <option_name> to <value>. If the option was not previously set in the defaults section, it is added. If it was set, its value is changed to <value>. If <value> is left blank, then the option is removed from the defaults section, if was set there. This command can be used along with any other command.

--outfile <filename>

Write the resulting multipath configuration to <filename> instead of /etc/multipath.conf.

## OPTIONS
--with_module { y | n }

If set to y, this runs modprobe dm_multipath to install the multipath modules. This option only works with the --enable command. This option is set to y by default.

--with_multipathd { y | n }

If set to y, this runs service multipathd start to start the multipathd daemon on --enable, service multipathd stop to stop the multipathd daemon on --disable, and service multipathd reload to reconfigure multipathd on --user_friendly_names and --find_multipaths. This option is set to n by default.

## FILES
/etc/multipath.conf

## SEE ALSO
multipath.conf(5), modprobe(8), multipath(8), multipathd(8), service(8),

## AUTHOR
Benjamin Marzinski <bmarzins@redhat.com>


mpathpersist

title: mpathpersist(8)

text:
# mpathpersist(8)

## NAME
mpathpersist - Manages SCSI persistent reservations on dm multipath devices.

## SYNOPSIS
mpathpersist [OPTIONS] device

## DESCRIPTION
This utility is used to manage SCSI persistent reservations on Device Mapper Multipath devices. To be able to use this functionality, the reservation_key attribute must be defined in the /etc/multipath.conf file. Otherwise the multipathd daemon will not check for persistent reservation for newly discovered paths or reinstated paths.

mpathpersist supports the same command-line options as the sg_persist utility. Consult the sg_persist (8) manual page for an in-depth discussion of the various options.

## OPTIONS
-verbose|-v level

Verbosity:

0

Critical messages.

1

Error messages.

2

Warning messages.

3

Informational messages.

4

Informational messages with trace enabled.

--device=DEVICE|-d DEVICE

Query or change DEVICE.

--batch-file=DEVICE|-f FILE

Read commands from FILE. See section "BATCH FILES" below. This option can be given at most once.

--help|-h

Output this usage message.

--hex|-H

Output response in hex.

--in|-i

Request PR In command.

--out|-o

Request PR Out command.

--param-alltgpt|-Y

PR Out parameter 'ALL_TG_PT'.

--param-aptpl|-Z

PR Out parameter 'APTPL'.

--read-keys|-k

PR In: Read Keys.

--param-rk=RK|-K RK

PR Out parameter reservation key (RK is in hex, up to 8 bytes).

--param-sark=SARK|-S SARK

PR Out parameter service action reservation key (SARK is in hex).

--preempt|-P

PR Out: Preempt.

--clear|-C

PR Out: Clear registrations.

--preempt-abort|-A

PR Out: Preempt and Abort.

--prout-type=TYPE|-T TYPE

PR Out command type.

--read-full-status|-s

PR In: Read Full Status.

--read-keys|-k

PR In: Read Keys.

--read-reservation|-r

PR In: Read Reservation.

--register|-G

PR Out: Register.

--register-ignore|-I

PR Out: Register and Ignore.

--release|-L

PR Out: Release.

--report-capabilities|-c

PR In: Report Capabilities.

--reserve|-R

PR Out: Reserve.

--transport-id=TIDS|-X TIDS

TransportIDs can be mentioned in several forms.

--alloc-length=LEN|-l LEN

PR In: maximum allocation length. LEN is a decimal number between 0 and 8192.

## EXAMPLE
Register the key "123abc" for the /dev/mapper/mpath9 device:

mpathpersist --out --register --param-sark=123abc /dev/mapper/mpath9

Read registered reservation keys for the /dev/mapper/mpath9 device:

mpathpersist -i -k /dev/mapper/mpath9

Create a reservation for the /dev/mapper/mpath9 device with the given reservation key:

mpathpersist --out --reserve --param-rk=123abc --prout-type=8 -d /dev/mapper/mpath9

Read the reservation status of the /dev/mapper/mpath9 device:

mpathpersist -i -s -d /dev/mapper/mpath9

Release the previously created reservation (note that the prout-type needs to be the same as above):

mpathpersist --out --release --param-rk=123abc --prout-type=8 -d /dev/mapper/mpath9

Remove the current key registered for this host (i.e. reset it to 0):

mpathpersist --out --register-ignore -K 123abc -S 0 /dev/mapper/mpath9

Remove current reservation, and unregister all registered keys from all I_T nexuses:

mpathpersist -oCK 123abc /dev/mapper/mpath9

## BATCH FILES
The option --batch-file (-f) sets an input file to be processed by mpathpersist. Grouping commands in batch files can provide a speed improvement in particular on large installments, because mpathpersist needs to scan existing paths and maps only once during startup.

The input file is a text file that is parsed line by line. Every line of the file is interpreted as a command line (i.e. list of options and parameters) for mpathpersist. Options and parameters are separated by one or more whitespace characters (space or TAB). Lines can, but do not have to, begin with the word "mpathpersist". The "#" character, either at the beginning of the line or following some whitespace, denotes the start of a comment that lasts until the end of the line. Empty lines are allowed. Continuation of mpathpersist commands over multiple lines is not supported.

All options listed in this man page, except -f and -v, are allowed in batch files. Both short and long option formats may be used. Using the -f option inside the batch file is an error. The -v option is ignored in batch files.

The multipath map on which to act must be specified on every input line, e.g. using the -d option. Commands acting on different multipath maps may be combined in a batch file, and multiple commands may act on the same multipath map. Commands are executed one by one, so that commands further down in the file see status changes caused by previous commands. If mpathpersist encounters an error while processing a line in the batch file, batch file processing is not aborted; subsequent commands are executed nonetheless. The exit status of mpathpersist is the status of the first failed command, or 0 if all commands succeeded.

If other options and parameters are used along with -f on the mpathpersist command line, the command line will be executed first, followed by the commands from the batch file.

Below is an example of a valid batch input file.

```
# This is an mpathpersist input file.
# Short and long forms of the same command
-i -k /dev/dm-1 # short form, this comment is ignored
mpathpersist --in --read-keys --device=/dev/dm-1
# Mixing of long and short options, variable white space

  --out  --register    -S  abcde     /dev/dm-1
# Mixing of commands for different maps
-ir /dev/dm-0
-ir /dev/dm-1
mpathpersist --out --param-rk abcde --reserve --prout-type 5 /dev/dm-1
# This should now show a reservation
-ir /dev/dm-1
-oCK abcde /dev/dm-1
--in --read-reservation /dev/dm-1
```

## SEE ALSO
multipath(8), multipathd(8), sg_persist(8).

## AUTHORS
multipath-tools was developed by Christophe Varoqui <christophe.varoqui@opensvc.com> and others.


multipath

title: multipath(8)

summary: Device mapper target autoconfig.

text:
# multipath(8)

## NAME
multipath - Device mapper target autoconfig.

## SYNOPSIS
multipath [-v level] [-B|-d|-i|-q|-r] [-b file] [-p policy] [device]

multipath [-v level] [-R retries] -f device

multipath [-v level] [-R retries] -F

multipath [-v level] [-l|-ll] [device]

multipath [-v level] [-a|-w] device

multipath [-v level] -W

multipath [-v level] [-i] [-c|-C] device

multipath [-v level] [-i] [-u|-U]

multipath [-h|-t|-T]

## DESCRIPTION
multipath is used to detect and coalesce multiple paths to devices, for fail-over or performance reasons.

## ARGUMENTS
The device argument restricts multipath's operation to devices matching the given expression. The argument may refer either to a multipath map or to its components ("paths"). The expression may be in one of the following formats:

device node

file name of a device node, e.g. /dev/dm-10 or /dev/sda. If the node refers to an existing device mapper device representing a multipath map, this selects the map or its paths, depending on the operation mode. Otherwise, it selects a path device.

device ID

kernel device number specified by major:minor numbers, e.g. 65:16. This format can only be used for path devices.

WWID

a World Wide Identifier matching a multipath map or its paths. To list WWIDs of devices present in the system, use e.g. the command "multipath -d -v3 2>/dev/null".

## OPERATION MODES
The default operation mode is to detect and set up multipath maps from the devices found in the system. Other operation modes are chosen by using one of the following command line switches:

-f

Flush (remove) a multipath device map specified as parameter, if unused. This operation is delegated to the multipathd daemon if it's running.

-F

Flush (remove) all unused multipath device maps. This operation is delegated to the multipathd daemon if it's running.

-l

Show ("list") the current multipath topology from information fetched in sysfs and the device mapper.

-ll

Show ("list") the current multipath topology from all available information (sysfs, the device mapper, path checkers ...).

-a

Add the WWID for the specified device to the WWIDs file.

-w

Remove the WWID for the specified device from the WWIDs file.

-W

Reset the WWIDs file to only include the current multipath devices.

-c

Check if a block device should be a path in a multipath device.

-C

Check if a multipath device has usable paths. This can be used to test whether or not I/O on this device is likely to succeed. The command itself doesn't attempt to do I/O on the device.

-u

Check if the device specified in the program environment should be a path in a multipath device.

-U

Check if the device specified in the program environment is a multipath device with usable paths. See -C.

-h

Print usage text.

-t

Display the currently used multipathd configuration.

-T

Display the currently used multipathd configuration, limiting the output to those devices actually present in the system. This can be used a template for creating /etc/multipath.conf.

## OPTIONS
-v level

Verbosity of information printed to stdout in default and "list" operation modes. The default level is -v 2.

0

Nothing is printed.

1

In default mode, Names/WWIDs of created or modified multipath maps are printed. In list mode, WWIDs of all multipath maps are printed.

2

In default mode, Topology of created or modified multipath maps is printed. In list mode, topology of all multipath maps is printed.

3

All detected paths and the topology of all multipath maps are printed.

The verbosity level also controls the level of log and debug messages printed to stderr. The default level corresponds to LOG_NOTICE (important messages that shouldn't be missed in normal operation).

-d

Dry run, do not create or update devmaps.

-e

Enable all foreign libraries. This overrides the enable_foreign option from multipath.conf(5).

-i

Ignore WWIDs file when processing devices. If find_multipaths strict or find_multipaths no is set in /etc/multipath.conf, multipath only considers devices that are listed in the WWIDs file. This option overrides that behavior. For other values of find_multipaths, this option has no effect. See the description of find_multipaths in /etc/multipath.conf(5). This option should only be used in rare circumstances.

-B

Treat the bindings file as read only.

-b file

(deprecated, do not use) Set user_friendly_names bindings file location. The default is /etc/multipath/bindings.

-q

Don't unset the device mapper feature queue_if_no_path for multipath maps. Normally, multipath would do so if multipathd is not running, because only a running multipath daemon guarantees that unusable paths are reinstated when they become usable again.

-p policy

Force new maps to use the specified policy, overriding the configuration in multipath.conf(5). The possible values for policy are the same as the values for path_grouping_policy in multipath.conf(5). Existing maps are not modified.

-r

Force a reload of all existing multipath maps. This command is delegated to the multipathd daemon if it's running. In this case, other command line switches of the multipath command have no effect.

-R retries

Number of times to retry flushing multipath devices that are in use. The default is 0.

## SEE ALSO
multipathd(8), multipath.conf(5), kpartx(8), udev(8), dmsetup(8), hotplug(8).

## AUTHORS
multipath-tools was developed by Christophe Varoqui <christophe.varoqui@opensvc.com> and others.


multipathc

title: multipathc(8)

summary: Interactive client for multipathd

text:
# multipathc(8)

## NAME
multipathc - Interactive client for multipathd

## SYNOPSIS
multipathc [ timeout ]

## DESCRIPTION
The multipathc tool provides an interactive shell for communicating with the multipathd daemon. The command multipathd -k invokes multipathc.

All commands documented in multipathd(8) are supported. The available commands can be viewed by entering 'help'. Use quit, exit, or CTRL-D to exit the shell. Keywords can be abbreviated with the first letters (for example, shu for shutdown), if the abbreviation is unique. Some commands support pretty-printing using printf-style format specifiers. The supported format specifiers can be listed with the command show wildcards. Depending on build options, the interactive shell may provide command completion and history expansion features.

The optional parameter timeout specifies the timeout to wait for a reply from multipathd, in milliseconds. The default is 4000 ms.

## SEE ALSO
multipathd(8)

## AUTHORS
multipath-tools was developed by Christophe Varoqui <christophe.varoqui@opensvc.com> and others.


multipathd

title: multipathd(8)

summary: Multipath daemon.

text:
# multipathd(8)

## NAME
multipathd - Multipath daemon.

## SYNOPSIS
multipathd [-d] [-s] [-v verbosity] [-B] [-w]

multipathd [-v verbosity] -kcommand

multipathd [-v verbosity] -k

## DESCRIPTION
The multipathd daemon is in charge of checking for failed paths. When this happens, it will reconfigure the multipath map the path belongs to, so that this map regains its maximum performance and redundancy.

With the -k option, multipathd acts as a client utility that sends commands to a running instance of the multipathd daemon (see COMMANDS below).

In this Linux distribution, multipathd does not run unless a /etc/multipath.conf file exists.

## OPTIONS
-d

Foreground Mode. Don't daemonize, and print all messages to stdout and stderr.

-s

Suppress timestamps. Do not prefix logging messages with a timestamp.

-v level

Verbosity level. Print additional information while running multipathd. A level of 0 means only print errors. A level of 3 or greater prints debugging information as well.

-B

Read-only bindings file. multipathd will not write to the user_friendly_names bindings file. If a user_friendly_name doesn't already exist for a device, it will use its WWID as its alias.

-kcommand

multipathd executes the given command (see COMMANDS below). If the command contains whitespace or shell special characters, it needs to be quoted like in multipathd -k'show topology'. No whitespace is allowed between the -k and the command string.

-k

multipathd executes the multipathc interactive shell for entering commands (see COMMANDS below).

-n

IGNORED. Use the option find_multipaths to control the treatment of newly detected devices by multipathd. See multipath.conf(5).

-w

Since kernel 4.14 a new device-mapper event polling interface is used for updating multipath devices on dmevents. Use this flag to force it to use the old event waiting method, based on creating a separate thread for each device.

## COMMANDS
The following commands can be used in interactive mode:

list|show paths

Show the paths that multipathd is monitoring, and their state.

list|show paths [raw] format $format

Show the paths that multipathd is monitoring, using a format string with path format wildcards. Adding raw will remove the headers and alignment padding from the output. See "Path format wildcards" below.

list|show path $path

Show whether path $path is offline or running.

list|show maps|multipaths

Show the multipath devices that the multipathd is monitoring.

list|show maps|multipaths [raw] format $format

Show the status of all multipath devices that the multipathd is monitoring, using a format string with multipath format wildcards. Adding raw will remove the headers and alignment padding from the output. See "Multipath format wildcards" below.

list|show maps|multipaths status

Show the status of all multipath devices that the multipathd is monitoring.

list|show maps|multipaths stats

Show some statistics of all multipath devices that the multipathd is monitoring.

list|show maps|multipaths topology

Show the current multipath topology. Same as 'multipath -ll'.

list|show maps|multipaths json

Show information about all multipath devices in JSON format.

list|show topology

Show the current multipath topology. Same as 'multipath -ll'.

list|show map|multipath $map topology

Show topology of a single multipath device specified by $map, for example 36005076303ffc56200000000000010aa. This map could be obtained from 'list maps'.

list|show map|multipath $map [raw] format $format.

Show the status of multipath device $map, using a format string with multipath format wildcards. Adding raw will remove the headers and alignment padding from the output. See "Multipath format wildcards" below.

list|show map|multipath $map json

Show information about multipath device $map in JSON format.

list|show wildcards

Show the format wildcards used in interactive commands taking $format. See "Format Wildcards" below.

list|show config

Show the currently used configuration, derived from default values and values specified within the configuration file /etc/multipath.conf.

list|show config local

Show the currently used configuration like show config, but limiting the devices section to those devices that are actually present in the system.

list|show blacklist

Show the currently used blacklist rules, derived from default values and values specified within the configuration file /etc/multipath.conf.

list|show devices

Show all available block devices by name including the information if they are blacklisted or not.

list|show status

Show the number of path checkers in each possible state, the number of monitored paths, and whether multipathd is currently handling a uevent.

list|show daemon

Show the current state of the multipathd daemon.

reset maps|multipaths stats

Reset the statistics of all multipath devices.

reset map|multipath $map stats

Reset the statistics of multipath device $map.

add path $path

Add a path to the list of monitored paths. $path is as listed in /sys/block (e.g. sda).

remove|del path $path

Stop monitoring a path. $path is as listed in /sys/block (e.g. sda).

add map|multipath $map

Add a multipath device to the list of monitored devices. $map can either be a device-mapper device as listed in /sys/block (e.g. dm-0) or it can be the alias for the multipath device (e.g. mpath1) or the uid of the multipath device (e.g. 36005076303ffc56200000000000010aa).

remove|del maps|multipaths

Remove all multipath devices.

remove|del map|multipath $map

Remove the multipath device $map.

resize map|multipath $map

Resizes map $map to the given size.

switch|switchgroup map|multipath $map group $group

Force a multipath device to switch to a specific path group. $group is the path group index, starting with 1.

reconfigure

Rereads the configuration, and reloads all changed multipath devices. This also happens at startup, when the service is reload, or when a SIGHUP is received.

reconfigure all

Rereads the configuration, and reloads all multipath devices regardless of whether or not they have changed. This also happens when multipath -r is run.

suspend map|multipath $map

Sets map $map into suspend state.

resume map|multipath $map

Resumes map $map from suspend state.

reset map|multipath $map

Reassign existing device-mapper table(s) use the multipath device, instead of its path devices.

reload map|multipath $map

Reload a multipath device.

fail path $path

Sets path $path into failed state.

reinstate path $path

Resumes path $path from failed state.

disablequeueing maps|multipaths

Disable queueing on all multipath devices.

restorequeueing maps|multipaths

Restore queueing to the configured no_path_retry setting on all multipath devices whose queueing has been previously disabled by the disablequeueing command. Note: If no_path_path_retry is set to queue for a limited number of retries after all paths have failed, this will not enable queueing if there are no active paths.

disablequeueing map|multipath $map

Disable queuing on multipathed map $map.

restorequeueing map|multipath $map

restore queueing to the configured no_path_retry setting on multipathed map $map whose queueing has been previously disabled by the disablequeueing command. Note: If no_path_path_retry is set to queue for a limited number of retries after all paths have failed, this will not enable queueing if there are no active paths.

forcequeueing daemon

Forces multipathd into queue_without_daemon mode, so that no_path_retry queueing will not be disabled when the daemon stops.

restorequeueing daemon

Restores configured queue_without_daemon mode.

map|multipath $map setprstatus

Enable persistent reservation management on $map.

map|multipath $map unsetprstatus

Disable persistent reservation management on $map.

map|multipath $map getprstatus

Get the current persistent reservation management status of $map.

map|multipath $map getprkey

Get the current persistent reservation key associated with $map.

map|multipath $map setprkey key $key

Set the persistent reservation key associated with $map to $key in the prkeys_file. This key will only be used by multipathd if reservation_key is set to file in /etc/multipath.conf.

map|multipath $map unsetprkey

Remove the persistent reservation key associated with $map from the prkeys_file. This will only unset the key used by multipathd if reservation_key is set to file in /etc/multipath.conf.

path $path setmarginal

move $path to a marginal pathgroup. The path will remain in the marginal path group until unsetmarginal is called. This command will only work if marginal_pathgroups is enabled and there is no Shaky paths detection method configured (see the multipath.conf man page for details).

path $path unsetmarginal

return marginal path $path to its normal pathgroup. This command will only work if marginal_pathgroups is enabled and there is no Shaky paths detection method configured (see the multipath.conf man page for details).

map $map unsetmarginal

return all marginal paths in $map to their normal pathgroups. This command will only work if marginal_pathgroups is enabled and there is no Shaky paths detection method configured (see the multipath.conf man page for details).

quit|exit

End interactive session.

shutdown

Stop multipathd.

## Format Wildcards
Multipathd commands that take a $format option require a format string. This string controls how a device is printed and should include format wildcards. When the devices are printed, these wildcards will be replaced by the appropriate device information. The following wildcards are supported.

Multipath format wildcards

%n

The device name.

%w

The device WWID (uuid).

%d

The device sysfs name (dm-<minor_nr>).

%F

The device failback setting. For deferred failbacks, it will either include the configured time if a deferred failback is not in progress, or it will show the current progress of a deferred failback in seconds.

%Q

The device no_path_retry setting. If no_path_retry is set to a number of retries, it will either print the configured number of checker retries if the device is not in recovery mode, the number of seconds until queueing is disabled if the device is queueing in recovery mode, or off if the device has disabled queueing.

%N

The number of active paths for the device.

%r

The device write-protect setting, either ro or rw.

%t

The state of the device in device-mapper. suspend if the devices is suspended, and active otherwise.

%S

The device size, using the suffixes K, M, G, T, and P, to stand for kilobytes, megabytes, gigabytes, terabytes, and petabytes, respectively.

%f

The "features" string of the device-mapper table in the kernel.

%x

The number of times the device has entered a state where it will fail IO. This is an alias for the %4 wildcard. This value can be reset with the 'reset map $map stats' command.

%h

The device table hardware handler string.

%A

The last action multipathd took on the device. This wildcard is for debugging use, as understanding its meaning requires looking at the code.

%0

The number of times a path in the device has failed. This value can be reset with the 'reset map $map stats' command.

%1

The number of times multipathd has initiated a pathgroup switch for the device. This value can be reset with the 'reset map $map stats' command.

%2

The number of times multipathd has loaded a new table for the device. This value can be reset with the 'reset map $map stats' command.

%3

The approximate number of seconds that multipathd has spent queueing with no usable paths. This value can be reset with the 'reset map $map stats' command.

%4

The number of times the device has entered a state where it will fail IO. This is an alias for the %x wildcard. This value can be reset with the 'reset map $map stats' command.

%s

The vendor/product string for the device.

%v

The array vendor string for the device.

%p

The array product string for the device.

%e

The array firmware revision string for the device.

%G

The foreign library used for the device, or -- for native device-mapper multipath devices. See "FOREIGN MULTIPATH SUPPORT" in /etc/multipath.conf(5).

%g

Data from vendor specific vpd pages for the device, if any. Currently multipathd supports VPD page 0xc0 for HPE 3PAR / Primera / Alletra storage arrays.

%k

The actual max_sectors_kb setting for the device (which may be different from the configured one).

Path format wildcards

%w

The device WWID (uuid).

%i

The device Host:Channel:Id:Lun for SCSI devices. The device "Controller Instance Number":"Controller ID":"Namespace Instance Number":"Namespace ID" for NVMe devices. The Controller and Namespace Instance Numbers match the NVMe device name: "nvme<Controller_Instance_Number>n<Namespace_Instance_Number>"

%d

The device sysfs name.

%D

The device major:minor

%t

The device-mapper state of the device, either active or failed.

%o

The offline state of the device. This shows "offline" if the device's "state" attribute in sysfs is "offline" (for SCSI) or "dead" (for NVMe). For all other sysfs states, it shows "running".

%T

The multipathd path checker state of the device. The possible states are:

ready

The device is ready to handle IO.

faulty

The device is unusable.

shaky

The device is not able to handle IO but can still be accessed to check the priority.

ghost

The device is in stand-by state.

i/o pending

The checker is in the process of determining the device state.

i/o timeout

The path checker has timed out, failing the device.

delayed

The device appears usable, but it being delayed for marginal path checking.

undef

The device either is not part of a multipath device, or its path checker has not yet run.

%s

The vendor/product/revision string for the device.

%c

The name of the device's path checking algorithm

%C

The progress towards the next path checker run on the device in seconds.

%p

The device priority.

%S

The device size, using the suffixes K, M, G, T, and P, to stand for kilobytes, megabytes, gigabytes, terabytes, and petabytes, respectively.

%z

The device serial number.

%M

The device marginal state, either marginal or normal.

%m

The multipath device that this device is a path of, or [orphan] if it is not part of any multipath device.

%N

The host World Wide Node Name (WWNN) of the device, if any.

%n

The target World Wide Node Name (WWNN) of the device, if any.

%R

The host World Wide Port Name (WWPN) of the device, if any.

%r

The target World Wide Port Name (WWPN) of the device, if any.

%a

The host adapter name for the device (only SCSI devices).

%G

The foreign library used for the device, or -- for native device-mapper multipath devices. See "FOREIGN MULTIPATH SUPPORT" in /etc/multipath.conf(5).

%g

Data from vendor specific vpd pages for the device, if any. Currently multipathd supports VPD page 0xc0 for HPE 3PAR / Primera / Alletra storage arrays.

%0

The number of times this device has failed.

%P

The device protocol. See /etc/multipath.conf(5).

%I

The device initialization state. Devices that have been fully initialized are shown as ok.

%L

The device SCSI LUN ID in hexadecimal format. This is only meaningful for SCSI devices.

%A

The ALUA Target Port Group ID for the device, if applicable.

%k

The actual max_sectors_kb setting for the device (which may be different than the configured one).

## SYSTEMD INTEGRATION
When compiled with systemd support two systemd service files are installed, multipathd.service and multipathd.socket. If enabled, the multipathd.socket service instructs systemd to intercept the CLI command socket, so that any call to the CLI interface will start-up the daemon if required. The multipathd.service file carries the definitions for controlling the multipath daemon. The daemon itself uses the sd_notify(3) interface to communicate with systemd. The following unit keywords are recognized:

WatchdogSec=

Enables the internal watchdog from systemd. multipath will send a notification via sd_notify(3) to systemd to reset the watchdog. If specified the polling_interval and max_polling_interval settings will be overridden by the watchdog settings. Please note that systemd prior to version 207 has issues which prevent the systemd-provided watchdog from working correctly. So the watchdog is not enabled per default, but has to be enabled manually by updating the multipathd.service file.

OOMScoreAdjust=

Overrides the internal OOM adjust mechanism.

LimitNOFILE=

Overrides the max_fds configuration setting.

## SEE ALSO
multipathc(8), multipath(8), kpartx(8)

sd_notify(3), systemd.service(5).

## AUTHORS
multipath-tools was developed by Christophe Varoqui <christophe.varoqui@opensvc.com> and others.