.\" Update the date below if you make any significant change.
.\" Make sure there are no errors with:
.\" groff -z -wall -b -e -t multipath/multipath.conf.5
+.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.conf.5 >/dev/null
.\"
.\" TODO: Look for XXX and ???
.\"
.\" ----------------------------------------------------------------------------
.
-.TH MULTIPATH.CONF 5 2016-11-27 "Linux"
+.TH MULTIPATH.CONF 5 2017-08-18 Linux
.
.
.\" ----------------------------------------------------------------------------
overwrite the built-in configuration table of \fBmultipathd\fP.
Any line whose first non-white-space character is a '#' is considered
a comment line. Empty lines are ignored.
+.PP
+Currently used multipathd configuration can be displayed with the \fBmultipath -t\fR
+or \fBmultipathd show config\fR command.
.
.
.\" ----------------------------------------------------------------------------
according to the identifier to promote effiecncy in processing uevents.
It has no default value, if you want to identify path by udev attribute
and to activate merging uevents for SCSI and DASD devices, you can set
-its value as:
+its value as: \fIuid_attrs "sd:ID_SERIAL dasd:ID_UID"\fR.
.RS
.TP
-\fBuid_attrs "sd:ID_SERIAL dasd:ID_UID"\fR
-.TP
The default is: \fB<unset>\fR
.RE
.
The default is: for SCSI devices \fBID_SERIAL\fR
.TP
The default is: for DASD devices \fBID_UID\fR
+.TP
+The default is: for NVME devices \fBID_WWN\fR
.RE
.
.
.B getuid_callout
(Superseded by \fIuid_attribute\fR) The default program and args to callout
to obtain a unique path identifier. Should be specified with an absolute path.
+.RS
.TP
+The default is: \fB<unset>\fR
+.RE
.
.
+.TP
.B prio
The name of the path priority routine. The specified routine
should return a numeric value specifying the relative priority
.I sysfs
Use the sysfs attributes \fIaccess_state\fR and \fIpreferred_path\fR to
generate the path priority. This prioritizer accepts the optional prio_arg
-\fIexclusive_pref_bit\fR
+\fIexclusive_pref_bit\fR.
.TP
.I emc
(Hardware-dependent)
Generate the path priority based on the regular expression and the
priority provided as argument. Requires prio_args keyword.
.TP
+.I path_latency
+Generate the path priority based on a latency algorithm.
+Requires prio_args keyword.
+.TP
.I datacore
-.\" XXX
-???. Requires prio_args keyword.
+(Hardware-dependent)
+Generate the path priority for some DataCore storage arrays. Requires prio_args
+keyword.
.TP
.I iet
-.\" XXX
-???. Requires prio_args keyword.
-.TP
-The default is: \fBconst\fR
+(iSCSI only)
+Generate path priority for iSCSI targets based on IP address. Requires
+prio_args keyword.
+.PP
+The default depends on the \fBdetect_prio\fR setting: If \fBdetect_prio\fR is
+\fByes\fR (default), the default priority algorithm is \fBsysfs\fR (except for
+NetAPP E-Series, where it is \fBalua\fR). If \fBdetect_prio\fR is
+\fBno\fR, the default priority algorithm is \fBconst\fR.
.RE
.
.
.RS
.TP 8
.I hbtl
-regex can be of SCSI H:B:T:L format. For example: 1:0:.:. , *:0:0:.
+Regex can be of SCSI H:B:T:L format. For example: 1:0:.:. , *:0:0:.
.TP
.I devname
-regex can be of device name format. For example: sda , sd.e
+Regex can be of device name format. For example: sda , sd.e
.TP
.I serial
-regex can be of serial number format. For example: .*J1FR.*324 . The serial can
+Regex can be of serial number format. For example: .*J1FR.*324 . The serial can
be looked up through sysfs or by running multipathd show paths format "%z". For
example: 0395J1FR904324
.TP
.I wwn
-regex can be of the form \fI"host_wwnn:host_wwpn:target_wwnn:target_wwpn"\fR
+Regex can be of the form \fI"host_wwnn:host_wwpn:target_wwnn:target_wwpn"\fR
these values can be looked up through sysfs or by running \fImultipathd show paths format
"%N:%R:%n:%r"\fR. For example: 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.* , .*:.*:iqn.2009-10.com.redhat.msp.lab.ask-06:.*
.RE
.TP 12
+.I path_latency
+Needs a value of the form "io_num=\fI<20>\fR base_num=\fI<10>\fR"
+.RS
+.TP 8
+.I io_num
+The number of read IOs sent to the current path continuously, used to calculate the average path latency.
+Valid Values: Integer, [2, 200].
+.TP
+.I base_num
+The base number value of logarithmic scale, used to partition different priority ranks. Valid Values: Integer,
+[2, 10]. And Max average latency value is 100s, min average latency value is 1us.
+For example: If base_num=10, the paths will be grouped in priority groups with path latency <=1us, (1us, 10us],
+(10us, 100us], (100us, 1ms], (1ms, 10ms], (10ms, 100ms], (100ms, 1s], (1s, 10s], (10s, 100s], >100s.
+.RE
+.TP 12
.I alua
If \fIexclusive_pref_bit\fR is set, paths with the \fIpreferred path\fR bit
set will always be in their own path group.
set will always be in their own path group.
.TP
.I datacore
-.\" XXX
-\fIpreferredsds\fR ???.
+.RS
+.TP 8
+.I preferredsds
+(Mandatory) The preferred "SDS name".
.TP
+.I timeout
+(Optional) The timeout for the INQUIRY, in ms.
+.RE
+.TP 12
.I iet
-.\" XXX
-\fIpreferredip\fR ???.
+.RS
+.TP 8
+.I preferredip=...
+(Mandatory) Th preferred IP address, in dotted decimal notation, for iSCSI targets.
+.RE
.TP
The default is: \fB<unset>\fR
.RE
Possible values for the feature list are:
.RS
.TP 12
-.\" XXX
.I queue_if_no_path
-(Superseded by \fIno_path_retry\fR) (Since ??? kernel) Queue I/O if no path is active.
-Identical to the \fIno_path_retry\fR with \fIqueue\fR value. See KNOWN ISSUES.
-.TP
-.I no_partitions
-Disable automatic partitions generation via kpartx.
+(Deprecated, superseded by \fIno_path_retry\fR) Queue I/O if no path is active.
+Identical to the \fIno_path_retry\fR with \fIqueue\fR value. If both this
+feature and \fIno_path_retry\fR are set, the latter value takes
+precedence. See KNOWN ISSUES.
.TP
-.\" XXX
.I pg_init_retries <times>
-(Since ??? kernel) Number of times to retry pg_init, it must be between 1 and 50.
+(Since kernel 2.6.24) Number of times to retry pg_init, it must be between 1 and 50.
.TP
-.\" XXX
.I pg_init_delay_msecs <msecs>
-(Since ??? kernel) Number of msecs before pg_init retry, it must be between 0 and 60000.
+(Since kernel 2.6.38) Number of msecs before pg_init retry, it must be between 0 and 60000.
.TP
-.\" XXX
.I queue_mode <mode>
-(Since ??? kernel) Select the the queue_mode per multipath device.
-Where <mode> can be \fIbio\fR, \fIrq\fR or \fImq\fR. Which corresponds to
-bio-based, request_fn rq-based, and blk-mq rq-based respectively.
+(Since kernel 4.8) Select the the queueing mode per multipath device.
+<mode> can be \fIbio\fR, \fIrq\fR or \fImq\fR, which corresponds to
+bio-based, request-based, and block-multiqueue (blk-mq) request-based,
+respectively.
+The default depends on the kernel parameter \fBdm_mod.use_blk_mq\fR. It is
+\fImq\fR if the latter is set, and \fIrq\fR otherwise.
.TP
-The default is: \fB0\fR
+The default is: \fB<unset>\fR
.RE
.
.
(Hardware-dependent)
Check the path state for HP/COMPAQ Smart Array(CCISS) controllers.
.TP
+.I none
+Do not check the device, fallback to use the values retrieved from sysfs
+.TP
.I rbd
Check if the path is in the Ceph blacklist and remap the path if it is.
.TP
.RS
.TP 12
.I value > 0
-number of retries until disable I/O queueing.
+Number of retries until disable I/O queueing.
.TP
.I fail
-for immediate failure (no I/O queueing).
+For immediate failure (no I/O queueing).
.TP
.I queue
-for never stop I/O queueing. Similar to \fIqueue_if_no_path\fR.
-.TP
-See KNOWN ISSUES.
+For never stop I/O queueing, similar to \fIqueue_if_no_path\fR. See KNOWN ISSUES.
.TP
The default is: \fBfail\fR
.RE
retry interval \fIno_path_retry\fR * \fIpolling_interval\fR
if a number of retries is given with \fIno_path_retry\fR and the
overall retry interval is longer than the specified \fIdev_loss_tmo\fR value.
-The Linux kernel will cap this value to \fI300\fR if \fIfast_io_fail_tmo\fR
+The Linux kernel will cap this value to \fI600\fR if \fIfast_io_fail_tmo\fR
is not set. See KNOWN ISSUES.
.RS
.TP
.
.
.TP
+.B prkeys_file
+The full pathname of the prkeys file, which is used by multipathd to keep
+track of the persistent reservation key used for a specific WWID, when
+\fIreservation_key\fR is set to \fBfile\fR.
+.RS
+.TP
+The default is \fB/etc/multipath/prkeys\fR
+.RE
+.
+.
+.TP
.B log_checker_err
If set to
.I once
list which contains an 8-byte value provided by the application client to the
device server to identify the I_T nexus.
.RS
+.PP
+Alternatively, this can be set to \fBfile\fR, which will store the RESERVATION
+KEY registered by mpathpersist in the \fIprkeys_file\fR. multipathd will then
+use this key to register additional paths as they appear. When the
+registration is removed, the RESERVATION KEY is removed from the
+\fIprkeys_file\fR.
.TP
The default is: \fB<unset>\fR
.RE
.
.TP
.B retain_attached_hw_handler
-If set to
+(Obsolete for kernels >= 4.3) If set to
.I yes
and the SCSI layer has already attached a hardware_handler to the device,
multipath will not force the device to use the hardware_handler specified by
mutipath.conf. If the SCSI layer has not attached a hardware handler,
multipath will continue to use its configured hardware handler.
.RS
-.TP
+.PP
The default is: \fByes\fR
+.PP
+\fBImportant Note:\fR Linux kernel 4.3 or newer always behaves as if
+\fB"retain_attached_hw_handler yes"\fR was set.
.RE
.
.
.
.
.TP
-.B san_path_err_threshold
-If set to a value greater than 0, multipathd will watch paths and check how many
-times a path has been failed due to errors.If the number of failures on a particular
-path is greater then the san_path_err_threshold then the path will not reinstante
-till san_path_err_recovery_time.These path failures should occur within a
-san_path_err_forget_rate checks, if not we will consider the path is good enough
-to reinstantate.
+.B marginal_path_double_failed_time
+One of the four parameters of supporting path check based on accounting IO
+error such as intermittent error. When a path failed event occurs twice in
+\fImarginal_path_double_failed_time\fR seconds due to an IO error and all the
+other three parameters are set, multipathd will fail the path and enqueue
+this path into a queue of which members are sent a couple of continuous
+direct reading asynchronous IOs at a fixed sample rate of 10HZ to start IO
+error accounting process.
+.RS
+.TP
+The default is: \fBno\fR
+.RE
+.
+.
+.TP
+.B marginal_path_err_sample_time
+One of the four parameters of supporting path check based on accounting IO
+error such as intermittent error. If it is set to a value no less than 120,
+when a path fail event occurs twice in \fImarginal_path_double_failed_time\fR
+second due to an IO error, multipathd will fail the path and enqueue this
+path into a queue of which members are sent a couple of continuous direct
+reading asynchronous IOs at a fixed sample rate of 10HZ to start the IO
+accounting process for the path will last for
+\fImarginal_path_err_sample_time\fR.
+If the rate of IO error on a particular path is greater than the
+\fImarginal_path_err_rate_threshold\fR, then the path will not reinstate for
+\fImarginal_path_err_recheck_gap_time\fR seconds unless there is only one
+active path. After \fImarginal_path_err_recheck_gap_time\fR expires, the path
+will be requeueed for rechecking. If checking result is good enough, the
+path will be reinstated.
.RS
.TP
The default is: \fBno\fR
.
.
.TP
-.B san_path_err_forget_rate
-If set to a value greater than 0, multipathd will check whether the path failures
-has exceeded the san_path_err_threshold within this many checks i.e
-san_path_err_forget_rate . If so we will not reinstante the path till
-san_path_err_recovery_time.
+.B marginal_path_err_rate_threshold
+The error rate threshold as a permillage (1/1000). One of the four parameters
+of supporting path check based on accounting IO error such as intermittent
+error. Refer to \fImarginal_path_err_sample_time\fR. If the rate of IO errors
+on a particular path is greater than this parameter, then the path will not
+reinstate for \fImarginal_path_err_rate_threshold\fR seconds unless there is
+only one active path.
.RS
.TP
The default is: \fBno\fR
.
.
.TP
-.B san_path_err_recovery_time
-If set to a value greater than 0, multipathd will make sure that when path failures
-has exceeded the san_path_err_threshold within san_path_err_forget_rate then the path
-will be placed in failed state for san_path_err_recovery_time duration.Once san_path_err_recovery_time
-has timeout we will reinstante the failed path .
-san_path_err_recovery_time value should be in secs.
+.B marginal_path_err_recheck_gap_time
+One of the four parameters of supporting path check based on accounting IO
+error such as intermittent error. Refer to
+\fImarginal_path_err_sample_time\fR. If this parameter is set to a positive
+value, the failed path of which the IO error rate is larger than
+\fImarginal_path_err_rate_threshold\fR will be kept in failed state for
+\fImarginal_path_err_recheck_gap_time\fR seconds. When
+\fImarginal_path_err_recheck_gap_time\fR seconds expires, the path will be
+requeueed for checking. If checking result is good enough, the path will be
+reinstated, or else it will keep failed.
.RS
.TP
The default is: \fBno\fR
.RE
.
.
+.TP
+.B ghost_delay
+Sets the number of seconds that multipath will wait after creating a device
+with only ghost paths before marking it ready for use in systemd. This gives
+the active paths time to appear before the multipath runs the hardware handler
+to switch the ghost paths to active ones. Setting this to \fI0\fR or \fIon\fR
+makes multipath immediately mark a device with only ghost paths as ready.
+.RS
+.TP
+The default is \fBno\fR
+.RE
+.
+.
.\" ----------------------------------------------------------------------------
.SH "blacklist section"
.\" ----------------------------------------------------------------------------
.TP
.B deferred_remove
.TP
-.B san_path_err_threshold
+.B marginal_path_err_sample_time
+.TP
+.B marginal_path_err_rate_threshold
.TP
-.B san_path_err_forget_rate
+.B marginal_path_err_recheck_gap_time
.TP
-.B san_path_err_recovery_time
+.B marginal_path_double_failed_time
.TP
.B delay_watch_checks
.TP
.B skip_kpartx
.TP
.B max_sectors_kb
+.TP
+.B ghost_delay
.RE
.PD
.LP
.I 1 alua
(Hardware-dependent)
Hardware handler for SCSI-3 ALUA compatible arrays.
-.TP
+.PP
The default is: \fB<unset>\fR
+.PP
+\fBImportant Note:\fR Linux kernels 4.3 and newer automatically attach a device
+handler to known devices (which includes all devices supporting SCSI-3 ALUA)
+and disallow changing the handler
+afterwards. Setting \fBhardware_handler\fR for such devices on these kernels
+has no effect.
.RE
.
.
.TP
.B deferred_remove
.TP
-.B san_path_err_threshold
+.B marginal_path_err_sample_time
+.TP
+.B marginal_path_err_rate_threshold
.TP
-.B san_path_err_forget_rate
+.B marginal_path_err_recheck_gap_time
.TP
-.B san_path_err_recovery_time
+.B marginal_path_double_failed_time
.TP
.B delay_watch_checks
.TP
.B skip_kpartx
.TP
.B max_sectors_kb
+.TP
+.B ghost_delay
.RE
.PD
.LP
.TP
.B deferred_remove
.TP
-.B san_path_err_threshold
+.B marginal_path_err_sample_time
+.TP
+.B marginal_path_err_rate_threshold
.TP
-.B san_path_err_forget_rate
+.B marginal_path_err_recheck_gap_time
.TP
-.B san_path_err_recovery_time
+.B marginal_path_double_failed_time
.TP
.B delay_watch_checks
.TP
.B delay_wait_checks
.TP
.B skip_kpartx
+.TP
+.B ghost_delay
.RE
.PD
.LP
projects / platform / upstream / multipath-tools.git / blobdiff