Difference between revisions of "Install"

From OpenZFS on OS X
Jump to: navigation, search
(Pseudo-Installing for Development)
(Initial installation from source)
 
(110 intermediate revisions by 14 users not shown)
Line 1: Line 1:
== Installing the Official Release ==
+
[[Category:About O3X]]
 +
[[Category:Getting and installing O3X]]
 +
== Installing the official release ==
  
 
Download the most recent dmg from the [[Downloads]] page.
 
Download the most recent dmg from the [[Downloads]] page.
Line 6: Line 8:
  
 
  $ md5 OpenZFS_on_OS_X_*.dmg
 
  $ md5 OpenZFS_on_OS_X_*.dmg
  $ sha1sum OpenZFS_on_OS_X_*.dmg
+
  $ shasum OpenZFS_on_OS_X_*.dmg
  $ openssl dgst -sha256 OpenZFS_on_OS_X_*.dmg
+
  $ shasum -a 256 OpenZFS_on_OS_X_*.dmg
  
 
Open the .dmg file.
 
Open the .dmg file.
Line 17: Line 19:
 
Follow the prompts.
 
Follow the prompts.
  
If you ever want to uninstall, follow the instructions for [[Uninstall#Uninstalling_a_Release_Version|uninstalling a release version]].
+
Bash completion is also available: see [[Bash_completion]] page
  
== Installing from Source ==
+
If you ever want to uninstall, follow the instructions for [[Uninstall#Uninstalling_a_release_version|uninstalling a release version]].
(Adapted from an [http://zerobsd.tumblr.com/post/62586498252/os-x-with-zfs article by ZeroBSD].)
+
  
If you have any other implementation of ZFS installed, you must uninstall it and reboot before proceeding further.
+
== Installing from source ==
 +
===Initial installation from source===
  
We'll need to fetch the latest source from the [https://github.com/zfs-osx repository on GitHub] and then compile it.
+
New-port: Currently recommended ./configure line is:
 +
./configure CPPFLAGS="-I/usr/local/opt/gettext/include -I/usr/local/opt/openssl@1.1/include" LDFLAGS="-L/usr/local/opt/gettext/lib/ -L/usr/local/opt/openssl@1.1/lib" CFLAGS="-g -O0" --sysconfdir=/etc --localstatedir=/var --prefix=/usr/local --sbindir=/usr/local/bin
  
For this, we'll need some prerequisites:
+
 
 +
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)
 
* [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)
 
* Xcode Command Line Tools (https://developer.apple.com/downloads/index.action)
* [http://brew.sh/ Homebrew] (or [http://www.macports.org/MacPorts])
+
* [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:
 
To install Homebrew:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Paste that at a Terminal prompt.
+
If you already have Homebrew installed, you should
 +
<syntaxhighlight lang="text">
 +
brew update && brew upgrade
 +
</syntaxhighlight>
  
Once Homebrew is installed, we need a couple of things first:
+
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">
 
<syntaxhighlight lang="text">
brew install automake libtool gawk
+
brew prune
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Create two folders in your home directory.
+
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">
 
<syntaxhighlight lang="bash">
mkdir ~/Developer
+
mkdir -p ~/Developer ~/bin
mkdir ~/bin
+
chmod 700 ~/Developer ~/bin
 +
chmod +a "group:everyone deny delete" ~/Developer ~/bin
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Add the ~/bin directory to your PATH.
+
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">
 
<syntaxhighlight lang="bash">
Line 60: Line 131:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
and update your environment by sourcing your profile.
+
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">
 
<syntaxhighlight lang="bash">
Line 66: Line 142:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
To acquire the sources and build ZFS, we'll need the [[zfsadm]] script found [https://gist.github.com/ilovezfs/7713854#file-zfsadm here].
+
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">
 
<syntaxhighlight lang="bash">
Line 72: Line 148:
 
git clone https://gist.github.com/7713854.git zfsadm-repo
 
git clone https://gist.github.com/7713854.git zfsadm-repo
 
cp zfsadm-repo/zfsadm ~/bin/
 
cp zfsadm-repo/zfsadm ~/bin/
chmod +x ~/bin/zfsadm
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
All set. Let's go cloning and building ZFS:
+
Now you can can build OpenZFS on OS X:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 81: Line 156:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Now let it work. This should take a few minutes depending on the speed of your machine.
+
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.
+
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">
 
<syntaxhighlight lang="bash">
cd ~/Developer/zfs
 
sudo make install
 
 
cd ~/Developer/spl
 
cd ~/Developer/spl
 +
sudo make install
 +
cd ~/Developer/zfs
 
sudo make install
 
sudo make install
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 95: Line 170:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
sudo kextstat | grep lundman
+
kextstat | grep lundman
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 113: Line 188:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
And check again.
+
Now check again.
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
sudo kextstat | grep lundman
+
kextstat | grep lundman
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 125: Line 200:
 
sudo kextload spl.kext
 
sudo kextload spl.kext
 
sudo kextload -d spl.kext zfs.kext
 
sudo kextload -d spl.kext zfs.kext
</syntaxhighlight>
 
 
Now add /usr/local/sbin to your PATH. This is where you will find the command binaries (zpool, zfs, zdb, etc.).
 
 
<syntaxhighlight lang="bash">
 
echo 'export PATH=$PATH:/usr/local/sbin' >> ~/.bash_profile
 
</syntaxhighlight>
 
 
and update your environment by sourcing your profile again.
 
 
<syntaxhighlight lang="bash">
 
source ~/.bash_profile
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 142: Line 205:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
sudo zpool
+
zpool
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 149: Line 212:
 
You can go ahead and [[zpool#Creating_a_pool|create your pools]] at this point.
 
You can go ahead and [[zpool#Creating_a_pool|create your pools]] at this point.
  
When you want to get the [https://github.com/zfs-osx/zfs/commits/master latest commits] from the GitHub, here's a quick overview of things you need to run.
+
===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.
 
First make sure you have exported all of your pools.
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
sudo zpool list
+
zpool list
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 163: Line 251:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
in order to prevent a kernel panic when the kexts are unloaded.
+
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.
 
Make sure they have exported successfully.
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
sudo zpool status
+
zpool status
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
It should say, "no pools available."
 
It should say, "no pools available."
  
Now you should be able to upgrade your ZFS installation safely.
+
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">
 
<syntaxhighlight lang="bash">
Line 189: Line 289:
  
 
# Assuming the build completed successfully,
 
# Assuming the build completed successfully,
# unload the kexts. If you did not export all of
+
# unload the kexts.
# your pools this will panic:
+
  
 
zfsadm -u
 
zfsadm -u
Line 205: Line 304:
 
# And verify they reloaded automatically
 
# And verify they reloaded automatically
  
sudo kextstat | grep lundman
+
kextstat | grep lundman
  
 
# If not, make sure kextd is aware of them
 
# If not, make sure kextd is aware of them
  
sudo touch /System/Library/Extensions
+
sudo touch /Library/Extensions /System/Library/Extensions
 
sudo killall -HUP kextd
 
sudo killall -HUP kextd
  
 
# and check again
 
# and check again
  
sudo kextstat | grep lundman
+
kextstat | grep lundman
  
 
# if they they still have not loaded automatically
 
# if they they still have not loaded automatically
Line 223: Line 322:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
If net.lundman.kernel.dependencies has been updated (quite rare) a reboot would 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]].
If you ever want to uninstall, follow the instructions for [[Uninstall#Uninstalling_a_Source_Install|uninstalling a source install]].
+
  
== Installing an Unofficial Disk Image (.dmg) for Testers ==
+
== Using without actually installing (development) ==
 +
This method is usually appropriate only for Developers.
  
== Pseudo-Installing for Development ==
+
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.
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 kext manually by running
+
You can load the kexts manually by running
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 238: Line 336:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
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.
+
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:
 
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:
Line 248: Line 346:
  
 
cd ~/Developer
 
cd ~/Developer
sudo cp -r zfs/module/zfs/zfs.kext /tmp/o3x/  
+
sudo cp -R zfs/module/zfs/zfs.kext /tmp/o3x/  
sudo cp -r spl/module/spl/spl.kext /tmp/o3x/
+
sudo cp -R spl/module/spl/spl.kext /tmp/o3x/
  
 
cd /tmp/o3x
 
cd /tmp/o3x
Line 260: Line 358:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
cd ~/Developer/zfs
+
~/Developer/zfs/cmd.sh zfs
sudo ./cmd.sh zfs status
+
</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>
 
</syntaxhighlight>

Latest revision as of 07:41, 20 August 2020

Installing the official release[edit]

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 uninstalling a release version.

Installing from source[edit]

Initial installation from source[edit]

New-port: Currently recommended ./configure line is:

./configure CPPFLAGS="-I/usr/local/opt/gettext/include -I/usr/local/opt/openssl@1.1/include" LDFLAGS="-L/usr/local/opt/gettext/lib/ -L/usr/local/opt/openssl@1.1/lib" CFLAGS="-g -O0" --sysconfdir=/etc --localstatedir=/var --prefix=/usr/local --sbindir=/usr/local/bin


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) :

sudo nvram boot-args="-v keepsyms=1"

On OS X Yosemite (10.10):

sudo nvram boot-args="-v keepsyms=1 kext-dev-mode=1"


This will take effect the next time you reboot. The argument -v will make your boot screen verbose instead of just showing the Apple logo, the argument keepsyms=1 will make your panic reports more useful for us, and the argument kext-dev-mode=1 (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 debug=0x144 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:

sudo nvram "recovery-boot-mode=unused"
sudo reboot recovery


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

csrutil disable

or

csrutil enable --without kext

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 --without fs, --without debug, --without dtrace, or --without nvram. If you specify all of them, that is equivalent to csrutil disable. The --without option takes a comma-delimited list or can be specified multiple times: --without kext,debug,dtrace is equivalent to --without kext --without debug --without dtrace).

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 uninstallation directions before proceeding.

Prerequisites:

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):

xcode-select --install

To install Homebrew:

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

If you already have Homebrew installed, you should

brew update && brew upgrade

Once Homebrew is installed or updated, you should check the output of

brew doctor

and address any issues it identifies that you know are not false positives.

If you have used brew before, you should also run

brew prune

Once your system is ready to brew, you should install the following:

brew install automake libtool gawk coreutils

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

mkdir -p ~/Developer ~/bin
chmod 700 ~/Developer ~/bin
chmod +a "group:everyone deny delete" ~/Developer ~/bin

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:

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

If you're on OS X Mountain Lion (10.8), you will want to run this instead:

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

Then update your environment by sourcing your profile.

source ~/.bash_profile

To acquire the sources and build ZFS, we can use the zfsadm script found here.

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

Now you can can build OpenZFS on OS X:

zfsadm

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.

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

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

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

Now check again.

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

Try running

zpool

to see if everything is installed and configured properly.

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

Running ZFS from the source build[edit]

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.

$ sudo bash# cd ~/Developer/zfs# ./load.shkernel[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 listNAME   SIZE  ALLOC   FREE  EXPANDSZ   FRAG    CAP  DEDUP  HEALTH  ALTROOT
BOOM  39.8G   207M  39.5G         -     1%     0%  1.00x  ONLINE  -
# ./cmd.sh zpool export BOOMUnmount successful for /Volumes/BOOM
# kextunload -b net.lundman.zfskernel[0]: ZFS: Unloaded module v1.3.1-230_gb9658da
# kextunload -b net.lundman.splkernel[0]: SPL: Released 524288 bytes from vmem_seg_arena
kernel[0]: SPL: Unloaded module. (os_mem_alloc: 0)

Upgrading a source install[edit]

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.

zpool list

For every pool listed, run

sudo zpool export $poolname

Alternatively, you can run:

sudo zpool export -a

which will try to export all pools for you.

Make sure they have exported successfully.

zpool status

It should say, "no pools available."

Get any zfsadm updates:

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/

Now you should be able to upgrade your ZFS installation.

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

Uninstalling a source install[edit]

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

Using without actually installing (development)[edit]

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

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.

~/Developer/zfs/cmd.sh zfs

Migrating old pools (from MacZFS or ZEVO)[edit]

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.

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

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