Difference between revisions of "Persistent block device naming"

From ArchWiki
Jump to navigation Jump to search
m
(fixed section fragments (interactive))
Tag: wiki-scripts
 
(103 intermediate revisions by 21 users not shown)
Line 4: Line 4:
 
[[es:Persistent block device naming]]
 
[[es:Persistent block device naming]]
 
[[it:Persistent block device naming]]
 
[[it:Persistent block device naming]]
[[zh-cn:持久化块设备命名法]]
+
[[ja:永続的なブロックデバイスの命名]]
 +
[[pt:Persistent block device naming]]
 +
[[zh-hans:Persistent block device naming]]
 +
[[zh-hant:UUID]]
 
{{Related articles start}}
 
{{Related articles start}}
 
{{Related|fstab}}
 
{{Related|fstab}}
Line 10: Line 13:
 
{{Related|LVM}}
 
{{Related|LVM}}
 
{{Related articles end}}
 
{{Related articles end}}
This article describes how to use persistent names for your block devices. This has been made possible by the introduction of udev and has some advantages over bus-based naming. If your machine has more than one SATA, SCSI or IDE disk controller, the order in which their corresponding device nodes are added is arbitrary. This may result in device names like {{ic|/dev/'''sda'''}} and {{ic|/dev/'''sdb'''}} switching around on each boot, culminating in an unbootable system, kernel panic, or a block device disappearing. Persistent naming solves these issues.
+
This article describes how to use persistent names for your [[block device]]s. This has been made possible by the introduction of [[udev]] and has some advantages over bus-based naming. If your machine has more than one SATA, SCSI or IDE disk controller, the order in which their corresponding device nodes are added is arbitrary. This may result in device names like {{ic|/dev/'''sda'''}} and {{ic|/dev/'''sdb'''}} switching around on each boot, culminating in an unbootable system, kernel panic, or a block device disappearing. Persistent naming solves these issues.
{{Note|If you are using [[LVM|LVM2]], this article is not relevant as LVM takes care of this automatically.}}
 
  
==Persistent naming methods==
+
{{Note|
 +
* Persistent naming has limits that are out-of-scope in this article. For example, while [[mkinitcpio]] may support a method, systemd may impose its own limits (e.g. {{Bug|42884}}) on naming it can process during boot.
 +
* This article is not relevant for [[LVM]] logical volumes as the {{ic|/dev/''VolumeGroupName''/''LogicalVolumeName''}} device paths are persistent.
 +
}}
 +
 
 +
== Persistent naming methods ==
 +
 
 +
