OpenZFS on OS X - User contributions [en]

Stopping Spotlight etc. from changing ZFS without permission

2020-08-27T20:36:58Z

89.115.197.57: /* Solutions */ add more extensive approach to add "flag files" and disable macOS services

== The Issue ==

ZFS is a great solution for backing up data, and moving data between platforms (e.g. Linux and Mac OS X). However, if you connect an external ZFS drive to Mac OS X, you may be unpleasantly surprised to find that Spotlight, Finder etc. will modify the filesystems on the drive without asking (and even in violation of the user privileges granted by those filesystems). This goes against several basic principles that you probably expect:

* the filesystem should not change unless you change data on the filesystem. E.g. simply plugging in the drive should not change the filesystem.

* any attempted changes to the filesystem should obey the privilege rules set on that filesystem. E.g. if the current user plugging in the drive lacks write privileges to the filesystem, no changes should be allowed.

However, Spotlight, Finder etc. do not obey these expectations. This can lead to serious problems for standard ZFS activities such as snapshot based backup. For example, say you backup data by sending ZFS snapshots from one ZFS filesystem to another ZFS drive. When you try to push incremental snapshots to an existing filesystem, it may fail with messages like "data has been changed since snapshot XYZ" -- even if you never wrote to that backup filesystem since your last snapshot. Now you are in a quandary. You will have to manually investigate the backup filesystem(s) to see what all the changes are, and whether might be any changes that need to be preserved (rather than just rolled back). If you are used to working with ZFS on Linux this may initially baffle you, because on Linux a ZFS filesystem will not change in content unless you deliberately write data to it!

The following Mac OS X services will modify your ZFS filesystems silently:

* Spotlight
* Finder (.DS_Store, Trash)

== Solutions ==

* in general, if you are connecting an external ZFS drive to a Mac solely to READ data from it, '''just import it readonly'''. This is the one trivially easy way to avoid the whole problem, e.g.:

'''zpool import -o readonly=on tank'''

If that is not an option, then you are going to have clean up your ZFS filesystems (every time) after OS X has "dirtied" them:

* '''always take a snapshot of ZFS filesystems BEFORE plugging them in to a Mac'''. This makes it relatively easy to know which changes are "OS X dirt" vs. previous data changes that you made before plugging into the Mac, and to rollback the dirt. For example: '''zfs diff -H tank@lastsnap tank''' will give you a list of new, modified and deleted files since lastsnap. Use Google to learn what Spotlight and Finder's hidden file names are.

* if you did not deliberately make changes to a given ZFS filesystem while connected to the Mac, then '''just rollback to the latest snapshot''' (as your first action once you import that drive to a non-Mac host).

