DEVLABEL(8)

NAME
devlabel - Consistent/persistent storage device access through symlinking

SYNOPSIS
devlabel [action] [options]

DESCRIPTION
devlabel is a script which manages symlinks to storage devices on your system. This is accomplished by utilizing the inherent unique identifiers (UUID) that each device *should* have in order to maintain a correctly pointing symlink in the event that the device name changes (eg. /dev/sdc1 becomes /dev/sdd1). By adding entries using devlabel its users can instead reference all devices by their symlink and no longer care what the true name of their device is. Similary, consistent raw device access can also be guaranteed through use of devlabel as it treats entries in the format of /dev/raw/raw# as a special form of symlink so that each raw device can consistently be bound to the correct storage device.

devlabel works with both IDE and SCSI storage and has been integrated into the hotplug system to allow USB, IEEE1394 (firewire) and PCI detection and consistency.

ACTIONS

reload
    Affirms the mappings of symlinks to storage devices. If a device cannot be found by its UUID, the existing symlink will be deleted. If the device name has changed, it will update the symlink. Both start and restart are synonyms for this command.

add [-d device] [-s symlink]
    Adds the entry symlink -> device and determines the UUID. The optional parameters --uid, --gid, --perms can also be used during an add to ensure consistent device accessibility across device renaming events. As well, alternatively, you can add by UUID if the correct UUID of the device is known. For this type of add you specify the [-s symlink] and the [-u UUID] of the device.

remove [-s symlink]
    Removes the entry symlink

status
    Returns the current status of all symlinks that are set to be configured. If the symlink is a raw device, it will return what major/minor combination it is bound to.

printid [-d device]
    Returns the identifier that devlabel finds for the device in question.

reverseremap
    Warning! ReverseRemap can be a dangerous action to your devlabel configuration. It wipes out the UUID values (column 3) from /etc/sysconfig/devlabel and using the last known device name (column 2), determines the UUID for that device and from then on devlabel will use that UUID to assure consistent access.

    You should only use this action if you know what you are doing. If a device renaming event has occurred on your system, using reverseremap will make devlabel ignore it and then think that no renaming event ever happened! ReverseRemap may come in handy when restoring your system or perhaps when upgrading between two versions of devlabel where the UUID format has been modified (eg. upgrading between the old devlabel which didn't use start sector values in the UUID to a newer devlabel which does).

OPTIONS

-d <device>
    The name of the device to be used for the specified action.

-s <symlink>
    The name of the symlink to be used.

-u <uuid>
    The UUID of the device to be used when adding by UUID. The -u option is currently only recognized during an add command. Normally you should not add by UUID unless you are using devlabel on a secondary node in a shared storage environment.

--uid <uid>
    The user id that the symlink should be set to when the symlink is made. The --uid option is currently only recognized during an add command.

--gid <gid>
    The group id that the symlink should be set to when the symlink is made. The --gid option is currently only recognized during an add command.

--perms <perissions>
    The permissions that the symlink should be set to when the symlink is made. The --perms option is currently only recognized during an add command.

--automount
    This option is only available during an add. If specified, it will cause this device to be automatically mounted every time devlabel is restarted if, within /etc/fstab , a corresponding entry is found for that symlink. If no entry is found, nothing will happen. Automount is stored as an option in the 4th field of the /etc/sysconfig/devlabel configuration file.

--multipath
    This option is only available during an add. If specified, it will treat the device as a multipath device and add symlinks to it accordingly. Symlinks will be added with the base symlink name with the suffix _multipath<#> to all devices which have the same UUID as the device given during the add. This option should only be used in multipath configurations where multiple devices exist to the same disk and thus return the same UUID. The multipath symlinks that are created with this option should then be used in /etc/raidtab to create your multipath device. This option should not be arbitrarily used just to subvert devlabel's protection against adding symlinks to non-unique devices as it won't give you the protection from device renaming that you seek.

-q  Quiet.

-v  Version.

FILES
/etc/sysconfig/devlabel
    The file containing all symlinks/rawdevices bindings to be made. This file should not be edited by hand. Instead, the devlabel program should be used to manipulate it.

METHODOLOGY
Devlabel first tries to find the uuid of the partition that you are attempting to add to devlabel by using the /usr/bin/partition_uuid program. Partition UUIDs are supported currently under ext2, ext3, xfs, jfs and ocfs. If no partition UUID can be found (or if it is not a partition you are adding) devlabel will then attempt to find either a SCSI uuid or IDE identifier.

To determine the unique identifier associated with a SCSI device, devlabel uses the program /usr/bin/scsi_unique_id. If this program cannot determine a unique identifier for your block device then the device cannot be used with devlabel.

Unique identifiers for SCSI devices are read from Page83 and Page80 of your SCSI block device as based on the SCSI standard. This program will look for identifiers in the order of: page 83 type 3, page 83 type 2, page 83 type 1, page 80, and then lastly page 83 type 0.

Unique identifiers for IDE devices are taken from /proc/ide/hd#/identify.

IDE and SCSI identifiers will be prefaced with their identifier type and concluded with the model name of the storage device and the start sector of the partition (if it is a partition). Partition UUIDs will be prefaced with their identifier type (P:), but are not concluded with any model name, start sector, etc. The entire string returned constitutes the device's UUID (for the sake of devlabel).

If two or more storage devices on your system return the same UUID, none of them may be used with devlabel

USAGE
Hotpluggable storage devices which show themselves as SCSI devices internally (eg. USB, firewire, but not PCMCIA) should have carefully chosen symlink names (eg. /dev/smartcardreader) as the UUIDs pulled from these devices are most likely being supplied by the connection hardware and not by the actual storage media itself.

If symlinks setup by devlabel are to be used within /etc/fstab , these symlinks must be located on the root partition so that they are accessable by /etc/rc.d/rc.sysinit during the boot-up process.

UUID NAMING CONVENTION
UUIDs are prefaced with a tag to alert devlabel as to where the identifier came from. Currently, devlabel supports Partition UUIDs, SCSI firmware identifiers and IDE identifiers.

P   Partition UUID

S83.3
    SCSI Page 83, Type 3 identifier

S83.2
    SCSI Page 83, Type 2 identifier

S83.1
    SCSI Page 83, Type 1 identifier

S80 SCSI Page 80 identifier (Serial Number)

S83.0
    SCSI Page 83, Type 0 identifier

I   IDE identifier as found in words 11-20 of /proc/ide/<device>/identify

AUTHOR
Gary Lerhaupt (gary_lerhaupt@dell.com)

WEBPAGE
http://www.lerhaupt.com/devlabel/