Official Arch BSD ZFS Install Guide

This guide aims to explain you how to install PacBSD on a ZFS storage pool.

Why use ZFS instead of UFS?

There are two answers to this question.

1) Why not?  :D

2) Because ZFS is the world's most advanced file system and PacBSD has a built-in support. ZFS is a copy-on-write, fault tolerant file system that makes easier your storage management on single disk-based configurations and on multiple devices-based configurations (mirror and/or RAID).

WARNING: Before installing PacBSD on a ZFS storage pool, please read the Official Arch BSD Install Guide to see how to configure a fresh installation of PacBSD and how to set your installation environment (e.g., keymap, vidcontrol etc.).

To avoid any redundancies, this guide will NOT explain things that are explained in the Official Guide.

Loading modules

Before creating a ZFS pool, you should load the zfs.ko and opensolaris.ko kernel modules. opensolaris.ko is a dependency of zfs.ko, so you can just load zfs.ko to load it too.

kldload zfs

NOTE: The ISO (2013-07-12) already loads this at boot, so it might not be required

Disk Partitioning

GPT-based systems

gpart create -s GPT ada0

gpart add -s 128k -t freebsd-boot ada0

gpart add -t freebsd-zfs ada0

If you have an IDE disk your target will be ad0, instead of ada0 (as described in the Official Guide).

MBR-based systems

gpart create -s MBR ada0

gpart add -t freebsd ada0

gpart create -s BSD ada0s1

gpart set -a active -i1 ada0

gpart add -t freebsd-zfs ada0s1

Creating the pool

zpool create tank /dev/ada0p2

So, the new pool tank is now created. You can call your pool with another label, if you want it.

Replace /dev/ada0p2 with your target partition.

Setting up Bootloader

GPT-based systems

gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i1 ada0

MBR-based systems

Please unmount your pool before installing the bootloader.

zpool export tank

gpart bootcode -b /boot/boot0 ada0

dd if=/boot/zfsboot of=/dev/ada0s1 count=1

dd if=/boot/zfsboot of=/dev/ada0s1a skip=1 seek=1024

Reimporting the pool

To do this we need to re-mount /boot/zfs on a ramdisk. (should be fixed with the next iso-release) This creates a 128MB ramdisk, might be slightly over-size...

mdmfs -s 128m md /boot/zfs

Now, reimport your pool to mount it into /mnt directory. This method avoids the final unmounting of the all datasets to set their mountpoint.

zpool export tank

zpool import -o altroot=/mnt -o cachefile=/boot/zfs/zpool.cache -f tank

Setting the checksum algorithm (optional)

zfs set checksum=fletcher4 tank

Creating datasets

zfs create -o canmount=off -o mountpoint=legacy tank/ROOT

zfs create -o canmount=on -o compression=on -o mountpoint=/ tank/ROOT/pacbsd-0

zfs create -o compression=on -o mountpoint=/home tank/HOME

zfs create -o compression=off -o mountpoint=/root tank/HOME/root

Since the use of root account is not recommended, i don't use compression on its dataset.

The canmount=off property is necessary to avoid automount of tank/ROOT dataset.

Since it is a special dataset, which i create to separate the nested root dataset and its clones from the rest, i don't need to automount it.

The mountpoint=legacy property is necessary for zfs to delegate the management of that dataset to the administrator.

The ZFS swap volume

PacBSD is able to use a ZFS pre-allocated volume as your swap area.

The only disadvantage is that you will no more be able to save core dumps in your swap volume, because PacBSD can only save them in a separate swap partition.

So, if you want to save core dumps, please consider to create a swap partition with gpart, as described in the Official Installation Guide, and skip this step.

A swap volume should have the checksum property turned off and it should be a pre-allocated volume.

zfs create -V2G -o checksum=off -o org.freebsd:swap=on tank/swap

The -V2G parameter is necessary to make a pre-allocated volume. ZFS cannot manage swap area on a normal dataset.

Remember that in every pre-allocated volumes you cannot use the quota property for limiting the volume's capacity.

org.freebsd:swap is a special property of FreeBSD (and PacBSD) for manage the swap area with ZFS.

Installing PacBSD

Please, see the related section on the Official Arch BSD Install Guide.

Configuring the system

With ZFS you can avoid the use of /etc/fstab for mounting the root dataset. So, the only purpose of it is to manage proc and linproc pseudo-volumes and for swap partition, if you created it.

For the swap partition entry, see the Official Guide.

So, make a chroot in your new system and create /etc/fstab.

chroot /mnt

cat << EOF > /etc/fstab

# Device Mountpoint FStype Options Dump Pass #

proc /proc procfs rw 0 0

EOF

Now, attach the following lines to /boot/loader.conf

cat << EOF >> /boot/loader.conf

zfs_load="YES"

vfs.root.mountfrom="zfs:tank/ROOT/archbsd-0"

EOF

The first line is necessary for the bootloader to load the zfs kernel module. The second is necessary for the kernel to find the root of your system.

For the rest, please see the Official Install Guide.

Setting the last things

Now, you should to copy the zpool.cache file, that was created with the pool.

So, exit from chroot and copy that file.

cp /boot/zfs/zpool.cache /mnt/boot/zfs/zpool.cache

Before rebooting, there is a last thing that you should do: setting the bootfs property. This property allows zfs to recognize tank/ROOT/archbsd-0 as a bootable dataset.

zpool set bootfs=tank/ROOT/archbsd-0 tank

You also have to enable zfs-service, otherwise it won't mount the datasets on boot.

For FreeBSD-init:

echo zfs_enable="YES" > /mnt/etc/rc.conf

For OpenRC-init (from within chroot):

rc-update add zfs default

OK! Now you have an PacBSD system installed on a ZFS storage pool.

So, reboot and enjoy it!  :-)

See Also

• Official Arch BSD Install Guide
• FreeBSD Handbook ZFS Chapter
• http://ostanin.org/blog/2011/12/19/root-on-zfs-with-freebsd-9/ (Useful additional external source to read through)