These are instructions for recreating the Native ZFS Root Filesystem Demo virtual machine (the "OVA example") that is available at http://www.vanadac.com/~dajhorn/projects/zfs/. The procedure for a Debian installation is similar but not identical.
Do not use this procedure to dual-boot Linux on an existing ZFS filesystem if the boot loader was installed by Solaris because
beadm does not recognize grub2 installations.
Computers that have less than 2GB of memory run ZFS slowly. 4GB of memory is recommended for normal performance in basic workloads. 16GB of memory is recommended if you wish to use advanced features like deduplication or compression.
1.1 Start the Ubuntu LiveCD and open a terminal at the desktop.
1.2 Input these commands at the terminal prompt:
$ sudo -i # apt-add-repository ppa:dajhorn/zfs # apt-get update # apt-get install debootstrap ubuntu-zfs
1.3 Check that the ZFS filesystem is installed and available:
# modprobe zfs # dmesg | grep ZFS: ZFS: Loaded module v0.6.0.5, ZFS pool version 28, ZFS filesystem version 5
2.1 Run your favorite disk partitioner, like
2.2 Create a small MBR primary partition of at least 8 megabytes. This is
/dev/sda1 in the OVA example.
2.3 On this first small partition, set
type=BE and enable the
2.4 Create a large partition of at least 4 gigabytes. This is
/dev/sda2 in the OVA example.
2.5 On this second large partition, set
type=BF and disable the
The partition table in the OVA example looks like this:
# fdisk -l /dev/sda Disk /dev/sda: 10.7 GB, 10737418240 bytes 255 heads, 63 sectors/track, 1305 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disk identifier: 0x00000000 Device Boot Start End Blocks Id System /dev/sda1 * 1 1 8001 be Solaris boot /dev/sda2 2 1305 10474380 bf Solaris
/dev/sda2 appropriately below.
Note: Recent GRUB releases assume that the
/boot/grub/grubenv file is writable by the stage2 module. Until GRUB gets a ZFS write enhancement, the GRUB modules must be installed to a separate filesystem.
/boot/grub is in the ZFS filesystem, then GRUB will fail to boot with this message:
error: sparse file not allowed. If you absolutely want only one filesystem, then remove the call to
recordfail() in each
grub.cfg menu stanza, and edit the
/etc/grub.d/10_linux file to make the change permanent.
3.1 Format the small boot partition created by Step 2.2 as a filesystem that has stage1 GRUB support. The OVA example was created like this:
# mke2fs -m 0 -L /boot/grub -j /dev/sda1
3.2 Create the root pool on the larger partition:
# zpool create rpool /dev/sda2
The pool name is arbitrary. On systems that can automatically install to ZFS, the root pool is named "rpool" by default. Note that system recovery is easier if you choose a unique name instead of "rpool". Anything except "rpool" or "tank" would be a good choice.
rpool appropriately below if you choose a different name.
3.3 Create a "ROOT" filesystem in the root pool:
# zfs create rpool/ROOT
3.4 Create a descendant filesystem for the Ubuntu system:
# zfs create rpool/ROOT/ubuntu-1
On Solaris systems, the root filesystem is cloned and the suffix is incremented for major system changes through
pkg image-update or
beadm. Similar functionality for APT is possible but currently unimplemented.
3.5 Dismount all ZFS filesystems.
# zfs umount -a
3.6 Set the
mountpoint property on the root filesystem:
# zfs set mountpoint=/ rpool/ROOT/ubuntu-1
3.7 Set the
bootfs property on the root pool.
# zpool set bootfs=rpool/ROOT/ubuntu-1 rpool
The boot loader uses these two properties to find and start the operating system. These property names are not arbitrary.
bootfs=MyPool/ROOT/system-1 on the kernel command line overrides the ZFS properties.
3.9 Export the pool:
# zpool export rpool
Don't skip this step. The system is put into an inconsistent state if this command fails or if you reboot at this point.
4.1 Import the pool:
# zpool import -R /mnt rpool
This implicitly mounts the new filesystem hierarchy on
4.2 Mount the small boot filesystem for GRUB that was created in step 3.1:
# mkdir -p /mnt/boot/grub # mount /dev/sda1 /mnt/boot/grub
4.4 Install the minimal system:
# debootstrap natty /mnt
debootstrap command leaves the new system in an unconfigured state. We will only do the minimum amount of configuration necessary in Step 5 to make the new system runnable. An alternative to using
debootstrap is to copy the entirety of a working Ubuntu system into the new ZFS root.
5.1 Copy these files from the LiveCD environment to the new system:
# cp /etc/hostname /mnt/etc/ # cp /etc/hosts /mnt/etc/
/mnt/etc/fstab file should be empty except for a comment. Add this line to the
/dev/sda1 /boot/grub auto defaults 0 1
The Ubuntu desktop installer may add
tmp lines to the
/etc/fstab file, but such entries are not strictly necessary for a modern system. Add them now if you want them.
5.3 Edit the
/mnt/etc/network/interfaces file so that it contains something like this:
# interfaces(5) file used by ifup(8) and ifdown(8) auto lo iface lo inet loopback auto eth0 iface eth0 inet dhcp
Customize this file if the new system is not a DHCP client on the LAN.
5.4 Rebind the virtual filesystems from the LiveCD environment to the new system and
chroot into it:
# mount --bind /dev /mnt/dev # mount --bind /proc /mnt/proc # mount --bind /sys /mnt/sys # chroot /mnt /bin/bash --login
5.5 Install PPA support in the chroot environment like this:
# apt-get update # apt-get install ubuntu-minimal python-software-properties
5.6 Install ZFS in the chroot environment for the new system:
# apt-add-repository ppa:dajhorn/zfs # apt-add-repository ppa:dajhorn/zfs-grub # apt-get update # apt-get install --no-install-recommends linux-image linux-image-generic linux-headers-generic # apt-get install ubuntu-zfs zfs-initramfs
This is the second time that you must wait for the SPL and ZFS modules to compile. Don't try to skip this step by copying anything from the host environment into the chroot environment. Don't combine the
apt-get install commands.
5.7 Set a root password on a the new system:
# passwd root
Install the ubuntu-desktop package now or later if you want a full Ubuntu installation.
The grub-common and grub-pc packages from the zfs-grub repository should already be installed, but automatic configuration may fail. Manually install GRUB again to be certain that the system is bootable.
6.1 Verify that the ZFS root filesystem is recognized:
# grub-probe / zfs
6.2 Verify that the ZFS modules are installed:
# ls /boot/grub/zfs* /boot/grub/zfs.mod /boot/grub/zfsinfo.mod
6.3 Refresh the initrd files:
# update-initramfs -c -k all update-initramfs: Generating /boot/initrd.img-2.6.35-22-generic
6.4 Update the boot configuration:
# update-grub Generating grub.cfg ... Found linux image: /boot/vmlinuz-2.6.35-22-generic Found initrd image: /boot/initrd.img-2.6.35-22-generic done
6.5 Install the boot loader to the MBR like this:
# grub-install /dev/sda Installation finished. No error reported.
Do not reboot the computer until you get exactly that result message.
7.1 Exit from th
chroot environment back to the LiveCD environment:
7.2 Run these commands in the LiveCD environment to dismount all filesystems:
# umount /mnt/boot/grub # umount /mnt/dev # umount /mnt/proc # umount /mnt/sys # zfs umount -a # zpool export rpool
zpool export command must succeed without being forced or the new system will fail to start.
7.3 We're done!
The zfs-initramfs package requires that
boot=zfs always be on the kernel command line. If the
boot=zfs parameter is not set, then the init process skips the ZFS routine entirely. This behavior is for safety; it makes the casual installation of the zfs-initramfs package unlikely to break a working system.
ZFS properties can be overridden on the the kernel command line with
bootfs arguments. For example, at the GRUB prompt:
linux /ROOT/ubuntu-1/@/boot/vmlinuz-2.6.35-27-generic boot=zfs rpool=AltPool bootfs=AltPool/ROOT/foobar-3
Note that GRUB does not currently dereference symbolic links in a ZFS filesystem, so you cannot use the
/initrd.img symlinks as GRUB command arguments.
Two things must happen before Debian or Ubuntu installations to a native ZFS filesystem are easy:
GRUB Enhancements (finished)
The regular GRUB packages in Ubuntu releases prior to 11.04 Natty Narwhal do not recognize zpool version 28 or lack zfs support entirely. The local GRUB 1.99~rc1 build provided here was taken directly from the upstream bzr head and forcibly linked against zfs-lib. It should be properly patched and packaged. The
grub-probe utility must be enhanced to resolve a "zfs" mount point.
grub-mkconfig utility and its run-parts must be enhanced to recognize a ZFS root and create the
/boot/grub/grub.cfg file appropriately.
Last edited by dajhorn,