# Labeling partitions done right on modern computers.



## k.jacker (Jan 21, 2019)

If you have ever added or removed a disk from your computer running FreeBSD, you have probably experienced that device names had moved around after a reboot and FreeBSD wouldn't boot anymore or a ZFS pool failed.
Labels can work around that.

Before we start, it’s important to know that there are two ways to label partitions: through GEOM and through GPT. On partitioning schemes other that GPT, e.g. MBR, the only way to apply a label to a partition is through GEOM, using either glabel(8) or tunefs(8).
With GPT partitions, we are using gpart(8), that's what this tutorial is about.
That said, if you have a more or less modern computer, you should forget about GEOM labels (almost) completely and use GPT labels instead. GEOM labels can still be useful to label whole disks, but that’s about it.

GPT first appeared on FreeBSD in 7.0-RELEASE in 2008 as an early work in progress. As with it’s bigger brother UEFI, over the years, the two became a usable state at some point. Every computer from recent years has support for GPT. If you are unsure about your computer's age - if it supports UEFI, you should be ably to use GPT partitions.

To avoid confusing  the unexperienced user, I’d like to mention, that MBR is both a partitioning scheme and a method to boot. While with a MBR partitioning scheme, you are restricted to booting via MBR, when using GPT, you can boot in both, UEFI mode or via MBR. As UEFI can still be buggy on hardware from only 4-5 years ago, a common setup is using GPT partitions in conjunction with a legacy MBR (called a protective MBR in that case) and a legacy _freebsd-boot_ partition, to boot.
The first two lines from `gpart show`, would display similar to the following (just for completeness).

```
% gpart show
=>     40  3907029088  ada0  GPT  (1.8T)
       40              1024    1  freebsd-boot  (512K)
```
That’s a regular GPT partitioning scheme, where GPT labels can be used. It's just setup to boot a legacy MBR.
If you want to use labels and your computer is capable of using GPT partitioning, but your disk(s) use MBR partitioning, I’d still consider trashing it all together and start from scratch with GPT. Keep in mind, that there's no way to convert from MBR to GPT. It's still worth the work IMO.


What’s so great about those GPT labels?
Well, they can be applied and modified at any time, also on mounted partitions. Additionally, with _gpart_ you only need a single tool for everything involved in partitioning and labeling your drives. Most important  though, they work great. You will never ever have any headaches again, using labels.

Now let’s start:
I’m going to start with a simple example of labeling a swap partition. This is for the reason, that some of you have already played with GPT labels and wondered why the corresponding device nodes refuse to appear. This is also a save start to learn and can be used on a running system, without the risk of leaving the system unbootable after reboot.

Say this is a basic FreeBSD install with a disk layout like the following:

```
% gpart show
=>       40  1953525088  ada0  GPT  (932G)
         40        1024     1  freebsd-boot  (512K)
       1064  1946156032     2  freebsd-ufs  (928G)
1946157096     6553600     3  freebsd-swap  (3.1G)
1952710696      814432        - free -  (398M)
```

Let’s check if there are any labels already, by adding the `-l` option:

```
% gpart show -l
=>       40  1953525088  ada0  GPT  (932G)
         40        1024     1  (null)  (512K)
       1064  1946156032     2  (null)  (928G)
1946157096     6553600     3  (null)  (3.1G)
1952710696      814432        - free -  (398M)
```
_(null) _indicates, no labels so far.
Let’s add a label to the swap partition and then put that label into /etc/fstab and reboot the computer. This is a 1TB Toshiba hard drive, so I use that as a name. As the partition already exists, we use `gpart modify` for the job:
`# gpart modify -l swap-1tb-toshiba -i3 ada0` (name it as you like)

```
% gpart show -l
=>       40  1953525088  ada0  GPT  (932G)
         40        1024     1  (null)  (512K)
       1064  1946156032     2  (null)  (928G)
1946157096     6553600     3  swap-1tb-toshiba  (3.1G)
1952710696      814432        - free -  (398M)
```
In the fourth line, our label shows up, applied while swap is in use. Note that the partition is still in use by it's regular device name /dev/ada0p3, you can verify that with `% swapinfo`.

