Labeling partitions done right on modern computers.


Aspiring Daemon

Reaction score: 449
Messages: 740

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
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.

    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 :D

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!


Aspiring Daemon

Reaction score: 471
Messages: 946

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!


Aspiring Daemon

Reaction score: 346
Messages: 832

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...


Son of Beastie

Reaction score: 1,875
Messages: 4,908

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


New Member

Reaction score: 1
Messages: 1

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 ;-).


Aspiring Daemon

Reaction score: 298
Messages: 701

Unfortunately (?), the term LABEL has many incarnations when it comes to disks:
  1. Partition labels of the partitioning scheme in use (e.g. GPT or MBR)
  2. geom(4) device labels
  3. Filesystem labels
  4. (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!