There are four different schemes for persistent naming: [[#by-label|by-label]], [[#by-uuid|by-uuid]], [[#by-id and by-path|by-id and by-path]]. For those using disks with [[GUID Partition Table|GUID Partition Table (GPT)]], two additional schemes can be used [[#by-partlabel|by-partlabel]] and [[#by-partuuid|by-partuuid]]. You can also use [[#Static device names with udev|static device names by using Udev]].
  
There are four different schemes for persistent naming: [[#by-label|by-label]], [[#by-uuid|by-uuid]], [[#by-id and by-path|by-id and by-path]]. For those using disks with [[GUID Partition Table|GUID Partition Table (GPT)]], two additional schemes can be used [[#by-partlabel|by-partlabel]] and [[#by-partuuid|by-partuuid]]. You can also use [[#Static device names with Udev|static device names by using Udev]].
+
The directories in {{ic|/dev/disk/}} are created and destroyed dynamically, depending on whether there are devices in them.
  
The following sections describes what the different persistent naming methods are and how they are used.  
+
{{Note|Beware that [[Disk cloning]] creates two different disks with the same name.}}
  
The {{ic|lsblk -f}} command can be used for viewing graphically the first persistent schemes:
+
The following sections describe what the different persistent naming methods are and how they are used.
  
{{hc|$ lsblk -f|<nowiki>
+
The [[lsblk]] command can be used for viewing graphically the first persistent schemes:
NAME   FSTYPE LABEL UUID                                MOUNTPOINT
+
 
 +
{{hc|$ lsblk -f|
 +
NAME       FSTYPE LABEL     UUID                                MOUNTPOINT
 
sda                                                       
 
sda                                                       
├─sda1 vfat         CBB6-24F2                            /boot
+
├─sda1     vfat             CBB6-24F2                            /boot
├─sda2 ext4  SYSTEM 0a3407de-014b-458b-b5c1-848e92a327a3 /
+
├─sda2     ext4  Arch Linux 0a3407de-014b-458b-b5c1-848e92a327a3 /
├─sda3 ext4  DATA  b411dc99-f0a0-4c87-9e05-184977be8539 /home
+
├─sda3     ext4  Data      b411dc99-f0a0-4c87-9e05-184977be8539 /home
└─sda4 swap         f9fe0b69-a280-415d-a03a-a32752370dee [SWAP]
+
└─sda4     swap             f9fe0b69-a280-415d-a03a-a32752370dee [SWAP]
</nowiki>}}
+
mmcblk0
 +
└─mmcblk0p1 vfat              F4CA-5D75
 +
}}
  
For those using [[GUID Partition Table|GPT]], use the {{ic|blkid}} command instead. The latter is more convenient for scripts, but more difficult to read.
+
For those using [[GPT]], use the {{ic|blkid}} command instead. The latter is more convenient for scripts, but more difficult to read.
  
{{hc|$ blkid|<nowiki>
+
{{hc|# blkid|2=
/dev/sda1: UUID="CBB6-24F2" TYPE="vfat" PARTLABEL="EFI SYSTEM PARTITION" PARTUUID="d0d0d110-0a71-4ed6-936a-304969ea36af"  
+
/dev/sda1: UUID="CBB6-24F2" TYPE="vfat" PARTLABEL="EFI system partition" PARTUUID="d0d0d110-0a71-4ed6-936a-304969ea36af"  
/dev/sda2: LABEL="SYSTEM" UUID="0a3407de-014b-458b-b5c1-848e92a327a3" TYPE="ext4" PARTLABEL="GNU/LINUX" PARTUUID="98a81274-10f7-40db-872a-03df048df366"  
+
/dev/sda2: LABEL="Arch Linux" UUID="0a3407de-014b-458b-b5c1-848e92a327a3" TYPE="ext4" PARTLABEL="GNU/Linux" PARTUUID="98a81274-10f7-40db-872a-03df048df366"  
/dev/sda3: LABEL="DATA" UUID="b411dc99-f0a0-4c87-9e05-184977be8539" TYPE="ext4" PARTLABEL="HOME" PARTUUID="7280201c-fc5d-40f2-a9b2-466611d3d49e"  
+
/dev/sda3: LABEL="Data" UUID="b411dc99-f0a0-4c87-9e05-184977be8539" TYPE="ext4" PARTLABEL="Home" PARTUUID="7280201c-fc5d-40f2-a9b2-466611d3d49e"  
/dev/sda4: UUID="f9fe0b69-a280-415d-a03a-a32752370dee" TYPE="swap" PARTLABEL="SWAP" PARTUUID="039b6c1c-7553-4455-9537-1befbc9fbc5b"
+
/dev/sda4: UUID="f9fe0b69-a280-415d-a03a-a32752370dee" TYPE="swap" PARTLABEL="Swap" PARTUUID="039b6c1c-7553-4455-9537-1befbc9fbc5b"
</nowiki>
+
/dev/mmcblk0: PTUUID="0003e1e5" PTTYPE="dos"
 +
/dev/mmcblk0p1: UUID="F4CA-5D75" TYPE="vfat" PARTUUID="0003e1e5-01"
 
}}
 
}}
  
===by-label===
+
=== by-label ===
  
Almost every filesystem type can have a label. All your partitions that have one are listed in the {{ic|/dev/disk/by-label}} directory. This directory is created and destroyed dynamically, depending on whether you have partitions with labels attached.
+
Almost every [[File systems#Types of file systems|file system type]] can have a label. All your volumes that have one are listed in the {{ic|/dev/disk/by-label}} directory.
  
{{hc|$ ls -l /dev/disk/by-label|<nowiki>
+
{{hc|$ ls -l /dev/disk/by-label|
 
total 0
 
total 0
lrwxrwxrwx 1 root root 10 May 27 23:31 DATA -> ../../sda3
+
lrwxrwxrwx 1 root root 10 May 27 23:31 Data -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 SYSTEM -> ../../sda2
+
lrwxrwxrwx 1 root root 10 May 27 23:31 Arch\x20Linux -> ../../sda2
</nowiki>}}
+
}}
 +
 
 +
Most file systems support setting the label upon file system creation, see the [[man page]] of the relevant {{ic|mkfs.*}} utility. For some file systems it is also possible to change the labels. Following are some methods for changing labels on common file systems:
 +
 
 +
; swap : {{ic|swaplabel -L "''new label''" /dev/''XXX''}} using {{pkg|util-linux}}
 +
; ext2/3/4 : {{ic|e2label /dev/''XXX'' "''new label''"}} using {{pkg|e2fsprogs}}
 +
; btrfs : {{ic|btrfs filesystem label /dev/''XXX'' "''new label''"}} using {{pkg|btrfs-progs}}
 +
; reiserfs : {{ic|reiserfstune -l "''new label''" /dev/''XXX''}} using {{pkg|reiserfsprogs}}
 +
; jfs : {{ic|jfs_tune -L "''new label''" /dev/''XXX''}} using {{pkg|jfsutils}}
 +
; xfs : {{ic|xfs_admin -L "''new label''" /dev/''XXX''}} using {{pkg|xfsprogs}}
 +
; fat/vfat : {{ic|fatlabel /dev/''XXX'' "''new label''"}} using {{pkg|dosfstools}}
 +
: {{ic|mlabel -i /dev/''XXX'' ::"''new label''"}} using {{pkg|mtools}}
 +
; exfat : {{ic|exfatlabel /dev/''XXX'' "''new label''"}} using {{Pkg|exfat-utils}}
 +
; ntfs : {{ic|ntfslabel /dev/''XXX'' "''new label''"}} using {{pkg|ntfs-3g}}
 +
; udf : {{ic|udflabel /dev/''XXX'' "''new label''"}} using {{Pkg|udftools}}
 +
; crypto_LUKS (LUKS2 only) : {{ic|1=cryptsetup config --label="''new label''" /dev/''XXX''}} using {{Pkg|cryptsetup}}
 +
 
 +
The label of a device can be obtained with ''lsblk'':
  
The labels of your filesystems can be changed. Following are some methods for changing labels on common filesystems:
+
{{hc|$ lsblk -dno LABEL /dev/sda2|
 +
Arch Linux
 +
}}
  
; swap : {{ic|swaplabel -L <label> /dev/XXX}} using {{pkg|util-linux}}
+
Or with ''blkid'':
; ext2/3/4 : {{ic|e2label /dev/XXX <label>}} using {{pkg|e2fsprogs}}
+
 
; btrfs : {{ic|btrfs filesystem label /dev/XXX <label>}} using {{pkg|btrfs-progs}}
+
{{hc|# blkid -s LABEL -o value /dev/sda2|
; reiserfs : {{ic|reiserfstune -l <label> /dev/XXX}} using {{pkg|reiserfsprogs}}
+
Arch Linux
; jfs : {{ic|jfs_tune -L <label> /dev/XXX}} using {{pkg|jfsutils}}
+
}}
; xfs : {{ic|xfs_admin -L <label> /dev/XXX}} using {{pkg|xfsprogs}}
 
; fat/vfat : {{ic|dosfslabel /dev/XXX <label>}} using {{pkg|dosfstools}}
 
; fat/vfat : {{ic|mlabel -i /dev/XXX ::<label>}} using {{pkg|mtools}}
 
; ntfs : {{ic|ntfslabel /dev/XXX <label>}} using {{pkg|ntfs-3g}}
 
  
 
{{Note|
 
{{Note|
* Changing the filesystem label of the root partition has to be done from a "live" GNU/Linux distribution because the partition needs to be unmounted first.
+
* The file system must not be mounted to change its label. For the root file system this can be accomplished by booting from another volume.
* Labels have to be unambiguous to prevent any possible conflicts;
+
* Labels have to be unambiguous to prevent any possible conflicts.
* Labels can be up to 16 characters long.}}
+
* Labels can be up to 16 characters long.
 +
* Since the label is a property of the filesystem, it is not suitable for addressing a single RAID device persistently.
 +
* When using encrypted containers with [[dm-crypt]], the labels of filesystems inside of containers are not available while the container is locked/encrypted.
 +
}}
  
===by-uuid===
+
=== by-uuid ===
  
[[wikipedia:UUID|UUID]] is a mechanism to give each filesystem a unique identifier. These identifiers are generated by filesystem utilities (e.g. {{ic|mkfs.*}}) when the partition gets formatted and are designed so that collisions are unlikely. All GNU/Linux filesystems (including swap and LUKS headers of raw encrypted devices) support UUID. FAT and NTFS filesystems (''fat'' and ''windows'' labels above) do not support UUID, but are still listed in {{ic|/dev/disk/by-uuid}} with a shorter UID (unique identifier):
+
[[wikipedia:UUID|UUID]] is a mechanism to give each [[filesystem]] a unique identifier. These identifiers are generated by filesystem utilities (e.g. {{ic|mkfs.*}}) when the device gets formatted and are designed so that collisions are unlikely. All GNU/Linux filesystems (including swap and LUKS headers of raw encrypted devices) support UUID. FAT, exFAT and NTFS filesystems do not support UUID, but are still listed in {{ic|/dev/disk/by-uuid/}} with a shorter UID (unique identifier):
  
 
{{hc|$ ls -l /dev/disk/by-uuid/|
 
{{hc|$ ls -l /dev/disk/by-uuid/|
Line 77: Line 109:
 
lrwxrwxrwx 1 root root 10 May 27 23:31 CBB6-24F2 -> ../../sda1
 
lrwxrwxrwx 1 root root 10 May 27 23:31 CBB6-24F2 -> ../../sda1
 
lrwxrwxrwx 1 root root 10 May 27 23:31 f9fe0b69-a280-415d-a03a-a32752370dee -> ../../sda4
 
lrwxrwxrwx 1 root root 10 May 27 23:31 f9fe0b69-a280-415d-a03a-a32752370dee -> ../../sda4
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 F4CA-5D75 -> ../../mmcblk0p1
 +
}}
 +
 +
The UUID of a device can be obtained with ''lsblk'':
 +
 +
{{hc|$ lsblk -dno UUID /dev/sda1|
 +
CBB6-24F2
 
}}
 
}}
 +
 +
Or with ''blkid'':
 +
 +
{{hc|# blkid -s UUID -o value /dev/sda1|
 +
CBB6-24F2
 +
}}
  
 
The advantage of using the UUID method is that it is much less likely that name collisions occur than with labels. Further, it is generated automatically on creation of the filesystem. It will, for example, stay unique even if the device is plugged into another system (which may perhaps have a device with the same label).  
 
The advantage of using the UUID method is that it is much less likely that name collisions occur than with labels. Further, it is generated automatically on creation of the filesystem. It will, for example, stay unique even if the device is plugged into another system (which may perhaps have a device with the same label).  
  
The disadvantage is that UUIDs make long code lines hard to read and break formatting in many configuration files (e.g. fstab or crypttab). Also every time a partition is resized or reformatted a new UUID is generated and configs have to get adjusted (manually).
+
The disadvantage is that UUIDs make long code lines hard to read and break formatting in many configuration files (e.g. [[fstab]] or [[crypttab]]). Also every time a volume is reformatted a new UUID is generated and configuration files have to get manually adjusted.
 +
 
 +
{{Tip|In case your swap does not have an UUID assigned, you will need to reset it using the [[Swap#Swap partition|mkswap]] utility.}}
 +
 
 +
=== by-id and by-path ===
 +
 
 +
{{ic|by-id}} creates a unique name depending on the hardware serial number, {{ic|by-path}} depending on the shortest physical path (according to sysfs). Both contain strings to indicate which subsystem they belong to (i.e. {{ic|pci-}} for {{ic|by-path}}, and {{ic|ata-}} for {{ic|by-id}}), so they are linked to the hardware controlling the device. This implies different levels of persistence: the {{ic|by-path}} will already change when the device is plugged into a different port of the controller, the {{ic|by-id}} will change when the device is plugged into a port of a hardware controller subject to another subsystem. [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/Online_Storage_Reconfiguration_Guide/persistent_naming.html] Thus, both are not suitable to achieve persistent naming tolerant to hardware changes.
 +
 
 +
However, both provide important information to find a particular device in a large hardware infrastructure. For example, if you do not manually assign persistent labels ({{ic|by-label}} or {{ic|by-partlabel}}) and keep a directory with hardware port usage, {{ic|by-id}} and {{ic|by-path}} can be used to find a particular device.[http://linuxshellaccount.blogspot.in/2008/09/how-to-easily-find-wwns-of-qlogic-hba.html] [http://www.linuxquestions.org/questions/linux-server-73/how-to-find-wwn-for-dev-sdc-917269/]
 +
 
 +
{{ic|by-id}} also creates [[Wikipedia:World Wide Name|World Wide Name]] links of storage devices that support it. Unlike other {{ic|by-id}} links, WWNs are fully persistent and will not change depending on the used subsystem.
 +
 
 +
{{hc|$ ls -l /dev/disk/by-id/|
 +
total 0
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470 -> ../../sda
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part1 -> ../../sda1
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part2 -> ../../sda2
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part3 -> ../../sda3
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part4 -> ../../sda4
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 mmc-SD32G_0x0040006d -> ../../mmcblk0
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 mmc-SD32G_0x0040006d-part1 -> ../../mmcblk0p1
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f -> ../../sda
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f-part1 -> ../../sda1
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f-part2 -> ../../sda2
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f-part3 -> ../../sda3
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f-part4 -> ../../sda4
 +
}}
  
{{Tip|In case your swap partition does not have an UUID assigned, you will need to reset the swap partition using [[Swap#Swap partition|mkswap]] utility.}}
+
{{hc|$ ls -l /dev/disk/by-path/|
 +
total 0
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1 -> ../../sda
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1-part1 -> ../../sda1
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1-part2 -> ../../sda2
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1-part3 -> ../../sda3
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1-part4 -> ../../sda4
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:07:00.0-platform-rtsx_pci_sdmmc.0 -> ../../mmcblk0
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:07:00.0-platform-rtsx_pci_sdmmc.0-part1 -> ../../mmcblk0p1
 +
}}
  
===by-id and by-path===
+
=== by-partlabel ===
{{Accuracy|Elements provided in the [[Talk:Persistent_block_device_naming|Talk page]] (since 2011) seems to clearly indicate that {{ic|by-id}} and {{ic|by-path}} are valid ways to state persistent device names. Were they not, this section should be marked for deletion so as to not bring up confusion in this page dedicated to ''persistent device naming''.|section=by-path and by-id unsuitable?}}
 
{{ic|by-id}} creates a unique name depending on the hardware serial number, {{ic|by-path}} depending on the shortest physical path (according to sysfs). Both contain strings to indicate which subsystem they belong to (i.e. {{ic|-ide-}} for {{ic|by-path}}, and {{ic|-ata-}} for {{ic|by-id}}) and thus are not suitable for solving the problems mentioned in the beginning of this article. They will not be discussed any further here.
 
  
===by-partlabel===
 
 
{{Note|This method only concerns disks with [[GUID Partition Table|GUID Partition Table (GPT)]].}}
 
{{Note|This method only concerns disks with [[GUID Partition Table|GUID Partition Table (GPT)]].}}
  
Partition labels can be defined in the header of the partition entry on GPT disks.
+
GPT partition labels can be defined in the header of the [[Wikipedia:GUID Partition Table#Partition entries (LBA 2–33)|partition entry]] on GPT disks.
  
See also [[Wikipedia:GUID_Partition_Table#Partition_entries]].
+
This method is very similar to the [[#by-label|filesystem labels]], except the partition labels do not get affected if the file system on the partition is changed.
  
This method is very similar to the [[#by-label|filesystem labels]], excepted that the dynamic directory is {{ic|/dev/disk/by-partlabel}}.
+
All partitions that have partition labels are listed in the {{ic|/dev/disk/by-partlabel}} directory.
  
{{hc|ls -l /dev/disk/by-partlabel/|<nowiki>
+
{{hc|ls -l /dev/disk/by-partlabel/|
 
total 0
 
total 0
lrwxrwxrwx 1 root root 10 May 27 23:31 EFI\x20SYSTEM\x20PARTITION -> ../../sda1
+
lrwxrwxrwx 1 root root 10 May 27 23:31 EFI\x20system\x20partition -> ../../sda1
lrwxrwxrwx 1 root root 10 May 27 23:31 GNU\x2fLINUX -> ../../sda2
+
lrwxrwxrwx 1 root root 10 May 27 23:31 GNU\x2fLinux -> ../../sda2
lrwxrwxrwx 1 root root 10 May 27 23:31 HOME -> ../../sda3
+
lrwxrwxrwx 1 root root 10 May 27 23:31 Home -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 SWAP -> ../../sda4
+
lrwxrwxrwx 1 root root 10 May 27 23:31 Swap -> ../../sda4
</nowiki>}}
+
}}
 +
 
 +
The partition label of a device can be obtained with ''lsblk'':
 +
 
 +
{{hc|$ lsblk -dno PARTLABEL /dev/sda1|
 +
EFI system partition
 +
}}
 +
 
 +
Or with ''blkid'':
 +
 
 +
{{hc|# blkid -s PARTLABEL -o value /dev/sda1|
 +
EFI system partition
 +
}}
  
 
{{Note|
 
{{Note|
* GPT partition labels have also to be different to avoid conflicts. To change your partition label, you can use {{ic|gdisk}} or the ncurse-based version {{ic|cgdisk}}. Both are available from the {{Pkg|gptfdisk}} package. See [[Partitioning#Partitioning_tools]].
+
* GPT partition labels also have to be different to avoid conflicts. To change your partition label, you can use [[gdisk]] or the ncurses-based version [[cgdisk]]. Both are available from the {{Pkg|gptfdisk}} package. See [[Partitioning#Partitioning tools]].
* According to the specification, GPT partition labels can be up to 72 characters long.}}
+
* According to the specification, GPT partition labels can be up to 72 characters long.
 +
}}
  
===by-partuuid===
+
=== by-partuuid ===
{{Note|This method only concerns disks with [[GUID Partition Table|GUID Partition Table (GPT)]].}}
 
  
Like [[#by-partlabel|GPT partition labels]], GPT partition UUID are defined in the partition entry on GPT disks.  
+
Like [[#by-partlabel|GPT partition labels]], GPT partition UUIDs are defined in the [[Wikipedia:GUID Partition Table#Partition entries (LBA 2–33)|partition entry]] on GPT disks.
  
See also [[Wikipedia:GUID_Partition_Table#Partition_entries]].
+
MBR does not support partition UUIDs, but Linux[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d33b98fc82b0908e91fb05ae081acaed7323f9d2] and software using libblkid[https://git.kernel.org/pub/scm/utils/util-linux/util-linux.git/commit/?id=d67cc2889a0527b26d7bb8c76f2acac46751d673] (e.g. udev[https://github.com/systemd/systemd/pull/3293]) are capable of generating pseudo PARTUUIDs for MBR partitions. The format is {{ic|''SSSSSSSS''-''PP''}}, where {{ic|''SSSSSSSS''}} is a zero-filled 32-bit [[Wikipedia:Master boot record#Disk identity|MBR disk signature]], and {{ic|''PP''}} is a zero-filled partition number in hexadecimal form. Unlike a regular PARTUUID of a GPT partition, MBR's pseudo PARTUUID can change if the partition number changes.
  
The dynamic directory is similar to other methods and, like [[#by-uuid|UUID filesystems]], using UUIDs is prefered over labels.
+
The dynamic directory is similar to other methods and, like [[#by-uuid|filesystem UUIDs]], using UUIDs is preferred over labels.
  
{{hc|ls -l /dev/disk/by-partuuid/|<nowiki>
+
{{hc|ls -l /dev/disk/by-partuuid/|
 
total 0
 
total 0
 +
lrwxrwxrwx 1 root root 10 May 27 23:31 0003e1e5-01 -> ../../mmcblk0p1
 
lrwxrwxrwx 1 root root 10 May 27 23:31 039b6c1c-7553-4455-9537-1befbc9fbc5b -> ../../sda4
 
lrwxrwxrwx 1 root root 10 May 27 23:31 039b6c1c-7553-4455-9537-1befbc9fbc5b -> ../../sda4
 
lrwxrwxrwx 1 root root 10 May 27 23:31 7280201c-fc5d-40f2-a9b2-466611d3d49e -> ../../sda3
 
lrwxrwxrwx 1 root root 10 May 27 23:31 7280201c-fc5d-40f2-a9b2-466611d3d49e -> ../../sda3
 
lrwxrwxrwx 1 root root 10 May 27 23:31 98a81274-10f7-40db-872a-03df048df366 -> ../../sda2
 
lrwxrwxrwx 1 root root 10 May 27 23:31 98a81274-10f7-40db-872a-03df048df366 -> ../../sda2
 
lrwxrwxrwx 1 root root 10 May 27 23:31 d0d0d110-0a71-4ed6-936a-304969ea36af -> ../../sda1
 
lrwxrwxrwx 1 root root 10 May 27 23:31 d0d0d110-0a71-4ed6-936a-304969ea36af -> ../../sda1
</nowiki>
 
 
}}
 
}}
  
===Static device names with Udev===
+
The partition UUID of a device can be obtained with ''lsblk'':
  
See [[Udev#Setting static device names]].
+
{{hc|$ lsblk -dno PARTUUID /dev/sda1|
 +
d0d0d110-0a71-4ed6-936a-304969ea36af
 +
}}
  
==Using persistent naming==
+
Or with ''blkid'':
 +
 
 +
{{hc|# blkid -s PARTUUID -o value /dev/sda1|
 +
d0d0d110-0a71-4ed6-936a-304969ea36af
 +
}}
 +
 
 +
=== Static device names with udev ===
 +
 
 +
See [[udev#Setting static device names]].
 +
 
 +
== Using persistent naming ==
  
 
There are various applications that can be configured using persistent naming. Following are some examples of how to configure them.
 
There are various applications that can be configured using persistent naming. Following are some examples of how to configure them.
Line 138: Line 239:
 
=== fstab ===
 
=== fstab ===
  
See the main article: [[fstab#UUIDs]]
+
See the main article: [[fstab#Identifying filesystems]].
 +
 
 +
=== Kernel parameters ===
 +
 
 +
To use persistent names in [[kernel parameters]], the following prerequisites must be met. On a standard installation following the installation guide both prerequisites are met:
  
===Boot managers===
+
* You are using a [[mkinitcpio#Configuration|mkinitcpio]] initial RAM disk image
 +
* You have either udev or systemd hook enabled in {{ic|/etc/mkinitcpio.conf}}
  
To use persistent names in your boot manager, the following prerequisites must be met:
+
The location of the root filesystem is given by the parameter {{ic|root}} on the kernel command line. The kernel command line is configured from the [[boot loader]], see [[Kernel parameters#Configuration]]. To change to persistent device naming, only change the parameters which specify block devices, e.g. {{ic|root}} and {{ic|resume}}, while leaving other parameters as is. Various naming schemes are supported:
  
* You are using a [[Mkinitcpio#Configuration|mkinitcpio]] initial RAM disk image
+
Persistent device naming [[#by-label|using label]] and the {{ic|1=LABEL=}} format, in this example {{ic|Arch Linux}} is the LABEL of the root file system.
* You have udev enabled in {{ic|/etc/mkinitcpio.conf}}
 
  
In the above example, {{ic|/dev/sda1}} is the root partition. In the [[GRUB]] {{ic|grub.cfg}} file, the ''linux'' line looks like this:
+
root="LABEL=Arch Linux"
  
linux /boot/vmlinuz-linux root=/dev/sda1 rw quiet
+
Persistent device naming [[#by-uuid|using UUID]] and the {{ic|1=UUID=}} format, in this example {{ic|0a3407de-014b-458b-b5c1-848e92a327a3}} is the UUID of the root file system.
  
Depending on which naming scheme you would prefer, change it to one of the following:
+
root=UUID=0a3407de-014b-458b-b5c1-848e92a327a3
  
linux /boot/vmlinuz-linux root=/dev/disk/by-label/root_myhost rw quiet
+
Persistent device naming [[#by-id and by-path|using disk id]] and the {{ic|/dev}} path format, in this example {{ic|wwn-0x60015ee0000b237f-part2}} is the id of the root partition.
  
or:
+
root=/dev/disk/by-id/wwn-0x60015ee0000b237f-part2
  
linux /boot/vmlinuz-linux root=UUID=2d781b26-0285-421a-b9d0-d4a0d3b55680 rw quiet
+
Persistent device naming [[#by-partuuid|using GPT partition UUID]] and the {{ic|1=PARTUUID=}} format, in this example {{ic|98a81274-10f7-40db-872a-03df048df366}} is the PARTUUID of the root partition.
  
If you are using [[LILO]], then do not try this with the {{ic|1=root=...}} configuration option; it will not work. Use {{ic|1=append="root=..."}} or {{ic|1=addappend="root=..."}} instead. Read the LILO man page for more information on {{ic|append}} and {{ic|addappend}}.
+
root=PARTUUID=98a81274-10f7-40db-872a-03df048df366
  
There is an alternative way to use the label embedded in the filesystem. For example if (as above) the filesystem in {{ic|/dev/sda1}} is labeled {{ic|root_myhost}}, you would give this line to GRUB:
+
Persistent device naming [[#by-partlabel|using GPT partition label]] and the {{ic|1=PARTLABEL=}} format, in this example {{ic|GNU/Linux}} is the PARTLABEL of the root partition.
  
  linux /boot/vmlinuz-linux root=LABEL=root_myhost rw quiet
+
  root="PARTLABEL=GNU/Linux"

Latest revision as of 23:34, 8 December 2019

This article describes how to use persistent names for your block devices. This has been made possible by the introduction of udev and has some advantages over bus-based naming. If your machine has more than one SATA, SCSI or IDE disk controller, the order in which their corresponding device nodes are added is arbitrary. This may result in device names like /dev/sda and /dev/sdb switching around on each boot, culminating in an unbootable system, kernel panic, or a block device disappearing. Persistent naming solves these issues.

Note:
  • Persistent naming has limits that are out-of-scope in this article. For example, while mkinitcpio may support a method, systemd may impose its own limits (e.g. FS#42884) on naming it can process during boot.
  • This article is not relevant for LVM logical volumes as the /dev/VolumeGroupName/LogicalVolumeName device paths are persistent.

Persistent naming methods

There are four different schemes for persistent naming: by-label, by-uuid, by-id and by-path. For those using disks with GUID Partition Table (GPT), two additional schemes can be used by-partlabel and by-partuuid. You can also use static device names by using Udev.

The directories in /dev/disk/ are created and destroyed dynamically, depending on whether there are devices in them.

Note: Beware that Disk cloning creates two different disks with the same name.

The following sections describe what the different persistent naming methods are and how they are used.

The lsblk command can be used for viewing graphically the first persistent schemes:

$ lsblk -f
NAME        FSTYPE LABEL      UUID                                 MOUNTPOINT
sda                                                       
├─sda1      vfat              CBB6-24F2                            /boot
├─sda2      ext4   Arch Linux 0a3407de-014b-458b-b5c1-848e92a327a3 /
├─sda3      ext4   Data       b411dc99-f0a0-4c87-9e05-184977be8539 /home
└─sda4      swap              f9fe0b69-a280-415d-a03a-a32752370dee [SWAP]
mmcblk0
└─mmcblk0p1 vfat              F4CA-5D75

For those using GPT, use the blkid command instead. The latter is more convenient for scripts, but more difficult to read.

# blkid
/dev/sda1: UUID="CBB6-24F2" TYPE="vfat" PARTLABEL="EFI system partition" PARTUUID="d0d0d110-0a71-4ed6-936a-304969ea36af" 
/dev/sda2: LABEL="Arch Linux" UUID="0a3407de-014b-458b-b5c1-848e92a327a3" TYPE="ext4" PARTLABEL="GNU/Linux" PARTUUID="98a81274-10f7-40db-872a-03df048df366" 
/dev/sda3: LABEL="Data" UUID="b411dc99-f0a0-4c87-9e05-184977be8539" TYPE="ext4" PARTLABEL="Home" PARTUUID="7280201c-fc5d-40f2-a9b2-466611d3d49e" 
/dev/sda4: UUID="f9fe0b69-a280-415d-a03a-a32752370dee" TYPE="swap" PARTLABEL="Swap" PARTUUID="039b6c1c-7553-4455-9537-1befbc9fbc5b"
/dev/mmcblk0: PTUUID="0003e1e5" PTTYPE="dos"
/dev/mmcblk0p1: UUID="F4CA-5D75" TYPE="vfat" PARTUUID="0003e1e5-01"

by-label

Almost every file system type can have a label. All your volumes that have one are listed in the /dev/disk/by-label directory.

$ ls -l /dev/disk/by-label
total 0
lrwxrwxrwx 1 root root 10 May 27 23:31 Data -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 Arch\x20Linux -> ../../sda2

Most file systems support setting the label upon file system creation, see the man page of the relevant mkfs.* utility. For some file systems it is also possible to change the labels. Following are some methods for changing labels on common file systems:

swap 
swaplabel -L "new label" /dev/XXX using util-linux
ext2/3/4 
e2label /dev/XXX "new label" using e2fsprogs
btrfs 
btrfs filesystem label /dev/XXX "new label" using btrfs-progs
reiserfs 
reiserfstune -l "new label" /dev/XXX using reiserfsprogs
jfs 
jfs_tune -L "new label" /dev/XXX using jfsutils
xfs 
xfs_admin -L "new label" /dev/XXX using xfsprogs
fat/vfat 
fatlabel /dev/XXX "new label" using dosfstools
mlabel -i /dev/XXX ::"new label" using mtools
exfat 
exfatlabel /dev/XXX "new label" using exfat-utils
ntfs 
ntfslabel /dev/XXX "new label" using ntfs-3g
udf 
udflabel /dev/XXX "new label" using udftools
crypto_LUKS (LUKS2 only) 
cryptsetup config --label="new label" /dev/XXX using cryptsetup

The label of a device can be obtained with lsblk:

$ lsblk -dno LABEL /dev/sda2
Arch Linux

Or with blkid:

# blkid -s LABEL -o value /dev/sda2
Arch Linux
Note:
  • The file system must not be mounted to change its label. For the root file system this can be accomplished by booting from another volume.
  • Labels have to be unambiguous to prevent any possible conflicts.
  • Labels can be up to 16 characters long.
  • Since the label is a property of the filesystem, it is not suitable for addressing a single RAID device persistently.
  • When using encrypted containers with dm-crypt, the labels of filesystems inside of containers are not available while the container is locked/encrypted.

by-uuid

UUID is a mechanism to give each filesystem a unique identifier. These identifiers are generated by filesystem utilities (e.g. mkfs.*) when the device gets formatted and are designed so that collisions are unlikely. All GNU/Linux filesystems (including swap and LUKS headers of raw encrypted devices) support UUID. FAT, exFAT and NTFS filesystems do not support UUID, but are still listed in /dev/disk/by-uuid/ with a shorter UID (unique identifier):

$ ls -l /dev/disk/by-uuid/
total 0
lrwxrwxrwx 1 root root 10 May 27 23:31 0a3407de-014b-458b-b5c1-848e92a327a3 -> ../../sda2
lrwxrwxrwx 1 root root 10 May 27 23:31 b411dc99-f0a0-4c87-9e05-184977be8539 -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 CBB6-24F2 -> ../../sda1
lrwxrwxrwx 1 root root 10 May 27 23:31 f9fe0b69-a280-415d-a03a-a32752370dee -> ../../sda4
lrwxrwxrwx 1 root root 10 May 27 23:31 F4CA-5D75 -> ../../mmcblk0p1

The UUID of a device can be obtained with lsblk:

$ lsblk -dno UUID /dev/sda1
CBB6-24F2

Or with blkid:

# blkid -s UUID -o value /dev/sda1
CBB6-24F2

The advantage of using the UUID method is that it is much less likely that name collisions occur than with labels. Further, it is generated automatically on creation of the filesystem. It will, for example, stay unique even if the device is plugged into another system (which may perhaps have a device with the same label).

The disadvantage is that UUIDs make long code lines hard to read and break formatting in many configuration files (e.g. fstab or crypttab). Also every time a volume is reformatted a new UUID is generated and configuration files have to get manually adjusted.

Tip: In case your swap does not have an UUID assigned, you will need to reset it using the mkswap utility.

by-id and by-path

by-id creates a unique name depending on the hardware serial number, by-path depending on the shortest physical path (according to sysfs). Both contain strings to indicate which subsystem they belong to (i.e. pci- for by-path, and ata- for by-id), so they are linked to the hardware controlling the device. This implies different levels of persistence: the by-path will already change when the device is plugged into a different port of the controller, the by-id will change when the device is plugged into a port of a hardware controller subject to another subsystem. [1] Thus, both are not suitable to achieve persistent naming tolerant to hardware changes.

However, both provide important information to find a particular device in a large hardware infrastructure. For example, if you do not manually assign persistent labels (by-label or by-partlabel) and keep a directory with hardware port usage, by-id and by-path can be used to find a particular device.[2] [3]

by-id also creates World Wide Name links of storage devices that support it. Unlike other by-id links, WWNs are fully persistent and will not change depending on the used subsystem.

$ ls -l /dev/disk/by-id/
total 0
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470 -> ../../sda
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part1 -> ../../sda1
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part2 -> ../../sda2
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part3 -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part4 -> ../../sda4
lrwxrwxrwx 1 root root 10 May 27 23:31 mmc-SD32G_0x0040006d -> ../../mmcblk0
lrwxrwxrwx 1 root root 10 May 27 23:31 mmc-SD32G_0x0040006d-part1 -> ../../mmcblk0p1
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f -> ../../sda
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f-part1 -> ../../sda1
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f-part2 -> ../../sda2
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f-part3 -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 wwn-0x60015ee0000b237f-part4 -> ../../sda4
$ ls -l /dev/disk/by-path/
total 0
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1 -> ../../sda
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1-part1 -> ../../sda1
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1-part2 -> ../../sda2
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1-part3 -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:00:1f.2-ata-1-part4 -> ../../sda4
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:07:00.0-platform-rtsx_pci_sdmmc.0 -> ../../mmcblk0
lrwxrwxrwx 1 root root 10 May 27 23:31 pci-0000:07:00.0-platform-rtsx_pci_sdmmc.0-part1 -> ../../mmcblk0p1

by-partlabel

Note: This method only concerns disks with GUID Partition Table (GPT).

GPT partition labels can be defined in the header of the partition entry on GPT disks.

This method is very similar to the filesystem labels, except the partition labels do not get affected if the file system on the partition is changed.

All partitions that have partition labels are listed in the /dev/disk/by-partlabel directory.

ls -l /dev/disk/by-partlabel/
total 0
lrwxrwxrwx 1 root root 10 May 27 23:31 EFI\x20system\x20partition -> ../../sda1
lrwxrwxrwx 1 root root 10 May 27 23:31 GNU\x2fLinux -> ../../sda2
lrwxrwxrwx 1 root root 10 May 27 23:31 Home -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 Swap -> ../../sda4

The partition label of a device can be obtained with lsblk:

$ lsblk -dno PARTLABEL /dev/sda1
EFI system partition

Or with blkid:

# blkid -s PARTLABEL -o value /dev/sda1
EFI system partition
Note:
  • GPT partition labels also have to be different to avoid conflicts. To change your partition label, you can use gdisk or the ncurses-based version cgdisk. Both are available from the gptfdisk package. See Partitioning#Partitioning tools.
  • According to the specification, GPT partition labels can be up to 72 characters long.

by-partuuid

Like GPT partition labels, GPT partition UUIDs are defined in the partition entry on GPT disks.

MBR does not support partition UUIDs, but Linux[4] and software using libblkid[5] (e.g. udev[6]) are capable of generating pseudo PARTUUIDs for MBR partitions. The format is SSSSSSSS-PP, where SSSSSSSS is a zero-filled 32-bit MBR disk signature, and PP is a zero-filled partition number in hexadecimal form. Unlike a regular PARTUUID of a GPT partition, MBR's pseudo PARTUUID can change if the partition number changes.

The dynamic directory is similar to other methods and, like filesystem UUIDs, using UUIDs is preferred over labels.

ls -l /dev/disk/by-partuuid/
total 0
lrwxrwxrwx 1 root root 10 May 27 23:31 0003e1e5-01 -> ../../mmcblk0p1
lrwxrwxrwx 1 root root 10 May 27 23:31 039b6c1c-7553-4455-9537-1befbc9fbc5b -> ../../sda4
lrwxrwxrwx 1 root root 10 May 27 23:31 7280201c-fc5d-40f2-a9b2-466611d3d49e -> ../../sda3
lrwxrwxrwx 1 root root 10 May 27 23:31 98a81274-10f7-40db-872a-03df048df366 -> ../../sda2
lrwxrwxrwx 1 root root 10 May 27 23:31 d0d0d110-0a71-4ed6-936a-304969ea36af -> ../../sda1

The partition UUID of a device can be obtained with lsblk:

$ lsblk -dno PARTUUID /dev/sda1
d0d0d110-0a71-4ed6-936a-304969ea36af

Or with blkid:

# blkid -s PARTUUID -o value /dev/sda1
d0d0d110-0a71-4ed6-936a-304969ea36af

Static device names with udev

See udev#Setting static device names.

Using persistent naming

There are various applications that can be configured using persistent naming. Following are some examples of how to configure them.

fstab

See the main article: fstab#Identifying filesystems.

Kernel parameters

To use persistent names in kernel parameters, the following prerequisites must be met. On a standard installation following the installation guide both prerequisites are met:

  • You are using a mkinitcpio initial RAM disk image
  • You have either udev or systemd hook enabled in /etc/mkinitcpio.conf

The location of the root filesystem is given by the parameter root on the kernel command line. The kernel command line is configured from the boot loader, see Kernel parameters#Configuration. To change to persistent device naming, only change the parameters which specify block devices, e.g. root and resume, while leaving other parameters as is. Various naming schemes are supported:

Persistent device naming using label and the LABEL= format, in this example Arch Linux is the LABEL of the root file system.

root="LABEL=Arch Linux"

Persistent device naming using UUID and the UUID= format, in this example 0a3407de-014b-458b-b5c1-848e92a327a3 is the UUID of the root file system.

root=UUID=0a3407de-014b-458b-b5c1-848e92a327a3

Persistent device naming using disk id and the /dev path format, in this example wwn-0x60015ee0000b237f-part2 is the id of the root partition.

root=/dev/disk/by-id/wwn-0x60015ee0000b237f-part2

Persistent device naming using GPT partition UUID and the PARTUUID= format, in this example 98a81274-10f7-40db-872a-03df048df366 is the PARTUUID of the root partition.

root=PARTUUID=98a81274-10f7-40db-872a-03df048df366

Persistent device naming using GPT partition label and the PARTLABEL= format, in this example GNU/Linux is the PARTLABEL of the root partition.

root="PARTLABEL=GNU/Linux"