multipathd/multipathd.8

   1 .\" ----------------------------------------------------------------------------
   2 .\" Update the date below if you make any significant change.
   3 .\" Make sure there are no errors with:
   4 .\" groff -z -wall -b -e -t multipathd/multipathd.8
   5 .\"
   6 .\" ----------------------------------------------------------------------------
   7 .
   8 .TH MULTIPATHD 8 2016-10-27 Linux
   9 .
  10 .
  11 .\" ----------------------------------------------------------------------------
  12 .SH NAME
  13 .\" ----------------------------------------------------------------------------
  14 .
  15 multipathd \- Multipath daemon.
  16 .
  17 .
  18 .\" ----------------------------------------------------------------------------
  19 .SH SYNOPSIS
  20 .\" ----------------------------------------------------------------------------
  21 .
  22 .B multipathd
  23 .RB [\| \-d | \-k \|]
  24 .RB [\| \-s \|]
  25 .RB [\| \-v\ \c
  26 .IR verbosity \|]
  27 .RB [\| \-B \|]
  28 .RB [\| \-w \|]
  29 .
  30 .
  31 .\" ----------------------------------------------------------------------------
  32 .SH DESCRIPTION
  33 .\" ----------------------------------------------------------------------------
  34 .
  35 The \fBmultipathd\fR daemon is in charge of checking for failed paths. When this
  36 happens, it will reconfigure the multipath map the path belongs to, so that this
  37 map regains its maximum performance and redundancy.
  38
  39 This daemon executes the external \fBmultipath\fR tool when events occur.
  40 In turn, the multipath tool signals the multipathd daemon when it is done with
  41 devmap reconfiguration, so that it can refresh its failed path list.
  42 .
  43 .
  44 .\" ----------------------------------------------------------------------------
  45 .SH OPTIONS
  46 .\" ----------------------------------------------------------------------------
  47 .
  48 .TP
  49 .B \-d
  50 Foreground Mode. Don't daemonize, and print all messages to stdout and stderr.
  51 .
  52 .TP
  53 .B \-s
  54 Suppress timestamps. Do not prefix logging messages with a timestamp.
  55 .
  56 .TP
  57 .BI \-v " level"
  58 Verbosity level. Print additional information while running multipathd. A level
  59 of 0 means only print errors. A level of 3 or greater prints debugging information
  60 as well.
  61 .
  62 .TP
  63 .B \-B
  64 Read-only bindings file. multipathd will not write to the \fIuser_friendly_names\fR
  65 bindings file. If a \fIuser_friendly_name\fR doesn't already exist for a device, it
  66 will use its WWID as its alias.
  67 .
  68 .TP
  69 .B \-k
  70 multipathd will enter interactive mode. From this mode, the available commands can
  71 be viewed by entering '\fIhelp\fR'. When you are finished entering commands, press
  72 \fBCTRL-D\fR to quit.
  73 .
  74 .TP
  75 .B \-n
  76 \fBIGNORED\fR. Use the option
  77 \fIfind_multipaths\fR to control the treatment of newly detected devices by
  78 multipathd. See
  79 .BR multipath.conf(5).
  80 .
  81 .TP
  82 .B \-w
  83 Since kernel 4.14 a new device-mapper event polling interface is used for updating
  84 multipath devices on dmevents. Use this flag to force it to use the old event
  85 waiting method, based on creating a seperate thread for each device.
  86 .
  87 .
  88 .
  89 .\" ----------------------------------------------------------------------------
  90 .SH COMMANDS
  91 .\" ----------------------------------------------------------------------------
  92 .
  93 .TP
  94 The following commands can be used in interactive mode:
  95 .
  96 .TP
  97 .B list|show paths
  98 Show the paths that multipathd is monitoring, and their state.
  99 .
 100 .TP
 101 .B list|show paths format $format
 102 Show the paths that multipathd is monitoring, using a format string with path
 103 format wildcards.
 104 .
 105 .TP
 106 .B list|show maps|multipaths
 107 Show the multipath devices that the multipathd is monitoring.
 108 .
 109 .TP
 110 .B list|show maps|multipaths format $format
 111 Show the status of all multipath devices that the multipathd is monitoring,
 112 using a format string with multipath format wildcards.
 113 .
 114 .TP
 115 .B list|show maps|multipaths status
 116 Show the status of all multipath devices that the multipathd is monitoring.
 117 .
 118 .TP
 119 .B list|show maps|multipaths stats
 120 Show some statistics of all multipath devices that the multipathd is monitoring.
 121 .
 122 .TP
 123 .B list|show maps|multipaths topology
 124 Show the current multipath topology. Same as '\fImultipath \-ll\fR'.
 125 .
 126 .TP
 127 .B list|show topology
 128 Show the current multipath topology. Same as '\fImultipath \-ll\fR'.
 129 .
 130 .TP
 131 .B list|show map|multipath $map topology
 132 Show topology of a single multipath device specified by $map, for example
 133 36005076303ffc56200000000000010aa. This map could be obtained from '\fIlist maps\fR'.
 134 .
 135 .TP
 136 .B list|show wildcards
 137 Show the format wildcards used in interactive commands taking $format.
 138 .
 139 .TP
 140 .B list|show config
 141 Show the currently used configuration, derived from default values and values
 142 specified within the configuration file \fI/etc/multipath.conf\fR.
 143 .
 144 .TP
 145 .B list|show config local
 146 Show the currently used configuration like \fIshow config\fR, but limiting
 147 the devices section to those devices that are actually present in the system.
 148 .
 149 .TP
 150 .B list|show blacklist
 151 Show the currently used blacklist rules, derived from default values and values
 152 specified within the configuration file \fI/etc/multipath.conf\fR.
 153 .
 154 .TP
 155 .B list|show devices
 156 Show all available block devices by name including the information if they are
 157 blacklisted or not.
 158 .
 159 .TP
 160 .B list|show status
 161 Show the number of path checkers in each possible state, the number of monitored
 162 paths, and whether multipathd is currently handling a uevent.
 163 .
 164 .TP
 165 .B list|show daemon
 166 Show the current state of the multipathd daemon.
 167 .
 168 .TP
 169 .B add path $path
 170 Add a path to the list of monitored paths. $path is as listed in /sys/block (e.g. sda).
 171 .
 172 .TP
 173 .B remove|del path $path
 174 Stop monitoring a path. $path is as listed in /sys/block (e.g. sda).
 175 .
 176 .TP
 177 .B add map|multipath $map
 178 Add a multipath device to the list of monitored devices. $map can either be a
 179 device-mapper device as listed in /sys/block (e.g. dm-0) or it can be the alias
 180 for the multipath device (e.g. mpath1) or the uid of the multipath device
 181 (e.g. 36005076303ffc56200000000000010aa).
 182 .
 183 .TP
 184 .B remove|del map|multipath $map
 185 Stop monitoring a multipath device.
 186 .
 187 .TP
 188 .B resize map|multipath $map
 189 Resizes map $map to the given size.
 190 .
 191 .TP
 192 .B switch|switchgroup map|multipath $map group $group
 193 Force a multipath device to switch to a specific path group. $group is the path
 194 group index, starting with 1.
 195 .
 196 .TP
 197 .B reconfigure
 198 Rereads the configuration, and reloads all changed multipath devices. This
 199 also happens at startup, when the service is reload, or when a SIGHUP is
 200 received.
 201 .
 202 .TP
 203 .B reconfigure all
 204 Rereads the configuration, and reloads all multipath devices regardless of
 205 whether or not they have changed. This also happens when \fImultipath -r\fR is
 206 run.
 207 .TP
 208 .B suspend map|multipath $map
 209 Sets map $map into suspend state.
 210 .
 211 .TP
 212 .B resume map|multipath $map
 213 Resumes map $map from suspend state.
 214 .
 215 .TP
 216 .B reset map|multipath $map
 217 Reassign existing device-mapper table(s) use the multipath device, instead
 218 of its path devices.
 219 .
 220 .TP
 221 .B reload map|multipath $map
 222 Reload a multipath device.
 223 .
 224 .TP
 225 .B fail path $path
 226 Sets path $path into failed state.
 227 .
 228 .TP
 229 .B reinstate path $path
 230 Resumes path $path from failed state.
 231 .
 232 .TP
 233 .B disablequeueing maps|multipaths
 234 Disable queueing on all multipath devices.
 235 .
 236 .TP
 237 .B restorequeueing maps|multipaths
 238 Restore queueing on all multipath devices.
 239 .
 240 .TP
 241 .B disablequeueing map|multipath $map
 242 Disable queuing on multipathed map $map.
 243 .
 244 .TP
 245 .B restorequeueing map|multipath $map
 246 Restore queuing on multipahted map $map.
 247 .
 248 .TP
 249 .B forcequeueing daemon
 250 Forces multipathd into queue_without_daemon mode, so that no_path_retry queueing
 251 will not be disabled when the daemon stops.
 252 .
 253 .TP
 254 .B restorequeueing daemon
 255 Restores configured queue_without_daemon mode.
 256 .
 257 .TP
 258 .B map|multipath $map setprstatus
 259 Enable persistent reservation management on $map.
 260 .
 261 .TP
 262 .B map|multipath $map unsetprstatus
 263 Disable persistent reservation management on $map.
 264 .
 265 .TP
 266 .B map|multipath $map getprstatus
 267 Get the current persistent reservation management status of $map.
 268 .
 269 .TP
 270 .B map|multipath $map getprkey
 271 Get the current persistent reservation key associated with $map.
 272 .
 273 .TP
 274 .B map|multipath $map setprkey key $key
 275 Set the persistent reservation key associated with $map to $key in the
 276 \fIprkeys_file\fR. This key will only be used by multipathd if
 277 \fIreservation_key\fR is set to \fBfile\fR in \fI/etc/multipath.conf\fR.
 278 .
 279 .TP
 280 .B map|multipath $map unsetprkey
 281 Remove the persistent reservation key associated with $map from the
 282 \fIprkeys_file\fR. This will only unset the key used by multipathd if
 283 \fIreservation_key\fR is set to \fBfile\fR in \fI/etc/multipath.conf\fR.
 284 .
 285 .TP
 286 .B path $path setmarginal
 287 move $path to a marginal pathgroup. The path will remain in the marginal
 288 path group until \fIunsetmarginal\fR is called. This command will only
 289 work if \fImarginal_pathgroups\fR is enabled and there is no Shaky paths
 290 detection method configured (see the multipath.conf man page for details).
 291 .
 292 .TP
 293 .B path $path unsetmarginal
 294 return marginal path $path to its normal pathgroup. This command will only
 295 work if \fImarginal_pathgroups\fR is enabled and there is no Shaky paths
 296 detection method configured (see the multipath.conf man page for details).
 297 .
 298 .TP
 299 .B map $map unsetmarginal
 300 return all marginal paths in $map to their normal pathgroups. This command
 301 will only work if \fImarginal_pathgroups\fR is enabled and there is no Shaky
 302 paths detection method configured (see the multipath.conf man page for details).
 303 .
 304 .TP
 305 .B quit|exit
 306 End interactive session.
 307 .
 308 .TP
 309 .B shutdown
 310 Stop multipathd.
 311 .
 312 .
 313 .\" ----------------------------------------------------------------------------
 314 .SH "SYSTEMD INTEGRATION"
 315 .\" ----------------------------------------------------------------------------
 316 .
 317 When compiled with systemd support two systemd service files are installed,
 318 \fImultipathd.service\fR and \fImultipathd.socket\fR The \fImultipathd.socket\fR
 319 service instructs systemd to intercept the CLI command socket, so that any call
 320 to the CLI interface will start-up the daemon if required.
 321 The \fImultipathd.service\fR file carries the definitions for controlling the
 322 multipath daemon. The daemon itself uses the \fBsd_notify\fR(3) interface to
 323 communicate with systemd. The following unit keywords are recognized:
 324 .
 325 .TP
 326 .B WatchdogSec=
 327 Enables the internal watchdog from systemd. multipath will send a
 328 notification via \fBsd_notify\fR(3) to systemd to reset the watchdog. If
 329 specified the \fIpolling_interval\fR and \fImax_polling_interval\fR settings
 330 will be overridden by the watchdog settings.
 331 Please note that systemd prior to version 207 has issues which prevent
 332 the systemd-provided watchdog from working correctly. So the watchdog
 333 is not enabled per default, but has to be enabled manually by updating
 334 the \fImultipathd.service\fR file.
 335 .
 336 .TP
 337 .B OOMScoreAdjust=
 338 Overrides the internal OOM adjust mechanism.
 339 .
 340 .TP
 341 .B LimitNOFILE=
 342 Overrides the \fImax_fds\fR configuration setting.
 343 .
 344 .
 345 .\" ----------------------------------------------------------------------------
 346 .SH "SEE ALSO"
 347 .\" ----------------------------------------------------------------------------
 348 .
 349 .BR multipath (8),
 350 .BR kpartx (8),
 351 .BR sd_notify (3),
 352 .BR system.service (5).
 353 .
 354 .
 355 .\" ----------------------------------------------------------------------------
 356 .SH AUTHORS
 357 .\" ----------------------------------------------------------------------------
 358 .
 359 \fImultipath-tools\fR was developed by Christophe Varoqui <christophe.varoqui@opensvc.com>
 360 and others.
 361 .\" EOF