multipath: Deprecate 'getuid' configuration variable
[multipath-tools/.git] / multipath / multipath.conf.5
index 94adee2..ade9885 100644 (file)
@@ -34,7 +34,7 @@ The configuration file contains entries of the form:
 .LP
 Each \fIsection\fP contains one or more attributes or subsections. The
 recognized keywords for attributes or subsections depend on the
-section in which they occor.
+section in which they occur.
 .LP
 The following \fIsection\fP keywords are recognized:
 .TP 17
@@ -55,8 +55,9 @@ section.
 .TP
 .B multipaths
 This section defines the multipath topologies. They are indexed by a
-\fIWorld Wide Identifier\fR(wwid), which is the result of the
-\fIgetuid_callout\fR program.
+\fIWorld Wide Identifier\fR(wwid), which is taken to be the value of
+the udev attribute given by the
+\fIuid_attribute\fR keyword.
 .TP
 .B devices
 This section defines the device-specific settings.
@@ -78,9 +79,10 @@ default is
 maximal interval between two path checks in seconds; default is
 .I 4 * polling_interval
 .TP
-.B udev_dir
-directory where udev creates its device nodes; default is
-.I /dev
+.B multipath_dir
+directory where the dynamic shared objects are stored; default is system
+dependent, commonly
+.I /lib/multipath
 .TP
 .B verbosity
 default verbosity. Higher values increase the verbosity level. Valid
@@ -134,14 +136,18 @@ per-multipath option in the configuration file.
 1 priority group per target node name. Target node names are fetched
 in /sys/class/fc_transport/target*/node_name.
 .TP
-Default value is \fImultibus\fR.
+Default value is \fIfailover\fR.
 .RE
 .TP
+.B uid_attribute
+The udev attribute providing a unique path
+identifier. Default value is
+.I ID_SERIAL
+.TP
 .B getuid_callout
 The default program and args to callout to obtain a unique path
-identifier. Should be specified with an absolute path. Default value
-is
-.I /lib/udev/scsi_id --whitelisted --device=/dev/%n
+identifier. Should be specified with an absolute path.
+This parameter is deprecated; \fIuid_attribute\fR should be used instead.
 .TP
 .B prio
 The name of the path priority routine. The specified routine
@@ -177,17 +183,22 @@ Generate the path priority for Hitachi HDS Modular storage arrays.
 .B random
 Generate a random priority between 1 and 10.
 .TP 12
-.B weightedpath <hbtl|devname> <regex1> <prio1> <regex2> <prio2> ...
-.I hbtl 
-regex can be of SCSI H:B:T:L format  Ex: 1:0:.:. , *:0:0:.
-.I devname 
-regex can be of device name format  Ex: sda , sd.e
+.B weightedpath
 Generate the path priority based on the regular expression and the 
-priority provided as argument.
+priority provided as argument. requires prio_args keyword.
 .TP
 Default value is \fBnone\fR.
 .RE
 .TP
+.B prio_args
+Arguments to pass to to the prio function.  Currently only used with
+.I weighted, which needs a value of the form
+.I "<hbtl|devname> <regex1> <prio1> <regex2> <prio2> ..."
+.I hbtl
+regex can be of SCSI H:B:T:L format  Ex: 1:0:.:. , *:0:0:.
+.I devname
+regex can be of device name format  Ex: sda , sd.e
+.TP
 .B features
 Specify any device-mapper features to be used. Syntax is
 .I num list
@@ -238,19 +249,38 @@ Default value is \fIdirectio\fR.
 .RE
 .TP
 .B failback
-Tell the daemon to manage path group failback, or not to. 0 or
-.I immediate
-means immediate failback, values >0 means deferred failback (in
-seconds).
-.I manual
-means no failback. Default value is
-.I manual
+Tell multipathd how to manage path group failback.
+.RS
+.TP 12
+.B immediate
+Immediately failback to the highest priority pathgroup that contains
+active paths.
+.TP
+.B manual
+Do not perform automatic failback.
+.TP
+.B followover
+Only perform automatic failback when the first path of a pathgroup
+becomes active. This keeps a node from automatically failing back when
+another node requested the failover.
+.TP
+.B values > 0
+deferred failback (time to defer in seconds)
+.TP
+Default value is \fImanual\fR.
+.RE
 .TP
 .B  rr_min_io
 The number of IO to route to a path before switching to the next in
-the same path group. Default is
+the same path group. This is only for BIO based multipath. Default is
 .I 1000
 .TP
+.B rr_min_io_rq
+The number of IO requests to route to a path before switching to the
+next in the same path group. This is only for request based multipath.
+Default is
+.I 1
+.TP
 .B rr_weight
 If set to \fIpriorities\fR the multipath configurator will assign
 path weights as "path prio * rr_min_io". Possible values are
@@ -276,13 +306,20 @@ to assign a persistent and unique alias to the multipath, in the form of mpath<n
 If set to 
 .I no
 use the WWID as the alias. In either case this be will
