3 # vdev_id: udev helper to generate user-friendly names for JBOD disks
5 # This script parses the file /etc/zfs/vdev_id.conf to map a
6 # physical path in a storage topology to a channel name. The
7 # channel name is combined with a disk enclosure slot number to
8 # create an alias that reflects the physical location of the drive.
9 # This is particularly helpful when it comes to tasks like replacing
10 # failed drives. Slot numbers may also be re-mapped in case the
11 # default numbering is unsatisfactory. The drive aliases will be
12 # created as symbolic links in /dev/disk/by-vdev.
14 # The currently supported topologies are sas_direct and sas_switch.
15 # A multipath mode is supported in which dm-mpath devices are
16 # handled by examining the first-listed running component disk. In
17 # multipath mode the configuration file should contain a channel
18 # definition with the same name for each path to a given enclosure.
20 # The alias keyword provides a simple way to map already-existing
21 # device symlinks to more convenient names. It is suitable for
22 # small, static configurations or for sites that have some automated
23 # way to generate the mapping file.
26 # Some example configuration files are given below.
29 # # Example vdev_id.conf - sas_direct.
37 # # PCI_ID HBA PORT CHANNEL NAME
43 # # Custom mapping for Channel A
52 # # Default mapping for B, C, and D
59 # # Example vdev_id.conf - sas_switch
64 # # SWITCH PORT CHANNEL NAME
71 # # Example vdev_id.conf - multipath
76 # # PCI_ID HBA PORT CHANNEL NAME
83 # # Example vdev_id.conf - alias
87 # # name fully qualified or base name of device link
88 # alias d1 /dev/disk/by-id/wwn-0x5000c5002de3b9ca
89 # alias d2 wwn-0x5000c5002def789e
91 PATH=/bin:/sbin:/usr/bin:/usr/sbin
92 CONFIG=/etc/zfs/vdev_id.conf
102 vdev_id <-d device> [-c config_file] [-p phys_per_port]
103 [-g sas_direct|sas_switch|scsi] [-m]
105 -c specify name of an alternative config file [default=$CONFIG]
106 -d specify basename of device (i.e. sda)
107 -e Create enclose device symlinks only (/dev/by-enclosure)
108 -g Storage network topology [default="$TOPOLOGY"]
109 -m Run in multipath mode
110 -p number of phy's per switch port [default=$PHYS_PER_PORT]
120 MAPPED_SLOT=`awk "\\$1 == \"slot\" && \\$2 == ${LINUX_SLOT} && \
121 \\$4 ~ /^${CHANNEL}$|^$/ { print \\$3; exit }" $CONFIG`
122 if [ -z "$MAPPED_SLOT" ] ; then
123 MAPPED_SLOT=$LINUX_SLOT
125 printf "%d" ${MAPPED_SLOT}
135 MAPPED_CHAN=`awk "\\$1 == \"channel\" && \\$2 == ${PORT} \
136 { print \\$3; exit }" $CONFIG`
139 MAPPED_CHAN=`awk "\\$1 == \"channel\" && \
140 \\$2 == \"${PCI_ID}\" && \\$3 == ${PORT} \
141 { print \\$4; exit }" $CONFIG`
144 printf "%s" ${MAPPED_CHAN}
148 if [ -z "$PHYS_PER_PORT" ] ; then
149 PHYS_PER_PORT=`awk "\\$1 == \"phys_per_port\" \
150 {print \\$2; exit}" $CONFIG`
152 PHYS_PER_PORT=${PHYS_PER_PORT:-4}
153 if ! echo $PHYS_PER_PORT | grep -q -E '^[0-9]+$' ; then
154 echo "Error: phys_per_port value $PHYS_PER_PORT is non-numeric"
158 if [ -z "$MULTIPATH_MODE" ] ; then
159 MULTIPATH_MODE=`awk "\\$1 == \"multipath\" \
160 {print \\$2; exit}" $CONFIG`
163 # Use first running component device if we're handling a dm-mpath device
164 if [ "$MULTIPATH_MODE" = "yes" ] ; then
165 # If udev didn't tell us the UUID via DM_NAME, check /dev/mapper
166 if [ -z "$DM_NAME" ] ; then
167 DM_NAME=`ls -l --full-time /dev/mapper |
168 awk "/\/$DEV$/{print \\$9}"`
171 # For raw disks udev exports DEVTYPE=partition when
172 # handling partitions, and the rules can be written to
173 # take advantage of this to append a -part suffix. For
174 # dm devices we get DEVTYPE=disk even for partitions so
175 # we have to append the -part suffix directly in the
177 if [ "$DEVTYPE" != "partition" ] ; then
178 PART=`echo $DM_NAME | awk -Fp '/p/{print "-part"$2}'`
181 # Strip off partition information.
182 DM_NAME=`echo $DM_NAME | sed 's/p[0-9][0-9]*$//'`
183 if [ -z "$DM_NAME" ] ; then
187 # Get the raw scsi device name from multipath -ll. Strip off
188 # leading pipe symbols to make field numbering consistent.
189 DEV=`multipath -ll $DM_NAME |
190 awk '/running/{gsub("^[|]"," "); print $3 ; exit}'`
191 if [ -z "$DEV" ] ; then
196 if echo $DEV | grep -q ^/devices/ ; then
199 sys_path=`udevadm info -q path -p /sys/block/$DEV 2>/dev/null`
202 # Use positional parameters as an ad-hoc array
203 set -- $(echo "$sys_path" | tr / ' ')
207 # Get path up to /sys/.../hostX
209 while [ $i -le $num_dirs ] ; do
210 d=$(eval echo \${$i})
211 scsi_host_dir="$scsi_host_dir/$d"
212 echo $d | grep -q -E '^host[0-9]+$' && break
216 if [ $i = $num_dirs ] ; then
220 PCI_ID=$(eval echo \${$(($i -1))} | awk -F: '{print $2":"$3}')
222 # In sas_switch mode, the directory four levels beneath
223 # /sys/.../hostX contains symlinks to phy devices that reveal
224 # the switch port number. In sas_direct mode, the phy links one
225 # directory down reveal the HBA port.
226 port_dir=$scsi_host_dir
228 "sas_switch") j=$(($i + 4)) ;;
229 "sas_direct") j=$(($i + 1)) ;;
233 while [ $i -le $j ] ; do
234 port_dir="$port_dir/$(eval echo \${$i})"
238 PHY=`ls -d $port_dir/phy* 2>/dev/null | head -1 | awk -F: '{print $NF}'`
239 if [ -z "$PHY" ] ; then
242 PORT=$(( $PHY / $PHYS_PER_PORT ))
244 # Look in /sys/.../sas_device/end_device-X for the bay_identifier
246 end_device_dir=$port_dir
247 while [ $i -lt $num_dirs ] ; do
248 d=$(eval echo \${$i})
249 end_device_dir="$end_device_dir/$d"
250 if echo $d | grep -q '^end_device' ; then
251 end_device_dir="$end_device_dir/sas_device/$d"
260 SLOT=`cat $end_device_dir/bay_identifier 2>/dev/null`
263 SLOT=`cat $end_device_dir/phy_identifier 2>/dev/null`
266 d=$(eval echo \${$i})
267 SLOT=`echo $d | sed -e 's/^.*://'`
271 d=$(eval echo \${$i})
272 SLOT=`echo $d | sed -e 's/^.*://'`
276 d=$(eval echo \${$i})
277 SLOT=`echo $d | sed -e 's/^.*://'`
280 # look for this SAS path in all SCSI Enclosure Services
282 sas_address=`cat $end_device_dir/sas_address 2>/dev/null`
283 enclosures=`lsscsi -g | \
284 sed -n -e '/enclosu/s/^.* \([^ ][^ ]*\) *$/\1/p'`
285 for enclosure in $enclosures; do
286 set -- $(sg_ses -p aes $enclosure | \
287 awk "/device slot number:/{slot=\$12} \
288 /SAS address: $sas_address/\
291 if [ -n "$SLOT" ] ; then
297 if [ -z "$SLOT" ] ; then
301 CHAN=`map_channel $PCI_ID $PORT`
302 SLOT=`map_slot $SLOT $CHAN`
303 if [ -z "$CHAN" ] ; then
306 echo ${CHAN}${SLOT}${PART}
310 if [ -z "$FIRST_BAY_NUMBER" ] ; then
311 FIRST_BAY_NUMBER=`awk "\\$1 == \"first_bay_number\" \
312 {print \\$2; exit}" $CONFIG`
314 FIRST_BAY_NUMBER=${FIRST_BAY_NUMBER:-0}
316 if [ -z "$PHYS_PER_PORT" ] ; then
317 PHYS_PER_PORT=`awk "\\$1 == \"phys_per_port\" \
318 {print \\$2; exit}" $CONFIG`
320 PHYS_PER_PORT=${PHYS_PER_PORT:-4}
321 if ! echo $PHYS_PER_PORT | grep -q -E '^[0-9]+$' ; then
322 echo "Error: phys_per_port value $PHYS_PER_PORT is non-numeric"
326 if [ -z "$MULTIPATH_MODE" ] ; then
327 MULTIPATH_MODE=`awk "\\$1 == \"multipath\" \
328 {print \\$2; exit}" $CONFIG`
331 # Use first running component device if we're handling a dm-mpath device
332 if [ "$MULTIPATH_MODE" = "yes" ] ; then
333 # If udev didn't tell us the UUID via DM_NAME, check /dev/mapper
334 if [ -z "$DM_NAME" ] ; then
335 DM_NAME=`ls -l --full-time /dev/mapper |
336 awk "/\/$DEV$/{print \\$9}"`
339 # For raw disks udev exports DEVTYPE=partition when
340 # handling partitions, and the rules can be written to
341 # take advantage of this to append a -part suffix. For
342 # dm devices we get DEVTYPE=disk even for partitions so
343 # we have to append the -part suffix directly in the
345 if [ "$DEVTYPE" != "partition" ] ; then
346 PART=`echo $DM_NAME | awk -Fp '/p/{print "-part"$2}'`
349 # Strip off partition information.
350 DM_NAME=`echo $DM_NAME | sed 's/p[0-9][0-9]*$//'`
351 if [ -z "$DM_NAME" ] ; then
355 # Get the raw scsi device name from multipath -ll. Strip off
356 # leading pipe symbols to make field numbering consistent.
357 DEV=`multipath -ll $DM_NAME |
358 awk '/running/{gsub("^[|]"," "); print $3 ; exit}'`
359 if [ -z "$DEV" ] ; then
364 if echo $DEV | grep -q ^/devices/ ; then
367 sys_path=`udevadm info -q path -p /sys/block/$DEV 2>/dev/null`
370 # expect sys_path like this, for example:
371 # /devices/pci0000:00/0000:00:0b.0/0000:09:00.0/0000:0a:05.0/0000:0c:00.0/host3/target3:1:0/3:1:0:21/block/sdv
373 # Use positional parameters as an ad-hoc array
374 set -- $(echo "$sys_path" | tr / ' ')
378 # Get path up to /sys/.../hostX
380 while [ $i -le $num_dirs ] ; do
381 d=$(eval echo \${$i})
382 scsi_host_dir="$scsi_host_dir/$d"
383 echo $d | grep -q -E '^host[0-9]+$' && break
387 if [ $i = $num_dirs ] ; then
391 PCI_ID=$(eval echo \${$(($i -1))} | awk -F: '{print $2":"$3}')
393 # In scsi mode, the directory two levels beneath
394 # /sys/.../hostX reveals the port and slot.
395 port_dir=$scsi_host_dir
399 while [ $i -le $j ] ; do
400 port_dir="$port_dir/$(eval echo \${$i})"
404 set -- $(echo $port_dir | sed -e 's/^.*:\([^:]*\):\([^:]*\)$/\1 \2/')
406 SLOT=$(($2 + $FIRST_BAY_NUMBER))
408 if [ -z "$SLOT" ] ; then
412 CHAN=`map_channel $PCI_ID $PORT`
413 SLOT=`map_slot $SLOT $CHAN`
414 if [ -z "$CHAN" ] ; then
417 echo ${CHAN}${SLOT}${PART}
420 # Figure out the name for the enclosure symlink
421 enclosure_handler () {
422 # We get all the info we need from udev's DEVPATH variable:
424 # DEVPATH=/sys/devices/pci0000:00/0000:00:03.0/0000:05:00.0/host0/subsystem/devices/0:0:0:0/scsi_generic/sg0
426 # Get the enclosure ID ("0:0:0:0")
427 ENC=$(basename $(readlink -m "/sys/$DEVPATH/../.."))
428 if [ ! -d /sys/class/enclosure/$ENC ] ; then
429 # Not an enclosure, bail out
433 # Get the long sysfs device path to our enclosure. Looks like:
434 # /devices/pci0000:00/0000:00:03.0/0000:05:00.0/host0/port-0:0/ ... /enclosure/0:0:0:0
436 ENC_DEVICE=$(readlink /sys/class/enclosure/$ENC)
438 # Grab the full path to the hosts port dir:
439 # /devices/pci0000:00/0000:00:03.0/0000:05:00.0/host0/port-0:0
440 PORT_DIR=$(echo $ENC_DEVICE | grep -Eo '.+host[0-9]+/port-[0-9]+:[0-9]+')
442 # Get the port number
443 PORT_ID=$(echo $PORT_DIR | grep -Eo "[0-9]+$")
445 # The PCI directory is two directories up from the port directory
446 # /sys/devices/pci0000:00/0000:00:03.0/0000:05:00.0
447 PCI_ID_LONG=$(basename $(readlink -m "/sys/$PORT_DIR/../.."))
449 # Strip down the PCI address from 0000:05:00.0 to 05:00.0
450 PCI_ID=$(echo "$PCI_ID_LONG" | sed -r 's/^[0-9]+://g')
452 # Name our device according to vdev_id.conf (like "L0" or "U1").
453 NAME=$(awk "/channel/{if (\$1 == \"channel\" && \$2 == \"$PCI_ID\" && \
454 \$3 == \"$PORT_ID\") {print \$4int(count[\$4])}; count[\$4]++}" $CONFIG)
460 # Special handling is needed to correctly append a -part suffix
461 # to partitions of device mapper devices. The DEVTYPE attribute
462 # is normally set to "disk" instead of "partition" in this case,
463 # so the udev rules won't handle that for us as they do for
464 # "plain" block devices.
466 # For example, we may have the following links for a device and its
469 # /dev/disk/by-id/dm-name-isw_dibgbfcije_ARRAY0 -> ../../dm-0
470 # /dev/disk/by-id/dm-name-isw_dibgbfcije_ARRAY0p1 -> ../../dm-1
471 # /dev/disk/by-id/dm-name-isw_dibgbfcije_ARRAY0p2 -> ../../dm-3
473 # and the following alias in vdev_id.conf.
475 # alias A0 dm-name-isw_dibgbfcije_ARRAY0
477 # The desired outcome is for the following links to be created
478 # without having explicitly defined aliases for the partitions.
480 # /dev/disk/by-vdev/A0 -> ../../dm-0
481 # /dev/disk/by-vdev/A0-part1 -> ../../dm-1
482 # /dev/disk/by-vdev/A0-part2 -> ../../dm-3
484 # Warning: The following grep pattern will misidentify whole-disk
485 # devices whose names end with 'p' followed by a string of
486 # digits as partitions, causing alias creation to fail. This
487 # ambiguity seems unavoidable, so devices using this facility
488 # must not use such names.
490 if echo $DM_NAME | grep -q -E 'p[0-9][0-9]*$' ; then
491 if [ "$DEVTYPE" != "partition" ] ; then
492 DM_PART=`echo $DM_NAME | awk -Fp '/p/{print "-part"$2}'`
496 # DEVLINKS attribute must have been populated by already-run udev rules.
497 for link in $DEVLINKS ; do
498 # Remove partition information to match key of top-level device.
499 if [ -n "$DM_PART" ] ; then
500 link=`echo $link | sed 's/p[0-9][0-9]*$//'`
502 # Check both the fully qualified and the base name of link.
503 for l in $link `basename $link` ; do
504 alias=`awk "\\$1 == \"alias\" && \\$3 == \"${l}\" \
505 { print \\$2; exit }" $CONFIG`
506 if [ -n "$alias" ] ; then
507 echo ${alias}${DM_PART}
514 while getopts 'c:d:eg:mp:h' OPTION; do
523 # When udev sees a scsi_generic device, it calls this script with -e to
524 # create the enclosure device symlinks only. We also need
525 # "enclosure_symlinks yes" set in vdev_id.config to actually create the
527 ENCLOSURE_MODE=$(awk '{if ($1 == "enclosure_symlinks") print $2}' $CONFIG)
528 if [ "$ENCLOSURE_MODE" != "yes" ] ; then
536 PHYS_PER_PORT=${OPTARG}
547 if [ ! -r $CONFIG ] ; then
551 if [ -z "$DEV" ] && [ -z "$ENCLOSURE_MODE" ] ; then
552 echo "Error: missing required option -d"
556 if [ -z "$TOPOLOGY" ] ; then
557 TOPOLOGY=`awk "\\$1 == \"topology\" {print \\$2; exit}" $CONFIG`
560 if [ -z "$BAY" ] ; then
561 BAY=`awk "\\$1 == \"slot\" {print \\$2; exit}" $CONFIG`
564 TOPOLOGY=${TOPOLOGY:-sas_direct}
566 # Should we create /dev/by-enclosure symlinks?
567 if [ "$ENCLOSURE_MODE" = "yes" ] && [ "$TOPOLOGY" = "sas_direct" ] ; then
568 ID_ENCLOSURE=$(enclosure_handler)
569 if [ -z "$ID_ENCLOSURE" ] ; then
573 # Just create the symlinks to the enclosure devices and then exit.
574 ENCLOSURE_PREFIX=$(awk '/enclosure_symlinks_prefix/{print $2}' $CONFIG)
575 if [ -z "$ENCLOSURE_PREFIX" ] ; then
576 ENCLOSURE_PREFIX="enc"
578 echo "ID_ENCLOSURE=$ID_ENCLOSURE"
579 echo "ID_ENCLOSURE_PATH=by-enclosure/$ENCLOSURE_PREFIX-$ID_ENCLOSURE"
583 # First check if an alias was defined for this device.
584 ID_VDEV=`alias_handler`
586 if [ -z "$ID_VDEV" ] ; then
589 sas_direct|sas_switch)
590 ID_VDEV=`sas_handler`
593 ID_VDEV=`scsi_handler`
596 echo "Error: unknown topology $TOPOLOGY"
602 if [ -n "$ID_VDEV" ] ; then
603 echo "ID_VDEV=${ID_VDEV}"
604 echo "ID_VDEV_PATH=disk/by-vdev/${ID_VDEV}"