Install

2015-04-12T05:55:44Z

121.216.2.234: Noted need for Xcode 6.3 or greater due to stac() clac() in codebase.

[[Category:About O3X]]
[[Category:Getting and installing O3X]]
== 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 [[Uninstall#Uninstalling_a_release_version|uninstalling a release version]].

== Installing from source ==
===Initial installation from source===
(Adapted from an [http://zerobsd.tumblr.com/post/62586498252/os-x-with-zfs article by ZeroBSD].)

Before doing anything else, please include <code>keepsyms=y</code> in your boot-args, and, if you are on OS X Yosemite, <code>kext-dev-mode=1</code>. For instance,
<syntaxhighlight lang="bash">
sudo nvram boot-args="-v keepsyms=y kext-dev-mode=1"
</syntaxhighlight>
This will take effect the next time you reboot. The argument <code>-v</code> will make your boot screen verbose instead of just showing the Apple logo, the argument <code>keepsyms=y</code> will make your panic reports more useful for us, and the argument <code>kext-dev-mode=1</code> will allow you to autoload unsigned kernel extensions from /System/Library/Extensions on OS X Yosemite.

If you have any other implementation of ZFS installed, you must uninstall it and reboot before proceeding further. Similarly, if you have installed the O3X installer version, please follow the [https://openzfsonosx.org/wiki/Uninstall uninstallation directions] before proceeding.

Prerequisites:

* [https://developer.apple.com/xcode/ Xcode] (from [http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 Mac App Store] or https://developer.apple.com/downloads/index.action)
* Xcode Command Line Tools (https://developer.apple.com/downloads/index.action)
* [http://brew.sh/ Homebrew] (or [http://www.macports.org/‎ MacPorts])

Note: Xcode 6.3 or later is now required to build due to Broadwell CPU support requirements.

To install Homebrew:

<syntaxhighlight lang="bash">
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
</syntaxhighlight>

Paste that at a Terminal prompt.

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

<syntaxhighlight lang="text">
brew install automake libtool gawk coreutils
</syntaxhighlight>

If you have used brew before, it might pay to check it

<syntaxhighlight lang="text">
brew doctor
</syntaxhighlight>

and if prompted

<syntaxhighlight lang="text">
brew prune
</syntaxhighlight>

Create two folders in your home directory.

<syntaxhighlight lang="bash">
mkdir -p ~/Developer ~/bin
chmod 700 ~/Developer ~/bin
chmod +a "group:everyone deny delete" ~/Developer ~/bin
</syntaxhighlight>

Adjust your PATH variable:

<syntaxhighlight lang="bash">
echo 'export PATH=$HOME/bin:/usr/local/bin:$PATH' >> ~/.bash_profile
</syntaxhighlight>

and update your environment by sourcing your profile.

<syntaxhighlight lang="bash">
source ~/.bash_profile
</syntaxhighlight>

To acquire the sources and build ZFS, we can use the [[zfsadm]] script found [https://gist.github.com/ilovezfs/7713854#file-zfsadm here].

<syntaxhighlight lang="bash">
cd ~/Developer/
git clone https://gist.github.com/7713854.git zfsadm-repo
cp zfsadm-repo/zfsadm ~/bin/
</syntaxhighlight>

Now you can can build OpenZFS on OS X:

<syntaxhighlight lang="bash">
zfsadm
</syntaxhighlight>

This will take a few minutes, depending on your hardware. There may be some warnings during the compilation. Do not worry about it unless you see errors.

Before using ZFS, we need to actually install it.

<syntaxhighlight lang="bash">
cd ~/Developer/spl
sudo make install
cd ~/Developer/zfs
sudo make install
</syntaxhighlight>

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

<syntaxhighlight lang="bash">
kextstat | grep lundman
</syntaxhighlight>

You should see something similar to

<syntaxhighlight lang="text">
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>
</syntaxhighlight>

If not, make sure kextd is aware of them.

<syntaxhighlight lang="bash">
sudo touch /System/Library/Extensions
sudo killall -HUP kextd
</syntaxhighlight>

Now check again.

<syntaxhighlight lang="bash">
kextstat | grep lundman
</syntaxhighlight>

If not, you can load the kexts manually.

<syntaxhighlight lang="bash">
cd /System/Library/Extensions
sudo kextload spl.kext
sudo kextload -d spl.kext zfs.kext
</syntaxhighlight>

Try running

<syntaxhighlight lang="bash">
zpool
</syntaxhighlight>

to see if everything is installed and configured properly.

You can go ahead and [[zpool#Creating_a_pool|create your pools]] at this point.

===Upgrading a source install===
When you want to get the [https://github.com/openzfsonosx/zfs/commits/master 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.

<syntaxhighlight lang="bash">
zpool list
</syntaxhighlight>

For every pool listed, run

<syntaxhighlight lang="bash">
sudo zpool export $poolname
</syntaxhighlight>

Make sure they have exported successfully.

<syntaxhighlight lang="bash">
zpool status
</syntaxhighlight>

It should say, "no pools available."

Alternatively, you can use this script to export all pools:
<syntaxhighlight lang="bash">
#!/bin/bash

if [ x$(which zpool) != x ]
then
zpool list -H | awk -F '\t' '{print $1;}' | xargs -I '#' sudo zpool export '#'
else
cd ~/Developer/zfs
./cmd.sh zpool list -H | awk -F '\t' '{print $1;}' | xargs -I '#' sudo ./cmd.sh zpool export '#'
fi
</syntaxhighlight>

Get any [[zfsadm]] updates:
<syntaxhighlight lang="bash">
cd ~/Developer
[ -d zfsadm-repo/.git ] && (cd zfsadm-repo ; git pull)
[ ! -d zfsadm-repo/.git ] && git clone https://gist.github.com/7713854.git zfsadm-repo
cp zfsadm-repo/zfsadm ~/bin/
</syntaxhighlight>

Now you should be able to upgrade your ZFS installation.

<syntaxhighlight lang="bash">
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

kextstat | grep lundman

# If not, make sure kextd is aware of them

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

# and check again

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
</syntaxhighlight>

If net.lundman.kernel.dependencies has been updated, which is rarely the case, a reboot will be necessary.

===Uninstalling a source install===
If you ever want to uninstall, follow the instructions for [[Uninstall#Uninstalling_a_source_install|uninstalling a source install]].

== Using without actually installing (development) ==
This method is usually appropriate only for Developers.

The procedure is the same as found in the section [[Install#Installing_from_source|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

<syntaxhighlight lang="bash">
zfsadm -k
</syntaxhighlight>

By default, zfsadm -k will copy spl.kext and zfs.kext from the source where they were built to /System/Library/Extensions, recursively change the ownership of everything in /System/Library/Extensions/spl.kext and /System/Library/Extensions/zfs.kext to be owned by the user "root" and the group "wheel," and then load the kexts directly from /System/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:

<syntaxhighlight lang="bash">
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
</syntaxhighlight>

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

<syntaxhighlight lang="bash">
~/Developer/zfs/cmd.sh zfs
</syntaxhighlight>

== 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.

<syntaxhighlight lang="bash">
sudo zpool import
</syntaxhighlight>

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.

<syntaxhighlight lang="bash">
zpool status
</syntaxhighlight>

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.

<syntaxhighlight lang="bash">
sudo zpool import poolname (or guid)
</syntaxhighlight>

(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.

<syntaxhighlight lang="bash">
sudo zpool import -f poolname (or guid)
</syntaxhighlight>

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'.

<syntaxhighlight lang="bash">
zpool status
</syntaxhighlight>

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

<syntaxhighlight lang="bash">
sudo zpool import
</syntaxhighlight>

OpenZFS on OS X - User contributions [en]

Install