* add "flag files" to each file system to prevent various OS X services from dirtying them. E.g. '''touch /tank/.metadata_never_index''' should [http://superuser.com/questions/1000280/disable-ds-store-spotlight-and-other-metadata-on-mac-disk-image prevent Spotlight indexing]. We should collect a list here of all the rules for preventing such "dirty" services.

A more extensive approach to add "flag files" and disable macOS services from polluting the file system:

# set the name of your ZFS pool on macOS, e.g.
zpool_name=tank

# Remove macOS specific files from Spotlight, fseventsd, and the Trashes, create dummy files instead
sudo rm -rfv /Volumes/$zpool_name/.{,_.}{fseventsd,Spotlight-V*,Trashes}
sudo mkdir -pv /Volumes/$zpool_name/.fseventsd
sudo touch /Volumes/$zpool_name/.fseventsd/no_log /Volumes/$zpool_name/.metadata_never_index /Volumes/$zpool_name/.Trashes

# Turn off Spotlight indexing and remove the .Spotlight-V* folders in newer macOS versions
sudo mdutil -i off /Volumes/$zpool_name
sudo mdutil -X /Volumes/$zpool_name

# Optionally, change ownership to current user to enable zfs volume operations w/o sudo
sudo chown -R "$USER" /Volumes/$zpool_name

Install

2020-06-04T12:56:44Z

89.115.197.57: /* Installing the official release */ add link to Bash_completion page

[[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
$ shasum OpenZFS_on_OS_X_*.dmg
$ shasum -a 256 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.

Bash completion is also available: see [[Bash_completion]] page

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

Before doing anything else, please set your boot-args.

On macOS Mojave (10.14), High Sierra (10.13), Sierra (10.12), OS X El Capitan (10.11), OS X Mavericks (10.9), and OS X Mountain Lion (10.8) :
<syntaxhighlight lang="bash">
sudo nvram boot-args="-v keepsyms=1"
</syntaxhighlight>

On OS X Yosemite (10.10):
<syntaxhighlight lang="bash">
sudo nvram boot-args="-v keepsyms=1 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=1</code> will make your panic reports more useful for us, and the argument <code>kext-dev-mode=1</code> (OS X Yosemite ONLY) will allow you to load your custom-built, unsigned kexts kernel extensions. Note that as of OS X El Capitan, kext-dev-mode is obsolete and does nothing. If you are on macOS Sierra (10.12) or OS X El Capitan, you should remove kext-dev-mode from your boot-args to avoid confusion.

If you are a developer, you may want <code>debug=0x144</code> in your boot-args as well, as explained here: [[Development]]

Tips for getting into recovery mode, useful if developing on a VM, type the following commands in a shell in the guest VM:
<syntaxhighlight lang="bash">
sudo nvram "recovery-boot-mode=unused"
sudo reboot recovery
</syntaxhighlight>

For macOS Sierra (10.12) and OS X El Capitan (10.11), you also need to boot into the Recovery OS (either the Recovery partition or bootable OS X install media for 10.11) and run
<syntaxhighlight lang="bash">
csrutil disable
</syntaxhighlight>
or
<syntaxhighlight lang="bash">
csrutil enable --without kext
</syntaxhighlight>
The latter will allow you to load your custom-built, unsigned kernel extensions, while keeping the rest of System Integrity Protection (SIP) in place.
(Depending on your needs, other options you may want are <code>--without fs</code>, <code>--without debug</code>, <code>--without dtrace</code>, or <code>--without nvram</code>. If you specify all of them, that is equivalent to <code>csrutil disable</code>. The <code>--without</code> option takes a comma-delimited list or can be specified multiple times: <code>--without kext,debug,dtrace</code> is equivalent to <code>--without kext --without debug --without dtrace</code>).

Starting with macOS Catalina, you will probably also want to disable the '''reboot to load kext''' using:

spctl kext-consent disable

During Recovery-Boot.

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. Additionally, as of XCode 8, if you are on 10.11 specifically (unnecessary on 10.12), you need to install the CLT (Command Line Tools):

<syntaxhighlight lang="bash">
xcode-select --install
</syntaxhighlight>

To install Homebrew:

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

If you already have Homebrew installed, you should
<syntaxhighlight lang="text">
brew update && brew upgrade
</syntaxhighlight>

Once Homebrew is installed or updated, you should check the output of
<syntaxhighlight lang="text">
brew doctor
</syntaxhighlight>
and address any issues it identifies that you know are not false positives.

If you have used brew before, you should also run
<syntaxhighlight lang="text">
brew prune
</syntaxhighlight>

Once your system is ready to brew, you should install the following:
<syntaxhighlight lang="text">
brew install automake libtool gawk coreutils
</syntaxhighlight>
(Note that autoconf will automatically be installed as well because it is a dependency of automake.)

Now that the needed tools are installed, it's time to set up your developer work space. 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>

Now adjust your PATH variable, unless you know it's already set appropriately.

If you're on OS X Mavericks or above (>= 10.9), run this:

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

If you're on OS X Mountain Lion (10.8), you will want to run this instead:
<syntaxhighlight lang="bash">
echo 'export PATH=$HOME/bin:/usr/local/bin:$PATH' >> ~/.bash_profile
</syntaxhighlight>

Then 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. If you are a developer and wish not to install ZFS, but rather run it from the compile directory, skip ahead.

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

===Running ZFS from the source build===

In the ZFS directory there is a script called '''load.sh''' which will load the two kext modules. To run userland binaries from the source tree, use the provided '''cmd.sh''' script to set the DYNDL_LIBRARY_PATH variable correctly to find the libraries.

Note that '''load.sh''' will also start '''tail -f /var/log/system.log''' for your convenience.
<syntaxhighlight lang="text" highlight="1,2,3,6,7,10,12,14">
$ sudo bash
# cd ~/Developer/zfs
# ./load.sh
kernel[0]: SPL: Loaded module v1.3.1-15_g4e2ff66 (DEBUG mode), (ncpu 4, memsize 4294967296, pages 1048576)
kernel[0]: ZFS: Loaded module v1.3.1-230_gb9658da, ZFS pool version 5000, ZFS filesystem version 5
# ./cmd.sh zpool import BOOM
# ./cmd.sh zpool list
NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT
BOOM 39.8G 207M 39.5G - 1% 0% 1.00x ONLINE -
# ./cmd.sh zpool export BOOM
Unmount successful for /Volumes/BOOM
# kextunload -b net.lundman.zfs
kernel[0]: ZFS: Unloaded module v1.3.1-230_gb9658da
# kextunload -b net.lundman.spl
kernel[0]: SPL: Released 524288 bytes from vmem_seg_arena
kernel[0]: SPL: Unloaded module. (os_mem_alloc: 0)
</syntaxhighlight>

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

Alternatively, you can run:
<syntaxhighlight lang="bash">
sudo zpool export -a
</syntaxhighlight>
which will try to export all pools for you.

Make sure they have exported successfully.

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

It should say, "no pools available."

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.

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 /Library/Extensions /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>

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

Bash completion

2020-06-04T12:54:07Z

89.115.197.57: fix shell code eaten by wiki syntax

Assuming you already have [http://brew.sh/ Homebrew] installed
== Bash version < 4 ==
brew install bash-completion
Add the following lines to your ~/.bash_profile:
if [ -f $(brew --prefix)/etc/bash_completion ]; then
. $(brew --prefix)/etc/bash_completion
fi
Install the ZFS bash completions:
cd /usr/local/etc/bash_completion.d
curl -O https://raw.githubusercontent.com/openzfs/zfs/master/contrib/bash_completion.d/zfs
chmod +x /usr/local/etc/bash_completion.d/zfs
Source the added file (source /usr/local/etc/bash_completion.d/zfs) or open a new terminal window.

== Bash version ≥ 4 ==
brew install bash-completion@2
Add the following lines to your ~/.bash_profile or ~/.bashrc (depending on your preferred setup of startup files):
export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
if [ -r "/usr/local/etc/profile.d/bash_completion.sh" ]; then
. "/usr/local/etc/profile.d/bash_completion.sh"
fi
Install the ZFS bash completions:
cd /usr/local/share/bash-completion/completions
curl -O https://raw.githubusercontent.com/openzfs/zfs/master/contrib/bash_completion.d/zfs
chmod +x /usr/local/share/bash-completion/completions/zfs
Source the added file (source /usr/local/share/bash-completion/completions/zfs) or open a new terminal window.

Bash completion

2020-06-04T12:50:55Z

89.115.197.57: update github url and add bash ≥ 4 instructions

Assuming you already have [http://brew.sh/ Homebrew] installed
== Bash version < 4 ==
brew install bash-completion
Add the following lines to your ~/.bash_profile:
if [ -f $(brew --prefix)/etc/bash_completion ]; then
. $(brew --prefix)/etc/bash_completion
fi
Install the ZFS bash completions:
cd /usr/local/etc/bash_completion.d
curl -O https://raw.githubusercontent.com/openzfs/zfs/master/contrib/bash_completion.d/zfs
chmod +x /usr/local/etc/bash_completion.d/zfs
Source the added file (source /usr/local/etc/bash_completion.d/zfs) or open a new terminal window.

== Bash version ≥ 4 ==
brew install bash-completion@2
Add the following lines to your ~/.bash_profile or ~/.bashrc (depending on your preferred setup of startup files):
export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"
Install the ZFS bash completions:
cd /usr/local/share/bash-completion/completions
curl -O https://raw.githubusercontent.com/openzfs/zfs/master/contrib/bash_completion.d/zfs
chmod +x /usr/local/share/bash-completion/completions/zfs
Source the added file (source /usr/local/share/bash-completion/completions/zfs) or open a new terminal window.

Install

2020-06-03T16:27:30Z

89.115.197.57: update brew install command to the current one on brew.sh

[[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
$ shasum OpenZFS_on_OS_X_*.dmg
$ shasum -a 256 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===

Before doing anything else, please set your boot-args.

On macOS Mojave (10.14), High Sierra (10.13), Sierra (10.12), OS X El Capitan (10.11), OS X Mavericks (10.9), and OS X Mountain Lion (10.8) :
<syntaxhighlight lang="bash">
sudo nvram boot-args="-v keepsyms=1"
</syntaxhighlight>

On OS X Yosemite (10.10):
<syntaxhighlight lang="bash">
sudo nvram boot-args="-v keepsyms=1 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=1</code> will make your panic reports more useful for us, and the argument <code>kext-dev-mode=1</code> (OS X Yosemite ONLY) will allow you to load your custom-built, unsigned kexts kernel extensions. Note that as of OS X El Capitan, kext-dev-mode is obsolete and does nothing. If you are on macOS Sierra (10.12) or OS X El Capitan, you should remove kext-dev-mode from your boot-args to avoid confusion.

If you are a developer, you may want <code>debug=0x144</code> in your boot-args as well, as explained here: [[Development]]

Tips for getting into recovery mode, useful if developing on a VM, type the following commands in a shell in the guest VM:
<syntaxhighlight lang="bash">
sudo nvram "recovery-boot-mode=unused"
sudo reboot recovery
</syntaxhighlight>

For macOS Sierra (10.12) and OS X El Capitan (10.11), you also need to boot into the Recovery OS (either the Recovery partition or bootable OS X install media for 10.11) and run
<syntaxhighlight lang="bash">
csrutil disable
</syntaxhighlight>
or
<syntaxhighlight lang="bash">
csrutil enable --without kext
</syntaxhighlight>
The latter will allow you to load your custom-built, unsigned kernel extensions, while keeping the rest of System Integrity Protection (SIP) in place.
(Depending on your needs, other options you may want are <code>--without fs</code>, <code>--without debug</code>, <code>--without dtrace</code>, or <code>--without nvram</code>. If you specify all of them, that is equivalent to <code>csrutil disable</code>. The <code>--without</code> option takes a comma-delimited list or can be specified multiple times: <code>--without kext,debug,dtrace</code> is equivalent to <code>--without kext --without debug --without dtrace</code>).

Starting with macOS Catalina, you will probably also want to disable the '''reboot to load kext''' using:

spctl kext-consent disable

During Recovery-Boot.

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. Additionally, as of XCode 8, if you are on 10.11 specifically (unnecessary on 10.12), you need to install the CLT (Command Line Tools):

<syntaxhighlight lang="bash">
xcode-select --install
</syntaxhighlight>

To install Homebrew:

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

If you already have Homebrew installed, you should
<syntaxhighlight lang="text">
brew update && brew upgrade
</syntaxhighlight>

Once Homebrew is installed or updated, you should check the output of
<syntaxhighlight lang="text">
brew doctor
</syntaxhighlight>
and address any issues it identifies that you know are not false positives.

If you have used brew before, you should also run
<syntaxhighlight lang="text">
brew prune
</syntaxhighlight>

Once your system is ready to brew, you should install the following:
<syntaxhighlight lang="text">
brew install automake libtool gawk coreutils
</syntaxhighlight>
(Note that autoconf will automatically be installed as well because it is a dependency of automake.)

Now that the needed tools are installed, it's time to set up your developer work space. 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>

Now adjust your PATH variable, unless you know it's already set appropriately.

If you're on OS X Mavericks or above (>= 10.9), run this:

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

If you're on OS X Mountain Lion (10.8), you will want to run this instead:
<syntaxhighlight lang="bash">
echo 'export PATH=$HOME/bin:/usr/local/bin:$PATH' >> ~/.bash_profile
</syntaxhighlight>

Then 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. If you are a developer and wish not to install ZFS, but rather run it from the compile directory, skip ahead.

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

===Running ZFS from the source build===

In the ZFS directory there is a script called '''load.sh''' which will load the two kext modules. To run userland binaries from the source tree, use the provided '''cmd.sh''' script to set the DYNDL_LIBRARY_PATH variable correctly to find the libraries.

Note that '''load.sh''' will also start '''tail -f /var/log/system.log''' for your convenience.
<syntaxhighlight lang="text" highlight="1,2,3,6,7,10,12,14">
$ sudo bash
# cd ~/Developer/zfs
# ./load.sh
kernel[0]: SPL: Loaded module v1.3.1-15_g4e2ff66 (DEBUG mode), (ncpu 4, memsize 4294967296, pages 1048576)
kernel[0]: ZFS: Loaded module v1.3.1-230_gb9658da, ZFS pool version 5000, ZFS filesystem version 5
# ./cmd.sh zpool import BOOM
# ./cmd.sh zpool list
NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT
BOOM 39.8G 207M 39.5G - 1% 0% 1.00x ONLINE -
# ./cmd.sh zpool export BOOM
Unmount successful for /Volumes/BOOM
# kextunload -b net.lundman.zfs
kernel[0]: ZFS: Unloaded module v1.3.1-230_gb9658da
# kextunload -b net.lundman.spl
kernel[0]: SPL: Released 524288 bytes from vmem_seg_arena
kernel[0]: SPL: Unloaded module. (os_mem_alloc: 0)
</syntaxhighlight>

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

Alternatively, you can run:
<syntaxhighlight lang="bash">
sudo zpool export -a
</syntaxhighlight>
which will try to export all pools for you.

Make sure they have exported successfully.

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

It should say, "no pools available."

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.

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 /Library/Extensions /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>

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