From patchwork Fri Jun 8 10:20:41 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Martin Wilck X-Patchwork-Id: 10454123 X-Patchwork-Delegate: christophe.varoqui@free.fr Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 59D696053F for ; Fri, 8 Jun 2018 10:22:17 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 52E5229514 for ; Fri, 8 Jun 2018 10:22:17 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 4734B2951C; Fri, 8 Jun 2018 10:22:17 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00, MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 73D0D29514 for ; Fri, 8 Jun 2018 10:22:16 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 886F53086244; Fri, 8 Jun 2018 10:22:15 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2661F5D9CA; Fri, 8 Jun 2018 10:22:15 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id A49A44CA88; Fri, 8 Jun 2018 10:22:14 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx12.intmail.prod.int.phx2.redhat.com [10.5.11.27]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w58AM8QF018469 for ; Fri, 8 Jun 2018 06:22:08 -0400 Received: by smtp.corp.redhat.com (Postfix) id 9057EA1422; Fri, 8 Jun 2018 10:22:08 +0000 (UTC) Delivered-To: dm-devel@redhat.com Received: from mx1.redhat.com (ext-mx17.extmail.prod.ext.phx2.redhat.com [10.5.110.46]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C6566A112F; Fri, 8 Jun 2018 10:22:06 +0000 (UTC) Received: from smtp2.provo.novell.com (smtp2.provo.novell.com [137.65.250.81]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 28D4B30C10F8; Fri, 8 Jun 2018 10:22:05 +0000 (UTC) Received: from apollon.suse.de.de (prv-ext-foundry1int.gns.novell.com [137.65.251.240]) by smtp2.provo.novell.com with ESMTP (TLS encrypted); Fri, 08 Jun 2018 04:21:54 -0600 From: Martin Wilck To: Christophe Varoqui Date: Fri, 8 Jun 2018 12:20:41 +0200 Message-Id: <20180608102041.22904-29-mwilck@suse.com> In-Reply-To: <20180608102041.22904-1-mwilck@suse.com> References: <20180608102041.22904-1-mwilck@suse.com> X-Greylist: Sender passed SPF test, Sender IP whitelisted by DNSRBL, ACL 207 matched, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.46]); Fri, 08 Jun 2018 10:22:05 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.46]); Fri, 08 Jun 2018 10:22:05 +0000 (UTC) for IP:'137.65.250.81' DOMAIN:'smtp2.provo.novell.com' HELO:'smtp2.provo.novell.com' FROM:'mwilck@suse.com' RCPT:'' X-RedHat-Spam-Score: -2.301 (RCVD_IN_DNSWL_MED, SPF_PASS) 137.65.250.81 smtp2.provo.novell.com 137.65.250.81 smtp2.provo.novell.com X-Scanned-By: MIMEDefang 2.84 on 10.5.110.46 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.27 X-loop: dm-devel@redhat.com Cc: dm-devel@redhat.com, Xose Vazquez Perez , Martin Wilck Subject: [dm-devel] [PATCH 28/28] multipath.conf(5): various corrections and clarifications X-BeenThere: dm-devel@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: device-mapper development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: dm-devel-bounces@redhat.com Errors-To: dm-devel-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.49]); Fri, 08 Jun 2018 10:22:16 +0000 (UTC) X-Virus-Scanned: ClamAV using ClamSMTP ... related to the topics of option precedence, and config file syntax in general. Signed-off-by: Martin Wilck --- multipath/multipath.conf.5 | 174 +++++++++++++++++++++++-------------- 1 file changed, 111 insertions(+), 63 deletions(-) diff --git a/multipath/multipath.conf.5 b/multipath/multipath.conf.5 index f6897954..044204a1 100644 --- a/multipath/multipath.conf.5 +++ b/multipath/multipath.conf.5 @@ -85,6 +85,16 @@ the indentation shown in the above example is helpful for human readers but not mandatory. .LP . +.LP +.B Note on regular expressions: +The \fImultipath.conf\fR syntax allows many attribute values to be specified as POSIX +Extended Regular Expressions (see \fBregex\fR(7)). These regular expressions +are \fBcase sensitive\fR and \fBnot anchored\fR, thus the expression "bar" matches "barbie", +"rhabarber", and "wunderbar", but not "Barbie". To avoid unwanted substring +matches, standard regular expression syntax using the special characters "^" and "$" can be used. +. +.LP +. The following \fIsection\fP keywords are recognized: .TP 17 .B defaults @@ -104,10 +114,12 @@ multipath topology discovery, despite being listed in the .B multipaths This section defines the multipath topologies. They are indexed by a \fIWorld Wide Identifier\fR(WWID). For details on the WWID generation -see section \fIWWID generation\fR below. +see section \fIWWID generation\fR below. Attributes set in this section take +precedence over all others. .TP .B devices -This section defines the device-specific settings. +This section defines the device-specific settings. Devices are identified by +vendor, product, and revision. .TP .B overrides This section defines values for attributes that should override the @@ -1114,100 +1126,112 @@ The default is \fBno\fR . . .\" ---------------------------------------------------------------------------- -.SH "blacklist section" +.SH "blacklist and blacklist_exceptions sections" .\" ---------------------------------------------------------------------------- . -The \fIblacklist\fR section is used to exclude specific device from inclusion in -the multipath topology. It is most commonly used to exclude local disks or LUNs -for the array controller. +The \fIblacklist\fR section is used to exclude specific devices from +the multipath topology. It is most commonly used to exclude local disks or +non-disk devices (such as LUNs for the storage array controller) from +being handled by multipath-tools. .LP . . -The following keywords are recognized: +The \fIblacklist_exceptions\fR section is used to revert the actions of the +\fIblacklist\fR section. This allows one to selectively include ("whitelist") devices which +would normally be excluded via the \fIblacklist\fR section. A common usage is +to blacklist "everything" using a catch-all regular expression, and create +specific blacklist_exceptions entries for those devices that should be handled +by multipath-tools. +.LP +. +. +The following keywords are recognized in both sections. The defaults are empty +unless explicitly stated. .TP 17 .B devnode -Regular expression of the device nodes to be excluded. +Regular expression matching the device nodes to be excluded/included. .RS -.TP -The default is: \fB^(ram|raw|loop|fd|md|dm-|sr|scd|st|dcssblk)[0-9]\fR and \fB^(td|hd|vd)[a-z]\fR +.PP +The default \fIblacklist\fR consists of the regular expressions +"^(ram|raw|loop|fd|md|dm-|sr|scd|st|dcssblk)[0-9]" and +"^(td|hd|vd)[a-z]". This causes virtual devices, non-disk devices, and some other +device types to be excluded from multipath handling by default. .RE .TP .B wwid -The \fIWorld Wide Identification\fR of a device. -.TP -.B property -Regular expression of the udev property to be excluded. +Regular expression for the \fIWorld Wide Identifier\fR of a device to be excluded/included. +. .TP .B device Subsection for the device description. This subsection recognizes the .B vendor and .B product -keywords. For a full description of these keywords please see the +keywords. Both are regular expressions. For a full description of these keywords please see the \fIdevices\fR section description. -. -. -.\" ---------------------------------------------------------------------------- -.SH "blacklist_exceptions section" -.\" ---------------------------------------------------------------------------- -. -The \fIblacklist_exceptions\fR section is used to revert the actions of the -\fIblacklist\fR section. For example to include specific device in the -multipath topology. This allows one to selectively include devices which -would normally be excluded via the \fIblacklist\fR section. -.LP -. -. -The following keywords are recognized: -.TP 17 -.B devnode -Regular expression of the device nodes to be whitelisted. -.TP -.B wwid -The \fIWorld Wide Identification\fR of a device. .TP .B property -Regular expression of the udev property to be whitelisted. +Regular expression for an udev property. All +devices that have matching udev properties will be excluded/included. +The handling of the \fIproperty\fR keyword is special, +because devices \fBmust\fR have at least one whitelisted udev property; +otherwise they're treated as blacklisted, and the message +"\fIblacklisted, udev property missing\fR" is displayed in the logs. +. .RS -.TP -The default is: \fB(SCSI_IDENT_|ID_WWN)\fR +.PP +The default \fIblacklist exception\fR is: \fB(SCSI_IDENT_|ID_WWN)\fR, causing +well-behaved SCSI devices and devices that provide a WWN (World Wide Number) +to be included, and all others to be excluded. .RE -.TP -.B device -Subsection for the device description. This subsection recognizes the -.B vendor -and -.B product -keywords. For a full description of these keywords please see the \fIdevices\fR -section description. .LP -The \fIproperty\fR blacklist and whitelist handling is different from the usual -handling in the sense that the whitelist \fIhas\fR to be set, otherwise the -device will be blacklisted. In these cases the message \fIblacklisted, udev -property missing\fR will be displayed. +For every device, these 4 blacklist criteria are evaluated in the the order +"property, dev\%node, device, wwid". If a device turns out to be +blacklisted by any criterion, it's excluded from handling by multipathd, and +the later criteria aren't evaluated any more. For each +criterion, the whitelist takes precedence over the blacklist if a device +matches both. +.LP +.B +Note: +Besides the blacklist and whitelist, other configuration options such as +\fIfind_multipaths\fR have an impact on +whether or not a given device is handled by multipath-tools. . . .\" ---------------------------------------------------------------------------- .SH "multipaths section" .\" ---------------------------------------------------------------------------- . +The \fImultipaths\fR section allows setting attributes of multipath maps. The +attributes that are set via the multipaths section (see list below) take +precedence over all other configuration settings, including those from the +\fIoverrides\fR section. +.LP The only recognized attribute for the \fImultipaths\fR section is the -\fImultipath\fR subsection. +\fImultipath\fR subsection. If there are multiple \fImultipath\fR subsections +matching a given WWID, the contents of these sections are merged, and settings +from later entries take precedence. .LP . . The \fImultipath\fR subsection recognizes the following attributes: .TP 17 .B wwid -(Mandatory) Index of the container. +(Mandatory) World Wide Identifier. Detected multipath maps are matched agains this attribute. +Note that, unlike the \fIwwid\fR attribute in the \fIblacklist\fR section, +this is \fBnot\fR a regular expression or a substring; WWIDs must match +exactly inside the multipaths section. .TP .B alias -Symbolic name for the multipath map. +Symbolic name for the multipath map. This takes precedence over a an entry for +the same WWID in the \fIbindings_file\fR. .LP . . The following attributes are optional; if not set the default values -are taken from the \fIdefaults\fR or \fIdevices\fR section: +are taken from the \fIoverrides\fR, \fIdevices\fR, or \fIdefaults\fR +section: .sp 1 .PD .1v .RS @@ -1266,26 +1290,46 @@ are taken from the \fIdefaults\fR or \fIdevices\fR section: .SH "devices section" .\" ---------------------------------------------------------------------------- . +\fImultipath-tools\fR have a built-in device table with reasonable defaults +for more than 100 known multipath-capable storage devices. The devices section +can be used to override these settings. If there are multiple matches for a +given device, the attributes of all matching entries are applied to it. +If an attribute is specified in several matching device subsections, +later entries take precedence. Thus, entries in files under \fIconfig_dir\fR (in +reverse alphabetical order) have the highest precedence, followed by entries +in \fImultipath.conf\fR; the built-in hardware table has the lowest +precedence. Inside a configuration file, later entries have higher precedence +than earlier ones. +.LP The only recognized attribute for the \fIdevices\fR section is the \fIdevice\fR -subsection. +subsection. Devices detected in the system are matched against the device entries +using the \fBvendor\fR, \fBproduct\fR, and \fBrevision\fR fields, which are +all POSIX Extended regular expressions (see \fBregex\fR(7)). +.LP +The vendor, product, and revision fields that multipath or multipathd detect for +devices in a system depend on the device type. For SCSI devices, they correspond to the +respective fields of the SCSI INQUIRY page. In general, the command '\fImultipathd show +paths format "%d %s"\fR' command can be used to see the detected properties +for all devices in the system. .LP -. . The \fIdevice\fR subsection recognizes the following attributes: -.TP -vendor, product, revision and product_blacklist are POSIX Extended regex. .TP 17 .B vendor -(Mandatory) Vendor identifier. +(Mandatory) Regular expression to match the vendor name. .TP .B product -(Mandatory) Product identifier. +(Mandatory) Regular expression to match the product name. .TP .B revision -Revision identfier. +Regular expression to match the product revision. If not specified, any +revision matches. .TP .B product_blacklist -Product strings to blacklist for this vendor. +Products with the given \fBvendor\fR matching this string are +blacklisted. This is equivalent to a \fBdevice\fR entry in the \fIblacklist\fR +section with the \fIvendor\fR attribute set to this entry's \fIvendor\fR, and +the \fIproduct\fR attribute set to the value of \fIproduct_blacklist\fR. .TP .B alias_prefix The user_friendly_names prefix to use for this @@ -1475,8 +1519,12 @@ Multipath uses a \fIWorld Wide Identification\fR (WWID) to determine which paths belong to the same device. Each path presenting the same WWID is assumed to point to the same device. .LP -The WWID is generated by three methods (in the order of preference): +The WWID is generated by four methods (in the order of preference): .TP 17 +.B uid_attrs +The WWID is derived from udev attributes by matching the device node name. See +description of \fIuid_attrs\fR in the defaults section above. +.TP .B getuid_callout Use the specified external program; cf \fIgetuid_callout\fR above. Care should be taken when using this method; the external program