Now that we are using GPT labels, one would expect this label to appear in /dev/gpt

```
% ls /dev/gpt
ls: /dev/gpt: No such file or directory
```
Weird enough, the directory does not exist, even if it should (if you did create GPT labels before, the directory may exist, but the _swap-1tb-toshiba_ label will not show).
It's hidden as long as the original device name is in use, as Bobi B. and Lanakus mentioned that here just yesterday.
That's the reason why I use the swap partition for this example, as we are going to "unuse" it now, which wouldn't be doable with your root filesystem (I assume now, that your swap partition does not hold any swapped-out data).

Let's take the swap partition offline (I don't say "remove it" on purpose, even if it would be the right term).
`# swapoff /dev/ada0p3`
Execute `% swapinfo` again, and you'll see, that /dev/ada0p3 is no longer listed as swap. It's no longer in use. What does that do our label in /dev/gpt?

```
% ls /dev/gpt
swap-1tb-toshiba
```
Well, it magically appeared 

Now that we have /dev/gpt/swap-1tb-toshiba we are going to edit /etc/fstab accordingly and then reboot.
Fire up your favorite editor and look for a line that looks similar to the following:

```
/dev/ada0p3    none        swap    sw    0    0
```
I'd suggest to copy/paste that line and then comment out one of them, but you can edit it in place if you prefer that.
Substitute /dev/ada0p3 with /dev/gpt/swap-1tb-toshiba, or whatever name you chose.
The line should now look like this:

```
/dev/gpt/swap-1tb-toshiba    none        swap    sw    0    0
```

Reboot the system. When it comes up again, check `% swapinfo` to see that, instead of the original device name, our GPT label is listed as swap.

That's the whole magic behind it.
You can of course create a label for your root filesystem as well, like
`# gpart modify -l rootfs-1tb-toshiba -i2 ada0`
Even if your label won't show up in /dev/gpt, since your root filesystem is in use, you can still put it's label into /etc/fstab and reboot with no problems.
Your GPT labels will at any time show up in the output of `gpart show -l`. Tthat's the command you should refer to, it's completely independent from filesystems being mounted or not.

With your root filesystem labeled as well, your /etc/fstab could look like this:

```
# Device    Mountpoint    FStype    Options    Dump    Pass#
#/dev/ada0p2                /           ufs        rw    1    1
/dev/gpt/rootfs-1tb-toshiba    /       ufs        rw    1    1
#/dev/ada0p3                none        swap    sw    0    0
/dev/gpt/swap-1tb-toshiba    none       swap    sw    0    0
```
Make sure you are not misspelling the label in /etc/fstab or the system will not boot. Should that happen, at the loader prompt typing (in the case of my example drive) *ufs:/dev/ada0p2*<enter> will boot the system.
Edit: I usually label all partitions on a disk, so no empty labels will show in the output from `gpart show -l`. You can label your _freebsd-boot _or _efi _partitions the same way.



Another important use case: ZFS
Creating a pool, using regular device names is a bad idea. I would honestly compare that to pointing a knife to your chest, closing your eyes and then start running.
On a small storage pool you may be able to sort out problems with changing device names, but with huge pools or root-on-zfs, the flexibility of labels can definitely save you some headache.
Labels really shine when you name them after the physical position of the disks inside a backplane or raid encosure, like _left_, _2nd-from-left_, _3rd-from-left._
For small pools, naming the disks after a random topic can also be handy. I have a small pool of 4 loose external USB disks, each with a sticker on it, that corresponds to it's GPT label.
_flour, yeast, water _and_ salt, _those drives can be connected randomly to any USB port or hub on any computer and the pool will always import nicely.

To create an example pool, using two mirrored SATA drives, one would do something like to the following:

```
# gpart create -s gpt ada0
# gpart create -s gpt ada1
# gpart add -t freebsd-zfs -l backup-left ada0
# gpart add -t freebsd-zfs -l backup-right ada1
zpool create <your options> backup mirror gpt/backup-left gpt/backup-right
```

The output from `zpool status backup` would look like this:

