Install

From OpenZFS on OS X
Revision as of 08:05, 27 April 2014 by Ilovezfs (Talk | contribs)

Jump to: navigation, search

Installing the official release

Download the most recent dmg from the Downloads page.

Verify the checksums.

$ md5 OpenZFS_on_OS_X_*.dmg
$ sha1sum OpenZFS_on_OS_X_*.dmg
$ openssl dgst -sha256 OpenZFS_on_OS_X_*.dmg

Open the .dmg file.

Read ReadMe.rtf.

Start the installer by opening OpenZFS_on_OS_X_x.y.z.pkg.

Follow the prompts.

If you ever want to uninstall, follow the instructions for uninstalling a release version.

Installing from source

(Adapted from an article by ZeroBSD.)

If you have any other implementation of ZFS installed, you must uninstall it and reboot before proceeding further.

If you have OpenZFS on OS X installed, please follow the uninstallation directions before proceeding.

We'll need to fetch the latest source from the repository on GitHub and then compile it.

For this, we'll need some prerequisites:


To install Homebrew:

ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"

Paste that at a Terminal prompt.

Once Homebrew is installed, we need a couple of things first:

brew install automake libtool gawk coreutils

Create two folders in your home directory.

mkdir -p ~/Developer
mkdir -p ~/bin

Add the ~/bin directory to your PATH.

echo 'export PATH=$HOME/bin:$PATH' >> ~/.bash_profile

and update your environment by sourcing your profile.

source ~/.bash_profile

To acquire the sources and build ZFS, we'll need the zfsadm script found here.

cd ~/Developer/
git clone https://gist.github.com/7713854.git zfsadm-repo
cp zfsadm-repo/zfsadm ~/bin/
chmod +x ~/bin/zfsadm

All set. Let's go cloning and building ZFS:

zfsadm

Now let it work. This should take a few minutes depending on the speed of your machine.

Before using ZFS, we need to actually install it.

cd ~/Developer/zfs
sudo make install
cd ~/Developer/spl
sudo make install

You can check to see if the kernel extensions loaded automatically with

sudo kextstat | grep lundman

You should see something similar to

137    1 0xffffff803f61a800 0x20c      0x20c      net.lundman.kernel.dependencies (10.0.0)
144    1 0xffffff7f82720000 0xd000     0xd000     net.lundman.spl (1.0.0) <137 7 5 4 3 1>
145    0 0xffffff7f8272d000 0x202000   0x202000   net.lundman.zfs (1.0.0) <144 13 7 5 4 3 1>

If not, make sure kextd is aware of them.

sudo touch /System/Library/Extensions
sudo killall -HUP kextd

And check again.

sudo kextstat | grep lundman

If not, you can load the kexts manually.

cd /System/Library/Extensions
sudo kextload spl.kext
sudo kextload -d spl.kext zfs.kext

Now add /usr/local/sbin to your PATH. This is where you will find the command binaries (zpool, zfs, zdb, etc.).

echo 'export PATH=$PATH:/usr/local/sbin' >> ~/.bash_profile

and update your environment by sourcing your profile again.

source ~/.bash_profile

Try running

sudo zpool

to see if everything is installed and configured properly.

You can go ahead and create your pools at this point.

When you want to get the latest commits from the GitHub, here's a quick overview of things you need to run.

First make sure you have exported all of your pools.

sudo zpool list

For every pool listed, run

sudo zpool export $poolname

in order to prevent a kernel panic when the kexts are unloaded.

Make sure they have exported successfully.

sudo zpool status

It should say, "no pools available."

Now you should be able to upgrade your ZFS installation safely.

cd ~/Developer
 
cd spl
make clean
cd ..
 
cd zfs
make clean
cd ..
 
zfsadm
 
# Assuming the build completed successfully,
# unload the kexts. If you did not export all of
# your pools this will panic:
 
zfsadm -u
 
# Now install the upgrade.
 
cd spl
sudo make install
cd ..
 
cd zfs
sudo make install
 
# And verify they reloaded automatically
 
sudo kextstat | grep lundman
 
# If not, make sure kextd is aware of them
 
sudo touch /System/Library/Extensions
sudo killall -HUP kextd
 
# and check again
 
sudo kextstat | grep lundman
 
# if they they still have not loaded automatically
 
cd /System/Library/Extensions
sudo kextload spl.kext
sudo kextload -d spl.kext zfs.kext

If net.lundman.kernel.dependencies has been updated (quite rare) a reboot would be necessary.

If you ever want to uninstall, follow the instructions for uninstalling a source install.

Installing a development build DMG

Development build DMGs are often released here: http://lundman.net/ftp/osx.zfs/

  • Export your pools and unload the kexts.
  • Download one of the builds.
  • Open the .dmg file
  • cd into either 64 or 32 depending on whether your architecture is i386 or x86_64
cd /Volumes/osx.zfs*/64
  • Run install_zfs.sh
sudo ./install_zfs.sh

If you ever want to uninstall, follow the instructions for uninstalling a development build dmg.

Using without actually installing (development)

This method is usually appropriate only for Developers.

The procedure is the same as found in the section installing from source except that you never run "make install." Instead you load the kexts manually, and execute the binaries directly from the source tree.

You can load the kexts manually by running

zfsadm -k

By default, zfsadm -k will create the directory ~/Library/Extensions if it doesn't exist, remove ~/Library/Extensions/spl.kext and ~/Library/Extensions/zfs.kext if they are present, copy spl.kext and zfs.kext from the source where they were built to ~/Library/Extenions, recursively change the ownership of everything in ~/Library/Extensions/spl.kext and ~/Library/Extensions/zfs.kext to be owned to be owned by the user "root" and the group "wheel," and then load the kexts directly from ~/Library/Extensions. If you prefer to use a different directory, use the -i option in zfsadm or edit zfsadm to hard code a different directory.

If you do not wish to use zfsadm, you can do all of this yourself, using whatever target directory you'd like. For example, you might do the following:

cd /tmp
sudo rm -rf o3x
sudo mkdir o3x
 
cd ~/Developer
sudo cp -r zfs/module/zfs/zfs.kext /tmp/o3x/ 
sudo cp -r spl/module/spl/spl.kext /tmp/o3x/
 
cd /tmp/o3x
sudo chown -R *
sudo kextload spl.kext
sudo kextload -d spl.kext zfs.kext

Once the kexts have been loaded, you can test the commands.

sudo ~/Developer/zfs/cmd.sh zfs status

Migrating old Pools (from MacZFS or ZEVO)

First export all of your pools, and uninstall the other implementation. It is all right if you forgot to export your pools before uninstalling. You will just need to use the '-f' option when importing into OpenZFS on OS X.

To find out the pool names, you need to execute the command for pool discovery.

sudo zpool import

This will tell you what pools are available to be imported, but will not actually import anything. You can see that nothing has been imported yet by using the 'zpool status' command.

sudo zpool status

Now that you know what pools are available to be imported, you can actually import a pool by supplying the name or guid that you saw during pool discovery.

sudo zpool import poolname (or guid)

(Notice how this differs from the command for pool discovery.)

If you forgot to export before migrating, you will need to use the '-f' option.

sudo zpool import -f poolname (or guid)

If you want to see the same information you saw during pool discovery, you will now need to use 'zpool status' rather than 'zpool import'.

sudo zpool status

If all pools have been imported, the pool discovery command— 'zpool import' with no pool or guid specified— will return without any output.

sudo zpool import