Know How -- ZFS -- Really don't panic

ZFS on Linux via FUSE.

Links:

An ultra-short HowTo

Here is my way how I got running ZFS on Debian 5.0.4 (Lenny)

Prerequisites

This is for a build on Debian Lenny. This is the list I needed after installing a minimal Debian Lenny from scratch:

apt-get install scons
apt-get install libssl-dev
apt-get install fuse-utils libfuse-dev libfuse2
apt-get install build-essential zlib1g-dev
apt-get install libaio-dev
apt-get install libattr1-dev
apt-get install git git-core

zfs-fuse moved to GIT. This makes it more easy to get it going as GIT is a lot more mature than Mercurial.

First Download

cd into some directory of your choice where you want to build zfs. Each step is based on the one before (so if you restart be sure to be in the right directory!):

Get the source:
git clone http://git.zfs-fuse.net/official
cd official
git checkout -b testing origin/testing
In a certain future (when 0.7.0 is out) you do not need the last line!

Later you can update

This probably are the commands (I am not so used to GIT to know if these are correct):
git pull origin
git merge origin/testing
When you are on the master branch:
git pull origin
git merge origin/testing

Build

Always do the complete build after update!

Build and install the tools (without debugging!):
cd src
scons -c
scons
sudo scons install
The first time you make the install, be sure to setup the /etc/zfs/zfsrc
sudo cp -i ../contrib/zfsrc /etc/zfs/.
sudo vi /etc/zfs/zfsrc

Build the ZFS userland kernel (with debugging!):
scons -c
scons debug=2

Run

Run the ZFS userland kernel (do not miss the modprobe!):
su -
cd zfs-fuse
modprobe fuse
./run.sh

First steps for creating a pool

Now you can create your pool:
zpool create POOLNAME raidz2 /dev/DRIVE1 /dev/DRIVE2 /dev/DRIVE3 /dev/DRIVE4
You will find it at /POOLNAME

Notes

  • Without the modprobe I was missing /dev/fuse
  • Without the "debug=2" the kernel is so quiet that you cannot trace any problems.
  • Manuals are missing completely. Manuals are not important, as all zfs commands tell some help if called without arguments. Also ZFS is easy, as soon as you started with it you know everything. See First Steps.

Experimenting with different versions

If you are experimenting with different versions, you will find some annoying "feature" of scons:

Scons is not able to handle installs properly:
scons -c
scons install
does not work as expected. It installs things based on the dependency date, and those dependendencies are NOT updated by compiling from scratch like the binaries are!

This means:

You cannot be sure to install things properly with "scons install" if you jump between versions.

I do not know any fix except doing a
rm -f /usr/local/sbin/z{db,fs,fs-fuse,pool,streamdump,test}
and then
scons install
As the destinations to install are missing then, scons will recreate them with the current version to install.

However to be sure to NOT using the wrong zpool command with another ZFS release (sometimes the ioctl numbers change, so a "zpool list" may come out as "zpool destroy" ioctl without a safety net like mine) I have a fix which was not recommended by the upstream:
vi lib/libzfscommon/include/sys/fs/zfs.h
and then I change the line
#define ZFS_IOC         ('Z' << 8)
into something like
#define ZFS_IOC         (('Z'+XXXXX) << 8)
where XXXXX is a number I always change from time to time when I change the major release.

This makes zfs-fuse unresponsive against commands coming from other compiled versions.

Note that upstream recommended to change the socket path etc. like in the patch attached to following post: groups.google.com/group/zfs-fuse/msg/803ba07156652208

  • The good thing about this is, that it makes it possible to run different versions of zfs fuse in parallel.
  • The bad thing about this is, that it may be cumbersome to change 3 places in a source just to be sure to have zfs versions to not interfere with each other.
Perhaps another way is to change the ZFS_SOCK_NAME in lib/libzfscommon/include/sys/fs/zfs.h instead of the IOCTL code. As ZFS-Fuse is userspace code this works, too.

-Tino, 2010-05-17