```
pool: backup
     id: 2004489531562853512
  state: ONLINE
action: The pool can be imported using its name or numeric identifier.
config:

    backup                    ONLINE
      mirror-0                ONLINE
        gpt/backup-left       ONLINE
        gpt/backup-right      ONLINE
```
Now you can add a drive, move the drives around, pull them out and put them back as you like. Ahhh, I love GPT labels 


Sidenote: Have you...
  - used journaling through GEOM and experienced devices disappear?
- find the output from `gpart show` cluttered, when unmounted partitions appear twice?

Then I can recommend disableing all other disk identifiers all together by putting the following three lines into /boot/loader.conf. They are not necessary to use GPT labels, though!. Just a nice addon!

```
kern.geom.label.disk_ident.enable=0
kern.geom.label.gptid.enable=0
kern.geom.label.ufsid.enable=0
```


----------



## Sevendogsbsd (Jan 27, 2019)

I was labeling all along but for whatever reason completely missed the "It's hidden as long as the original device name is in use" explanation I am sure more than one person told me...once I added the appropriate entries to /etc/fstab, voila` all is well. Thanks k.jacker!


----------



## PMc (May 17, 2019)

This is very helpful. One learns that 

GEOM labels are something different than gpt labels
gpt labels are something different than gptid
disk_ident is again something different than gptid
And I was wondering why I didn't get rid of the gptid by switching off disk_ident...


----------



## Phishfry (Nov 30, 2019)

Excellent FAQ. I finally have my 24 bay chassis disk labels working right.


----------



## arcalus (Jun 6, 2020)

If anyone is wondering why they can't boot into their FreeBSD fresh install, this post is probably the solution. Whether using a physical USB for the install or a virtual CD-ROM through the iDRAC, drives were always being enumerated differently. 

Thank you for this post! It only took me a half dozen installs before I found it ;-).


----------



## Mjölnir (Jun 7, 2020)

Unfortunately (?), the term _LABEL_ has many incarnations when it comes to disks:

Partition labels of the partitioning scheme in use (e.g. GPT or MBR)
geom(4) device labels
Filesystem labels
(old-style BSD sub-partitions ...)
Did I miss any? This excellent HOWTO clarifies some of the confusion that  arises from this.  Thank you very much!


----------



## Deleted member 60479 (Nov 27, 2020)

May I label an encrypted UFS disk post creating the *.eli device?


----------



## Argentum (Nov 27, 2020)

k.jacker said:


> Now that we have /dev/gpt/swap-1tb-toshiba we are going to edit /etc/fstab accordingly and then reboot.
> Fire up your favorite editor and look for a line that looks similar to the following:
> 
> ```
> ...


That worked on  my laptop:
`swapinfo`


```
Device          1K-blocks     Used    Avail Capacity
/dev/gpt/lenovo-swap   8388608        0  8388608     0%
```

The next question arises - *what happens when I add the identical label to several partitions on different drives*?

On another computer I have multiple drives for mirror, cache and logs. I want the system to be bootable even if some drives from the configuration are physically removed (cache, logs, one mirror member). I have solved this problem by adding a redundant swap partition with identical number to each drive, even if not in use. The motherboard changes the drives numbering according to the number of drives connected, not as the physical connection. So, I have a swap partition #2 on each drive. When I remove one, the system still boots without the need to edit `/etc/fstab`. 

Now my question is, *how can I solve this problem, using GPT labels*? If I set the same label for swap partition on each drive, *what happens*?


----------



## driesm (Nov 27, 2020)

Bad things (untested theritory) it probably uses the GPT label of the first detected disk. Just don't use the same label, give them a number, like swap0, swap1 , etc


----------



## T-Daemon (Nov 28, 2020)

Argentum said:


> - *what happens when I add the identical label to several partitions on different drives*?





Argentum said:


> If I set the same label for swap partition on each drive, *what happens*?


The first disk/partition in the disk numbering with the same label is picked up, all others ignored.

Here a test VM with 3 swap disks, 100 - 300 MB (they have different sizes to differentiate them from each other), all three disks/partitions gpart labeled "swap", "Device" `/dev/gpt/swap` set in /etc/fstab.

