Difference between revisions of "ZFS"

From ArchWiki
Jump to: navigation, search
m (Spelling correction)
(mkinitramfs hook)
(27 intermediate revisions by 14 users not shown)
Line 7: Line 7:
 
{{Article summary end}}
 
{{Article summary end}}
  
[[Wikipedia:ZFS|ZFS]] is an advanced filesystem created by [[Wikipedia:Sun Microsystems|Sun Microsystems]] (now owned by Oracle) and released for OpenSolaris in November 2005.  Features of ZFS include: pooled storage (integrated volume management -- zpool), [[Wikipedia:Copy-on-write|Copy-on-write]], [[Wikipedia:Snapshot (computer storage)|snapshots]], data integrity verification and automatic repair (scrubbing), [[Wikipedia:http://en.wikipedia.org/wiki/RAID-Z#RAID-Z|RAID-Z]], and a maximum [[Wikipedia:Exabyte|16 Exabyte]] volume size.  ZFS is licensed under the [[Wikipedia:CDDL|Common Development and Distribution License]] (CDDL).
+
[[Wikipedia:ZFS|ZFS]] is an advanced filesystem created by [[Wikipedia:Sun Microsystems|Sun Microsystems]] (now owned by Oracle) and released for OpenSolaris in November 2005.  Features of ZFS include: pooled storage (integrated volume management -- zpool), [[Wikipedia:Copy-on-write|Copy-on-write]], [[Wikipedia:Snapshot (computer storage)|snapshots]], data integrity verification and automatic repair (scrubbing), [[Wikipedia:RAID-Z|RAID-Z]], and a maximum [[Wikipedia:Exabyte|16 Exabyte]] volume size.  ZFS is licensed under the [[Wikipedia:CDDL|Common Development and Distribution License]] (CDDL).
  
Described as [http://web.archive.org/web/20060428092023/http://www.sun.com/2004-0914/feature/ "The last word in filesystems"] ZFS is stable, fast, secure, and future-proof.  Being licensed under the GPL incompatible CDDL, it is not possible for ZFS to be distributed along with the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with [http://zfsonlinux.org/ zfsonlinux.org].
+
Described as [http://web.archive.org/web/20060428092023/http://www.sun.com/2004-0914/feature/ "The last word in filesystems"] ZFS is stable, fast, secure, and future-proof.  Being licensed under the GPL incompatible CDDL, it is not possible for ZFS to be distributed along with the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with [http://zfsonlinux.org/ zfsonlinux.org] (ZOL).
  
 
==Installation==
 
==Installation==
Line 15: Line 15:
 
The ZFS kernel module is available in the [[AUR]] via {{aur|zfs}}.
 
The ZFS kernel module is available in the [[AUR]] via {{aur|zfs}}.
  
==Configuration==
+
{{note|The ZFS and SPL (Solaris Porting Layer is a Linux kernel module which provides many of the Solaris kernel APIs) kernel modules are tied to a specific kernel version. It would not be possible to apply any kernel updates until updated packages are uploaded to AUR or the archzfs repository.}}
  
ZFS is considered a "zero administration" filesystem by its creators, therefore configuring ZFS is very straight forward. Configuration is done primarily with two commands, {{ic|# zfs}} and {{ic|# zpool}}.
+
Should you wish to update the core/linux package before the AUR/zfs and AUR/spl packages' dependency lists are updated, a possible work-around is to remove (uninstall) spl and zfs packages (the respective modules and file system may stay in-use), update the core/linux package, build + install zfs and spl packages - just do not forget to edit PKGBUILD and correct the core/linux version number in "depends" section to match the updated version). Finally, the system may be rebooted. [ This is only for the situation, when ZFS is not used for root filesystem. ]
  
===initramfs hook===
+
===Unofficial repository===
  
Should you wish to use ZFS on root file system, the kernel module must be added to the hooks list in [[Mkinitcpio|mkinitcpio.conf]]:
+
For fast and effortless installation and updates, the [http://demizerone.com/archzfs "archzfs"] signed repository is available to add to your {{ic|pacman.conf}}:
  
To see all available options for the ZFS hook,
+
{{hc|/etc/pacman.conf|<nowiki>
 +
[archzfs]
 +
Server = http://demizerone.com/$repo/core/$arch</nowiki>
 +
}}
  
  $ mkinitcpio -H zfs
+
The repository and packages are signed with the maintainer's PGP key which is verifiable here: http://demizerone.com. This key is not trusted by any of the Arch Linux master keys, so it will need to be locally signed before use. See [[pacman-key]].
  
Now edit the mkinitcpio config,
+
Add the maintainer's key,
  
{{hc|/etc/mkinitcpio.conf|
+
# pacman-key -r 0EE7A126
...
+
 
HOOKS<nowiki>="base udev autodetect pata scsi sata filesystems usbinput fsck zfs"</nowiki>
+
and locally sign to add it to the system's trust database,
...
+
 
 +
# pacman-key --lsign-key 0EE7A126
 +
 
 +
Once the key has been signed, it is now possible to update the package database,
 +
 
 +
# pacman -Syy
 +
 
 +
and install ZFS packages:
 +
 
 +
# pacman -S archzfs
 +
 
 +
===Archzfs testing repository===
 +
 
 +
If you have the testing repository active in {{ic|pacman.conf}} then it is possible to use the archzfs repository that tracks the testing kernel.
 +
 
 +
{{hc|# /etc/pacman.conf|<nowiki>
 +
[archzfs]
 +
Server = http://demizerone.com/$repo/testing/$arch</nowiki>
 
}}
 
}}
  
Make sure its placement is last on the list to prevent errors from causing errors when the module is loaded. Such as [[#No hostid found]].
+
===Archiso tracking repository===
  
Recreate the ramdisk
+
ZFS can easily be used from within the archiso live environment by using the special archiso tracking repository for ZFS. This repository makes it easy to install Arch Linux on a root ZFS filesystem, or to mount ZFS pools from within an archiso live environment using an up-to-date live medium. To use this repository from the live environment, add the following server line to pacman.conf:
  
  # mkinitcpio -p linux
+
{{hc|/etc/pacman.conf|<nowiki>
 +
[archzfs]
 +
Server = http://demizerone.com/$repo/archiso/$arch</nowiki>
 +
}}
  
There should be no errors.
+
This repository and packages are also signed, so the key must be locally signed following the steps listed in the previous section before use. For a guide on how to install Arch Linux on to a root ZFS filesystem, see [[Installing Arch Linux on ZFS]].
  
===Add zfs to DAEMONS list===
+
==Configuration==
  
For ZFS to live by its "zero administration" namesake, the zfs daemon must bee loaded at startup. A benefit to this is that it is not necessary to mount your zpool in {{ic|/etc/fstab}}; the zfs daemon imports and mounts your zfs pool automatically.
+
ZFS is considered a "zero administration" filesystem by its creators; therefore, configuring ZFS is very straight forward. Configuration is done primarily with two commands: {{ic|zfs}} and {{ic|zpool}}.
  
{{hc|/etc/rc.conf|
+
===mkinitramfs hook===
 +
 
 +
If you are using ZFS on your root filesystem, then you will need to add the ZFS hook to [[Mkinitcpio|mkinitcpio.conf]]; if you are not using ZFS for your root filesystem, then you do not need to add the ZFS hook.
 +
 
 +
You will need to change your [[kernel parameters]] to include the dataset you want to boot. You can use <code>zfs=bootfs</code> to use the ZFS bootfs (set via <code>zpool set bootfs=rpool/ROOT/arch rpool</code>) or you can set the [[kernel parameters]] to <code>zfs=<pool>/<dataset></code> to boot directly from a ZFS dataset.
 +
 
 +
To see all available options for the ZFS hook:
 +
 
 +
  $ mkinitcpio -H zfs
 +
 
 +
To use the mkinitcpio hook, you will need to add <code>zfs</code> to your <code>HOOKS</code> in <code>/etc/mkinitcpio.conf</code>:
 +
 
 +
{{hc|/etc/mkinitcpio.conf|
 
...
 
...
DAEMONS<nowiki>=(... @syslog-ng zfs dbus ...)</nowiki>
+
HOOKS<nowiki>="base udev autodetect modconf encrypt zfs filesystems usbinput"</nowiki>
 
...
 
...
 
}}
 
}}
  
And now start the daemon if it is not started already
+
{{note|It is not necessary to use the "fsck" hook with ZFS. ZFS automatically fixes any errors that occur within the filesystem. However, if the hook is required for another filesystem used on the system, such as ext4, the current ZFS packaging implementation does not yet properly handle fsck requests from mkinitcpio and an error is produced when generating a new ramdisk.}}
  
  # rc.d start zfs
+
It is important to place this after any hooks which are needed to prepare the drive before it is mounted. For example, if your ZFS volume is encrypted, then you will need to place encrypt before the zfs hook to unlock it first.
  
===Prepare your drives===
+
Recreate the ramdisk:
  
If using storage drives larger than 2TB, you must partition them with gdisk.  gdisk is available in the [extra] repository via {{Pkg|gptfdisk}}.
+
  # mkinitcpio -p linux
  
Use {{ic| # parted --list}} to see a list of all available drives. If any of the storage drives you plan to use show {{ic|Error: /dev/<device>: unrecognised disk label}} when being listed by GNU Parted, then an error will occur when trying to create the pool. The partition tables of the storage drives containing this error will need to be redone.
+
===Automatic Start===
  
Create a gpt partition table using the defaults (entire) disk and the default "linux filesystem". It is recommended by the ZFS on linux developers to use the entire disk. See [http://zfsonlinux.org/faq.html ZFS on Linux FAQ].
+
For ZFS to live by its "zero administration" namesake, the zfs daemon must be loaded at startup. A benefit to this is that it is not necessary to mount your zpool in {{ic|/etc/fstab}}; the zfs daemon imports and mounts one zfs pool automatically. The daemon mounts a zfs pool reading the file {{ic|/etc/zfs/zpool.cache}}, so the zfs pool that you want to automatically mounted must write the file there.
  
Once the partition table is set, producing a list of your storage drives with GNU parted should produce similar output:
+
Set a pool as to be automatically mounted by the zfs daemon:
 +
# zpool set cachefile=/etc/zfs/zpool.cache <pool>
  
{{hc|# parted --list|
+
==Systemd==
...
+
  
Model: ATA ST3000DM001-9YN1 (scsi)
+
Enable the service so it is automatically started at boot time:
Disk /dev/sdb: 3001GB
+
Sector size (logical/physical): 512B/4096B
+
Partition Table: gpt
+
Disk Flags:
+
  
Number  Start   End    Size    File system  Name              Flags
+
   # systemctl enable zfs.service
1      1049kB  3001GB  3001GB              Linux filesystem
+
  
...
+
To manually start the daemon:
}}
+
 
 +
  # systemctl start zfs.service
 +
 
 +
==Create a storage pool==
 +
 
 +
Use {{ic| # parted --list}} to see a list of all available drives. It is not necessary to partition your drives before creating the zfs filesystem, this will be done automatically. However, if you feel the need to completely wipe your drive before creating the filesystem, this can be easily done with the dd command.
 +
 
 +
  # dd if=/dev/zero of=/dev/<device>
  
===Create a storage pool===
+
It should not have to be stated, but be careful with this command!
  
Firstly, the [http://zfsonlinux.org/faq.html#WhatDevNamesShouldIUseWhenCreatingMyPool zfs on linux developers recommend] using device ids when creating ZFS storage pools of less than 10 devices. To find the id's for your device, simply
+
Once you have the list of drives, it is now time to get the id's of the drives you will be using. The [http://zfsonlinux.org/faq.html#WhatDevNamesShouldIUseWhenCreatingMyPool zfs on Linux developers recommend] using device ids when creating ZFS storage pools of less than 10 devices. To find the id's for your device, simply:
  
 
   $ ls -lah /dev/disk/by-id/
 
   $ ls -lah /dev/disk/by-id/
Line 91: Line 128:
  
 
   lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JKRR -> ../../sdc
 
   lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JKRR -> ../../sdc
  lrwxrwxrwx 1 root root 10 Aug 12 05:30 ata-ST3000DM001-9YN166_S1F0JKRR-part1 -> ../../sdc1
 
 
   lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JTM1 -> ../../sde
 
   lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JTM1 -> ../../sde
  lrwxrwxrwx 1 root root 10 Aug 12 05:30 ata-ST3000DM001-9YN166_S1F0JTM1-part1 -> ../../sde1
 
 
   lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KBP8 -> ../../sdd
 
   lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KBP8 -> ../../sdd
  lrwxrwxrwx 1 root root 10 Aug 12 05:30 ata-ST3000DM001-9YN166_S1F0KBP8-part1 -> ../../sdd1
 
 
   lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KDGY -> ../../sdb
 
   lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KDGY -> ../../sdb
  lrwxrwxrwx 1 root root 10 Aug 12 05:30 ata-ST3000DM001-9YN166_S1F0KDGY-part1 -> ../../sdb1
 
  
Now finally, create the ZFS pool:
+
Now, finally, create the ZFS pool:
  
   # zpool create -m <mount> <pool> raidz <ids>
+
   # zpool create -f -m <mount> <pool> raidz <ids>
 
+
or as an example
+
 
+
  # zpool create -m /mnt/data bigdata raidz ata-ST3000DM001-9YN166_S1F0KDGY-part1 ata-ST3000DM001-9YN166_S1F0JKRR-part1 ata-ST3000DM001-9YN166_S1F0KBP8-part1 ata-ST3000DM001-9YN166_S1F0JTM1-part1
+
  
 
* '''create''': subcommand to create the pool.
 
* '''create''': subcommand to create the pool.
  
* '''pool''': This is the name of the pool. Change it to whatever you like.
+
* '''-f''': Force creating the pool. This is to overcome the "EFI label error". See [[#does not contain an EFI label]].
  
 
* '''-m''': The mount point of the pool. If this is not specified, than your pool will be mounted to {{ic|/<pool>}}.
 
* '''-m''': The mount point of the pool. If this is not specified, than your pool will be mounted to {{ic|/<pool>}}.
 +
 +
* '''pool''': This is the name of the pool. Change it to whatever you like.
  
 
* '''raidz''': This is the type of virtual device that will be created from the pool of devices. Raidz is a special implementation of raid5. See [https://blogs.oracle.com/bonwick/entry/raid_z Jeff Bonwick's Blog -- RAID-Z] for more information about raidz.
 
* '''raidz''': This is the type of virtual device that will be created from the pool of devices. Raidz is a special implementation of raid5. See [https://blogs.oracle.com/bonwick/entry/raid_z Jeff Bonwick's Blog -- RAID-Z] for more information about raidz.
  
* '''ids''': The names of the drives or partions that you want to include into your pool. Get it from {{ic|/dev/disk/by-id}}.
+
* '''ids''': The names of the drives or partitions that you want to include into your pool. Get it from {{ic|/dev/disk/by-id}}.
 +
 
 +
Here is an example for the full command:
 +
 
 +
  # zpool create -f -m /mnt/data bigdata raidz ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-9YN166_S1F0JKRR ata-ST3000DM001-9YN166_S1F0KBP8 ata-ST3000DM001-9YN166_S1F0JTM1
  
 
If the command is successful, there will be no output. Using the {{ic|$ mount}} command will show that you pool is mounted. Using {{ic|# zpool status}} will show that your pool has been created.
 
If the command is successful, there will be no output. Using the {{ic|$ mount}} command will show that you pool is mounted. Using {{ic|# zpool status}} will show that your pool has been created.
Line 136: Line 171:
 
}}
 
}}
  
At this point it would be good to reboot your computer to make sure your ZFS pool is mounted at boot. It is best to deal with all errors A.S.A.P. before transfering your data.
+
At this point it would be good to reboot your computer to make sure your ZFS pool is mounted at boot. It is best to deal with all errors before transferring your data.
  
 
== Usage ==
 
== Usage ==
  
To see all the commands available in ZFS, use
+
To see all the commands available in ZFS, use :
  
 
   $ man zfs
 
   $ man zfs
  
or
+
or:
  
 
   $ man zpool
 
   $ man zpool
Line 150: Line 185:
 
=== Scrub ===
 
=== Scrub ===
  
ZFS pools should be scrubbed at least once a week. To scrub your pool
+
ZFS pools should be scrubbed at least once a week. To scrub your pool:
  
 
   # zpool scrub <pool>
 
   # zpool scrub <pool>
  
To do automatic scrubbing once a week, set the following line in your root crontab
+
To do automatic scrubbing once a week, set the following line in your root crontab:
  
 
{{hc|# crontab -e|
 
{{hc|# crontab -e|
Line 172: Line 207:
 
=== Destroy a storage pool ===
 
=== Destroy a storage pool ===
  
ZFS makes it easy to destroy a mounted storage pool, removing all metadata about the ZFS device. This command destroys any data contained in the pool.
+
ZFS makes it easy to destroy a mounted storage pool, removing all metadata about the ZFS device. This command destroys any data contained in the pool:
  
 
   # zpool destroy <pool>
 
   # zpool destroy <pool>
  
and now when checking the status
+
And now when checking the status:
  
 
{{hc|# zpool status|no pools available}}
 
{{hc|# zpool status|no pools available}}
  
 
To find the name of your pool, see [[#Check zfs pool status]].
 
To find the name of your pool, see [[#Check zfs pool status]].
 +
 +
=== Export a storage pool ===
 +
 +
If you are going to use the pool in a different system, or are doing
 +
 +
=== Swap partition ===
 +
 +
ZFS does not allow to use swapfiles, but you can use a ZFS volume as swap partition. It is importart to set the ZVOL block size to match the system page size, for x86_64 systems that is 4k.
 +
 +
Create a 8gb zfs volume:
 +
 +
  # zfs create -V 8gb -b 4K <pool>/swap
 +
 +
Prepare it as swap partition:
 +
 +
  # mkswap /dev/zvol/<pool>/maindisk/swap
 +
 +
Enable swap:
 +
 +
  # swapon /dev/zvol/<pool>/maindisk/swap
 +
 +
To make it permament you need to edit your {{ic|/etc/fstab}}.
 +
 +
Add a line to {{ic|/etc/fstab}}:
 +
 +
  /dev/zvol/<pool>/swap none swap defaults 0 0
  
 
==Troubleshooting==
 
==Troubleshooting==
  
===No hostid found===
+
=== does not contain an EFI label ===
 +
 
 +
The following error will occur when attempting to create a zfs filesystem,
 +
 
 +
  /dev/disk/by-id/<id> does not contain an EFI label but it may contain partition
 +
 
 +
The way to overcome this is to use <code>-f</code> with the zfs create command.
 +
 
 +
=== No hostid found ===
  
 
An error that occurs at boot with the following lines appearing before initscript output:
 
An error that occurs at boot with the following lines appearing before initscript output:
Line 190: Line 259:
 
   ZFS: No hostid found on kernel command line or /etc/hostid.
 
   ZFS: No hostid found on kernel command line or /etc/hostid.
  
This error occurs because the {{ic|zfs}} hook in {{ic|/etc/mkinitcpio.conf}} is loaded before the filesystem. Move the zfs module hook after {{ic|filesystems}} like so,
+
This warning occurs because the ZFS module does not have access to the spl hosted. There are two solutions, for this. You can either place your spl hostid in the [[kernel parameters]] in your boot loader. For example, adding <code>spl.spl_hostid=0x00bab10c</code>.
  
{{hc|/etc/mkinitcpio.conf|
+
The other solution is to make sure that there is a hostid in <code>/etc/hostid</code>, and then regenerate the initramfs image. Which will copy the hostid into the initramfs image.
...
+
HOOKS<nowiki>="base udev autodetect pata scsi sata filesystems usbinput fsck zfs"</nowiki>
+
...
+
}}
+
 
+
and regenerate the ramdisk
+
  
 
   # mkinitcpio -p linux
 
   # mkinitcpio -p linux
  
reboot to verify changes are correct.
+
=== On boot the zfs pool does not mount stating: "pool may be in use from other system" ===
 +
 
 +
You can always ignore the check adding {{ic|zfs_force&#61;1}} in your [[kernel parameters]], but it is not advisable as a permanent solution.
 +
 
 +
First of all double check you actually exported the pool correctly. Exporting the zpool clears the hostid marking the ownership. So during the first boot the zpool should mount correctly. If it does not there is some other problem.
 +
 
 +
Reboot again, if the zfs pool refuses to mount it means your hostid is not yet correctly set in the early boot phase and it confuses zfs. So you have to manually tell zfs the correct number, once the hostid is coherent across the reboots the zpool will mount correctly.
 +
 
 +
Boot using zfs_force and write down your hostid. This one is just an example.
 +
% hostid
 +
0a0af0f8
 +
Follow the previous section to set it.
 +
 
 +
== Tips and tricks ==
 +
 
 +
=== Emergency chroot repair with archzfs ===
 +
 
 +
Here is how to use the archiso to get into your ZFS filesystem for maintenance.
 +
 
 +
Boot the latest archiso and bring up your network:
 +
 
 +
    # wifi-menu
 +
    # ip link set eth0 up
 +
 
 +
Test the network connection:
 +
 
 +
    # ping google.com
 +
 
 +
Sync the pacman package database:
 +
 
 +
    # pacman -Syy
 +
 
 +
(optional) Install your favorite text editor:
 +
 
 +
    # pacman -S vim
 +
 
 +
Add archzfs archiso repository to {{ic|pacman.conf}}:
 +
 
 +
{{hc|/etc/pacman.conf|<nowiki>
 +
[archzfs]
 +
Server = http://demizerone.com/$repo/archiso/$arch</nowiki>}}
 +
 
 +
Sync the pacman package database:
 +
 
 +
    # pacman -Syy
 +
 
 +
Install the ZFS package group:
 +
 
 +
    # pacman -S archzfs
 +
 
 +
Load the ZFS kernel modules:
 +
 
 +
    # modprobe zfs
 +
 
 +
Import your pool:
 +
 
 +
    # zpool import -a -R /mnt
 +
 
 +
Mount your boot partitions (if you have them):
 +
 
 +
    # mount /dev/sda2 /mnt/boot
 +
    # mount /dev/sda1 /mnt/boot/efi
 +
 
 +
Chroot into your ZFS filesystem:
 +
 
 +
    # arch-chroot /mnt /bin/bash
 +
 
 +
Check your kernel version:
 +
 
 +
    # pacman -Qi linux
 +
    # uname -r
 +
 
 +
uname will show the kernel version of the archiso. If they are different, you will need to run depmod (in the chroot) with the correct kernel version of your chroot installation:
 +
 
 +
    # depmod -a 3.6.9-1-ARCH (version gathered from pacman -Qi linux)
 +
 
 +
This will load the correct kernel modules for the kernel version installed in your chroot installation.
 +
 
 +
Regenerate your ramdisk:
 +
 
 +
    # mkinitcpio -p linux
 +
 
 +
There should be no errors.
  
==Tips and tricks==
+
== See also ==
  
==See also==
 
 
* [http://zfsonlinux.org/ ZFS on Linux]
 
* [http://zfsonlinux.org/ ZFS on Linux]
 
* [http://zfsonlinux.org/faq.html ZFS on Linux FAQ]
 
* [http://zfsonlinux.org/faq.html ZFS on Linux FAQ]

Revision as of 15:46, 2 April 2013

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary end

ZFS is an advanced filesystem created by Sun Microsystems (now owned by Oracle) and released for OpenSolaris in November 2005. Features of ZFS include: pooled storage (integrated volume management -- zpool), Copy-on-write, snapshots, data integrity verification and automatic repair (scrubbing), RAID-Z, and a maximum 16 Exabyte volume size. ZFS is licensed under the Common Development and Distribution License (CDDL).

Described as "The last word in filesystems" ZFS is stable, fast, secure, and future-proof. Being licensed under the GPL incompatible CDDL, it is not possible for ZFS to be distributed along with the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with zfsonlinux.org (ZOL).

Installation

The ZFS kernel module is available in the AUR via zfsAUR.

Note: The ZFS and SPL (Solaris Porting Layer is a Linux kernel module which provides many of the Solaris kernel APIs) kernel modules are tied to a specific kernel version. It would not be possible to apply any kernel updates until updated packages are uploaded to AUR or the archzfs repository.

Should you wish to update the core/linux package before the AUR/zfs and AUR/spl packages' dependency lists are updated, a possible work-around is to remove (uninstall) spl and zfs packages (the respective modules and file system may stay in-use), update the core/linux package, build + install zfs and spl packages - just do not forget to edit PKGBUILD and correct the core/linux version number in "depends" section to match the updated version). Finally, the system may be rebooted. [ This is only for the situation, when ZFS is not used for root filesystem. ]

Unofficial repository

For fast and effortless installation and updates, the "archzfs" signed repository is available to add to your pacman.conf:

/etc/pacman.conf
[archzfs]
Server = http://demizerone.com/$repo/core/$arch

The repository and packages are signed with the maintainer's PGP key which is verifiable here: http://demizerone.com. This key is not trusted by any of the Arch Linux master keys, so it will need to be locally signed before use. See pacman-key.

Add the maintainer's key,

# pacman-key -r 0EE7A126

and locally sign to add it to the system's trust database,

# pacman-key --lsign-key 0EE7A126

Once the key has been signed, it is now possible to update the package database,

# pacman -Syy

and install ZFS packages:

# pacman -S archzfs

Archzfs testing repository

If you have the testing repository active in pacman.conf then it is possible to use the archzfs repository that tracks the testing kernel.

# /etc/pacman.conf
[archzfs]
Server = http://demizerone.com/$repo/testing/$arch

Archiso tracking repository

ZFS can easily be used from within the archiso live environment by using the special archiso tracking repository for ZFS. This repository makes it easy to install Arch Linux on a root ZFS filesystem, or to mount ZFS pools from within an archiso live environment using an up-to-date live medium. To use this repository from the live environment, add the following server line to pacman.conf:

/etc/pacman.conf
[archzfs]
Server = http://demizerone.com/$repo/archiso/$arch

This repository and packages are also signed, so the key must be locally signed following the steps listed in the previous section before use. For a guide on how to install Arch Linux on to a root ZFS filesystem, see Installing Arch Linux on ZFS.

Configuration

ZFS is considered a "zero administration" filesystem by its creators; therefore, configuring ZFS is very straight forward. Configuration is done primarily with two commands: zfs and zpool.

mkinitramfs hook

If you are using ZFS on your root filesystem, then you will need to add the ZFS hook to mkinitcpio.conf; if you are not using ZFS for your root filesystem, then you do not need to add the ZFS hook.

You will need to change your kernel parameters to include the dataset you want to boot. You can use zfs=bootfs to use the ZFS bootfs (set via zpool set bootfs=rpool/ROOT/arch rpool) or you can set the kernel parameters to zfs=<pool>/<dataset> to boot directly from a ZFS dataset.

To see all available options for the ZFS hook:

 $ mkinitcpio -H zfs

To use the mkinitcpio hook, you will need to add zfs to your HOOKS in /etc/mkinitcpio.conf:

/etc/mkinitcpio.conf
...
HOOKS="base udev autodetect modconf encrypt zfs filesystems usbinput"
...
Note: It is not necessary to use the "fsck" hook with ZFS. ZFS automatically fixes any errors that occur within the filesystem. However, if the hook is required for another filesystem used on the system, such as ext4, the current ZFS packaging implementation does not yet properly handle fsck requests from mkinitcpio and an error is produced when generating a new ramdisk.

It is important to place this after any hooks which are needed to prepare the drive before it is mounted. For example, if your ZFS volume is encrypted, then you will need to place encrypt before the zfs hook to unlock it first.

Recreate the ramdisk:

 # mkinitcpio -p linux

Automatic Start

For ZFS to live by its "zero administration" namesake, the zfs daemon must be loaded at startup. A benefit to this is that it is not necessary to mount your zpool in /etc/fstab; the zfs daemon imports and mounts one zfs pool automatically. The daemon mounts a zfs pool reading the file /etc/zfs/zpool.cache, so the zfs pool that you want to automatically mounted must write the file there.

Set a pool as to be automatically mounted by the zfs daemon:

# zpool set cachefile=/etc/zfs/zpool.cache <pool>

Systemd

Enable the service so it is automatically started at boot time:

 # systemctl enable zfs.service

To manually start the daemon:

 # systemctl start zfs.service

Create a storage pool

Use # parted --list to see a list of all available drives. It is not necessary to partition your drives before creating the zfs filesystem, this will be done automatically. However, if you feel the need to completely wipe your drive before creating the filesystem, this can be easily done with the dd command.

 # dd if=/dev/zero of=/dev/<device>

It should not have to be stated, but be careful with this command!

Once you have the list of drives, it is now time to get the id's of the drives you will be using. The zfs on Linux developers recommend using device ids when creating ZFS storage pools of less than 10 devices. To find the id's for your device, simply:

 $ ls -lah /dev/disk/by-id/

The ids should look similar to the following:

 lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JKRR -> ../../sdc
 lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JTM1 -> ../../sde
 lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KBP8 -> ../../sdd
 lrwxrwxrwx 1 root root  9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KDGY -> ../../sdb

Now, finally, create the ZFS pool:

 # zpool create -f -m <mount> <pool> raidz <ids>
  • create: subcommand to create the pool.
  • -m: The mount point of the pool. If this is not specified, than your pool will be mounted to /<pool>.
  • pool: This is the name of the pool. Change it to whatever you like.
  • raidz: This is the type of virtual device that will be created from the pool of devices. Raidz is a special implementation of raid5. See Jeff Bonwick's Blog -- RAID-Z for more information about raidz.
  • ids: The names of the drives or partitions that you want to include into your pool. Get it from /dev/disk/by-id.

Here is an example for the full command:

 # zpool create -f -m /mnt/data bigdata raidz ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-9YN166_S1F0JKRR ata-ST3000DM001-9YN166_S1F0KBP8 ata-ST3000DM001-9YN166_S1F0JTM1

If the command is successful, there will be no output. Using the $ mount command will show that you pool is mounted. Using # zpool status will show that your pool has been created.

# zpool status
  pool: bigdata
 state: ONLINE
 scan: none requested
config:

        NAME                                       STATE     READ WRITE CKSUM
        bigdata                                    ONLINE       0     0     0
          -0                                       ONLINE       0     0     0
            ata-ST3000DM001-9YN166_S1F0KDGY-part1  ONLINE       0     0     0
            ata-ST3000DM001-9YN166_S1F0JKRR-part1  ONLINE       0     0     0
            ata-ST3000DM001-9YN166_S1F0KBP8-part1  ONLINE       0     0     0
            ata-ST3000DM001-9YN166_S1F0JTM1-part1  ONLINE       0     0     0

errors: No known data errors

At this point it would be good to reboot your computer to make sure your ZFS pool is mounted at boot. It is best to deal with all errors before transferring your data.

Usage

To see all the commands available in ZFS, use :

 $ man zfs

or:

 $ man zpool

Scrub

ZFS pools should be scrubbed at least once a week. To scrub your pool:

 # zpool scrub <pool>

To do automatic scrubbing once a week, set the following line in your root crontab:

# crontab -e
...
30 19 * * 5 zpool scrub <pool>
...

Replace <pool> with the name of your ZFS storage pool.

Check zfs pool status

To print a nice table with statistics about your ZFS pool, including and read/write errors, use

 # zpool status -v

Destroy a storage pool

ZFS makes it easy to destroy a mounted storage pool, removing all metadata about the ZFS device. This command destroys any data contained in the pool:

 # zpool destroy <pool>

And now when checking the status:

# zpool status
no pools available

To find the name of your pool, see #Check zfs pool status.

Export a storage pool

If you are going to use the pool in a different system, or are doing

Swap partition

ZFS does not allow to use swapfiles, but you can use a ZFS volume as swap partition. It is importart to set the ZVOL block size to match the system page size, for x86_64 systems that is 4k.

Create a 8gb zfs volume:

 # zfs create -V 8gb -b 4K <pool>/swap

Prepare it as swap partition:

 # mkswap /dev/zvol/<pool>/maindisk/swap

Enable swap:

 # swapon /dev/zvol/<pool>/maindisk/swap

To make it permament you need to edit your /etc/fstab.

Add a line to /etc/fstab:

 /dev/zvol/<pool>/swap none swap defaults 0 0

Troubleshooting

does not contain an EFI label

The following error will occur when attempting to create a zfs filesystem,

 /dev/disk/by-id/<id> does not contain an EFI label but it may contain partition

The way to overcome this is to use -f with the zfs create command.

No hostid found

An error that occurs at boot with the following lines appearing before initscript output:

 ZFS: No hostid found on kernel command line or /etc/hostid.

This warning occurs because the ZFS module does not have access to the spl hosted. There are two solutions, for this. You can either place your spl hostid in the kernel parameters in your boot loader. For example, adding spl.spl_hostid=0x00bab10c.

The other solution is to make sure that there is a hostid in /etc/hostid, and then regenerate the initramfs image. Which will copy the hostid into the initramfs image.

 # mkinitcpio -p linux

On boot the zfs pool does not mount stating: "pool may be in use from other system"

You can always ignore the check adding zfs_force=1 in your kernel parameters, but it is not advisable as a permanent solution.

First of all double check you actually exported the pool correctly. Exporting the zpool clears the hostid marking the ownership. So during the first boot the zpool should mount correctly. If it does not there is some other problem.

Reboot again, if the zfs pool refuses to mount it means your hostid is not yet correctly set in the early boot phase and it confuses zfs. So you have to manually tell zfs the correct number, once the hostid is coherent across the reboots the zpool will mount correctly.

Boot using zfs_force and write down your hostid. This one is just an example.

% hostid
0a0af0f8

Follow the previous section to set it.

Tips and tricks

Emergency chroot repair with archzfs

Here is how to use the archiso to get into your ZFS filesystem for maintenance.

Boot the latest archiso and bring up your network:

   # wifi-menu
   # ip link set eth0 up

Test the network connection:

   # ping google.com

Sync the pacman package database:

   # pacman -Syy

(optional) Install your favorite text editor:

   # pacman -S vim

Add archzfs archiso repository to pacman.conf:

/etc/pacman.conf
[archzfs]
Server = http://demizerone.com/$repo/archiso/$arch

Sync the pacman package database:

   # pacman -Syy

Install the ZFS package group:

   # pacman -S archzfs

Load the ZFS kernel modules:

   # modprobe zfs

Import your pool:

   # zpool import -a -R /mnt

Mount your boot partitions (if you have them):

   # mount /dev/sda2 /mnt/boot
   # mount /dev/sda1 /mnt/boot/efi

Chroot into your ZFS filesystem:

   # arch-chroot /mnt /bin/bash

Check your kernel version:

   # pacman -Qi linux
   # uname -r

uname will show the kernel version of the archiso. If they are different, you will need to run depmod (in the chroot) with the correct kernel version of your chroot installation:

   # depmod -a 3.6.9-1-ARCH (version gathered from pacman -Qi linux)

This will load the correct kernel modules for the kernel version installed in your chroot installation.

Regenerate your ramdisk:

   # mkinitcpio -p linux

There should be no errors.

See also