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
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:
Let’s check if there are any labels already, by adding the
(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
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
Now that we are using GPT labels, one would expect this label to appear in /dev/gpt
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).
Execute
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:
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:
Reboot the system. When it comes up again, check
That's the whole magic behind it.
You can of course create a label for your root filesystem as well, like
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
With your root filesystem labeled as well, your /etc/fstab could look like this:
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
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:
The output from
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
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!
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).
Code:
% gpart show
=> 40 3907029088 ada0 GPT (1.8T)
40 1024 1 freebsd-boot (512K)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:
Code:
% 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:
Code:
% 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)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)
Code:
% 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) % swapinfo.Now that we are using GPT labels, one would expect this label to appear in /dev/gpt
Code:
% ls /dev/gpt
ls: /dev/gpt: No such file or directoryIt'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/ada0p3Execute
% 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?
Code:
% ls /dev/gpt
swap-1tb-toshibaNow 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:
Code:
/dev/ada0p3 none swap sw 0 0Substitute /dev/ada0p3 with /dev/gpt/swap-1tb-toshiba, or whatever name you chose.
The line should now look like this:
Code:
/dev/gpt/swap-1tb-toshiba none swap sw 0 0Reboot 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 ada0Even 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:
Code:
# 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 0Edit: 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:
Code:
# 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-rightThe output from
zpool status backup would look like this:
Code:
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 ONLINESidenote: 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!
Code:
kern.geom.label.disk_ident.enable=0
kern.geom.label.gptid.enable=0
kern.geom.label.ufsid.enable=0