This setup has 3 swap disks/partitions, first in disk numbering, the 100 MB disk, is picked up, see swapinfo "Avail" column:



Here the 100 MB swap disk/partition was removed, and the 300 MB swap disk was put in a SATA port in front of the 200 MB disk:


----------



## avner (Dec 21, 2020)

I want to express my gratitude for this how-to. During my install I did use GPT for partitioning and added labels to all of my partitions but like many could not figure out why they were not listed under /dev. It sounds like using the format /dev/gpt/<label-name> in  /etc/fstab is the way to go but for completeness sake can I get some confirmation that /dev/gpt/<rawuuid> will also work to identify the partition in /etc/fstab? Thanks, I will test when I get a chance but don't want to leave my remote server in unbootable condition right now.


----------



## T-Daemon (Dec 21, 2020)

avner said:


> It sounds like using the format /dev/gpt/<label-name> in /etc/fstab is the way to go but for completeness sake can I get some confirmation that /dev/gpt/<rawuuid> will also work to identify the partition in /etc/fstab?


I can confirm that /dev/gptid/<rawuuid>'s will also work to identify the partition in /etc/fstab:


----------



## free-and-bsd (Mar 18, 2021)

Thanks! Good stuff and helpful. I was wandering why it is on my system that my GPT disk is identified by the gpart  as diskid/DISKMODEL&OTHERSTUFF instead of adaX. Device /dev/ada0 exists, though, but no /dev/adapN...
This HOWTO keeps all the tips in one place.


----------



## sidetone (Mar 24, 2021)

FreeBSD Labeled Filesystems
		


Is a variation for partition labeling, that can also be used for non-GPT partitions.


----------



## scott_sch (May 8, 2021)

Great explaination, lights the way to some worthwhile improvements, but I'm wondering how secondary partitions fit into this? Im building a multiboot pc and need to label ada0s2a.


----------



## free-and-bsd (May 8, 2021)

free-and-bsd said:


> Thanks! Good stuff and helpful. I was wandering why it is on my system that my GPT disk is identified by the gpart  as diskid/DISKMODEL&OTHERSTUFF instead of adaX. Device /dev/ada0 exists, though, but no /dev/adapN...
> This HOWTO keeps all the tips in one place.


One more thing to mention though. If those names like diskid/DISK-PHLA9156009N1blabla are used in a ZFS pool, those sysctls mentioned above won't change that on the next boot. You need to explicitly _export_ and _import_ again the pool for the disk names to change accordingly. I faced that problem after reading this HOWTO, and now all is fine.


----------



## mer (May 8, 2021)

`NAME                  STATE     READ WRITE CKSUM
    storage               ONLINE       0     0     0
      mirror-0            ONLINE       0     0     0
        ada2p1            ONLINE       0     0     0
        gpt/WMC1F0E6J1ZE  ONLINE       0     0     0`

So lets say you currently have a mirror like the above, then gpart show -l ada2 gives us:
`gpart show -l ada2
=>        34  5860533101  ada2  GPT  (2.7T)
          34        2014        - free -  (1.0M)
        2048  5452595200     1  WMC1F0E17A2R  (2.5T)
  5452597248   407935887        - free -  (195G)`

Could one do

zpool detach storage ada2p1 to remove it from the mirror, this should also make /dev/gpt/WMCF0E17A2R reappear
followed by 
zpool attach storage gpt/WMCF0E17A2R
give us storage back as a mirror with both members using the gpt labels?


----------



## sidetone (Sep 15, 2021)

sysutils/lsblk allows listing of labels along with their partitions. It doesn't have a manpage. Its only command is lsblk, which the disk can be signified as an argument.


----------



## Erichans (Sep 15, 2021)

sidetone said:


> sysutils/lsblk allows listing of labels along with their partitions. It doesn't have a manpage. Its only command is lsblk, which the disk can be signified as an argument.



sysutils/lsblk is inspired by or likened to linux `lsblk`; as in lsblk(8). It was developed by vermaden and is described in List Block Devices on FreeBSD lsblk(8) Style

`lsblk --help` gives info and options for the command line.


----------