-be overriden by any specific aliases in the \fImultipaths\fR section.
+be overridden by any specific aliases in the \fImultipaths\fR section.
 Default is
 .I no
 .TP
+.B flush_on_last_del
+If set to
+.I yes
+, multipathd will disable queueing when the last path to a device has been
+deleted. Default is
+.I no
+.TP
 .B max_fds
 Specify the maximum number of file descriptors that can be opened by multipath
-and multipathd.  This is equivalent to ulimit -n. A value of \fImax\fR will set
+and multipathd.  This is equivalent to ulimit \-n. A value of \fImax\fR will set
 this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
 maximum number of open fds is taken from the calling process. It is usually
 1024. To be safe, this should be set to the maximum number of paths plus 32,
@@ -290,7 +327,7 @@ if that number is greated than 1024.
 .TP
 .B checker_timeout
 Specify the timeout to user for path checkers that issue scsi commands with an
-explict timeout, in seconds; default taken from
+explicit timeout, in seconds; default taken from
 .I /sys/block/sd<x>/device/timeout
 .TP
 .B fast_io_fail_tmo
@@ -302,7 +339,15 @@ will disable the timeout.
 .TP
 .B dev_loss_tmo
 Specify the number of seconds the scsi layer will wait after a problem has
-been detected on a FC remote port before removing it from the system.
+been detected on a FC remote port before removing it from the system. This
+can be set to "infinity" which sets it to the max value of 2147483647
+seconds, or 68 years. It will be automatically adjusted to the overall
+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 \fBfast_io_fail_tmo\fR
+is not set.
 .TP
 .B queue_without_daemon
 If set to
@@ -316,9 +361,50 @@ cannot be told to stop queueing IO. Setting queue_without_daemon to
 .I no
 , avoids this problem. Default is
 .I yes
+.TP
 .B bindings_file
 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
-.I /var/lib/multipath/bindings
+.I /etc/multipath/bindings
+.TP
+.B wwids_file
+The full pathname of the wwids file, which is used by multipath to keep track
+of the wwids for LUNs it has created multipath devices on in the past.
+Defaults to
+.I /etc/multipath/wwids
+.TP
+.B log_checker_err
+If set to
+.I once
+, multipathd logs the first path checker error at logging level 2. Any later
+errors are logged at level 3 until the device is restored. If set to
+.I always
+, multipathd always logs the path checker error at logging level 2. Default is
+.I always
+.TP
+.B reservation_key
+This is the service action reservation key used by mpathpersist.  It must be
+set for all multipath devices using persistent reservations, and it must be
+the same as the RESERVATION KEY field of the PERSISTENT RESERVE OUT parameter
+list which contains an 8-byte value provided by the application client to the
+device server to identify the I_T nexus. It is unset by default.
+.TP
+.B retain_attached_hw_handler
+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. Default is
+.I no
+.TP
+.B detect_prio
+If set to
+.I yes
+, multipath will try to detect if the device supports ALUA. If so, the device
+will automatically use the
+.I alua
+prioritizer. If not, the prioritizer will be selected as usual. Default is
+.I no
 .
 .SH "blacklist section"
 The
@@ -349,7 +435,7 @@ The
 section is used to revert the actions of the
 .I blacklist
 section, ie to include specific device in the
-multipath topology. This allows to selectively include devices which
+multipath topology. This allows one to selectively include devices which
 would normally be excluded via the
 .I blacklist
 section.
@@ -403,13 +489,23 @@ section:
 .TP
 .B prio
 .TP
+.B prio_args
+.TP
 .B failback
 .TP
+.B rr_weight
+.TP
+.B flush_on_last_del
+.TP
 .B no_path_retry
 .TP
 .B rr_min_io
 .TP
+.B rr_min_io_rq
+.TP
 .B features
+.TP
+.B reservation_key
 .RE
 .PD
 .LP
@@ -436,6 +532,10 @@ subsection recognizes the following attributes:
 .B product_blacklist
 (Optional) Product strings to blacklist for this vendor
 .TP
+.B alias_prefix
+(Optional) The user_friendly_names prefix to use for this
+device type, instead of the default "mpath"
+.TP
 .B hardware_handler
 (Optional) The hardware handler to use for this device type.
 The following hardware handler are implemented:
@@ -465,7 +565,7 @@ section:
 .TP 18
 .B path_grouping_policy
 .TP
-.B getuid_callout
+.B uid_attribute
 .TP
 .B path_selector
 .TP
@@ -473,6 +573,8 @@ section:
 .TP
 .B prio
 .TP
+.B prio_args
+.TP
 .B features
 .TP
 .B failback
@@ -483,9 +585,17 @@ section:
 .TP
 .B rr_min_io
 .TP
+.B rr_min_io_rq
+.TP
 .B fast_io_fail_tmo
 .TP
 .B dev_loss_tmo
+.TP
+.B flush_on_last_del
+.TP
+.B retain_attached_hw_handler
+.TP
+.B detect_prio
 .RE
 .PD
 .LP