Editing Install

Jump to: navigation, search

Warning: You are not logged in.

Your IP address will be recorded in this page's edit history.
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision Your text
Line 8: Line 8:
  
 
  $ md5 OpenZFS_on_OS_X_*.dmg
 
  $ md5 OpenZFS_on_OS_X_*.dmg
−
  $ shasum OpenZFS_on_OS_X_*.dmg
+
  $ sha1sum OpenZFS_on_OS_X_*.dmg
−
  $ shasum -a 256 OpenZFS_on_OS_X_*.dmg
+
  $ openssl dgst -sha256 OpenZFS_on_OS_X_*.dmg
  
 
Open the .dmg file.
 
Open the .dmg file.
Line 18: Line 18:
  
 
Follow the prompts.
 
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]].
 
If you ever want to uninstall, follow the instructions for [[Uninstall#Uninstalling_a_release_version|uninstalling a release version]].
  
 
== Installing from source ==
 
== Installing from source ==
−
===Initial installation from source===
+
(Adapted from an [http://zerobsd.tumblr.com/post/62586498252/os-x-with-zfs article by ZeroBSD].)
  
−
New-port: Currently recommended ./configure line is:
+
If you have any other implementation of ZFS installed, you must uninstall it and reboot before proceeding further.
−
./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
+
  
 +
We'll need to fetch the latest source from the [https://github.com/openzfsonosx repository on GitHub] and then compile it.
  
−
Before doing anything else, please set your boot-args.
+
For this, we'll need some prerequisites:
−
 
+
−
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">
−
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+
ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
If you already have Homebrew installed, you should
+
Paste that at a Terminal prompt.
−
<syntaxhighlight lang="text">
+
−
brew update && brew upgrade
+
−
</syntaxhighlight>
+
  
−
Once Homebrew is installed or updated, you should check the output of  
+
Once Homebrew is installed, we need a couple of things first:
−
<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 prune
+
brew install automake libtool gawk
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Once your system is ready to brew, you should install the following:
+
Create two folders in your home directory.
−
<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 -p ~/Developer ~/bin
+
mkdir ~/Developer
−
chmod 700 ~/Developer ~/bin
+
mkdir ~/bin
−
chmod +a "group:everyone deny delete" ~/Developer ~/bin
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Now adjust your PATH variable, unless you know it's already set appropriately.
+
Add the ~/bin directory to your PATH.
−
 
+
−
If you're on OS X Mavericks or above (>= 10.9), run this:
+
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 131: Line 62:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
If you're on OS X Mountain Lion (10.8), you will want to run this instead:
+
and update your environment by sourcing your profile.
−
<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 142: Line 68:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
To acquire the sources and build ZFS, we can use the [[zfsadm]] script found [https://gist.github.com/ilovezfs/7713854#file-zfsadm here].
+
To acquire the sources and build ZFS, we'll need the [[zfsadm]] script found [https://gist.github.com/ilovezfs/7713854#file-zfsadm here].
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 148: Line 74:
 
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>
  
−
Now you can can build OpenZFS on OS X:
+
All set. Let's go cloning and building ZFS:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 156: Line 83:
 
</syntaxhighlight>
 
</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.
+
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. If you are a developer and wish not to install ZFS, but rather run it from the compile directory, skip ahead.
+
Before using ZFS, we need to actually install it.
  
 
<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 170: Line 97:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
kextstat | grep lundman
+
sudo kextstat | grep lundman
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 188: Line 115:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Now check again.
+
And check again.
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
kextstat | grep lundman
+
sudo kextstat | grep lundman
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 202: Line 129:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Try running
+
Now add /usr/local/sbin to your PATH. This is where you will find the command binaries (zpool, zfs, zdb, etc.).
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
zpool
+
echo 'export PATH=$PATH:/usr/local/sbin' >> ~/.bash_profile
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
to see if everything is installed and configured properly.
+
and update your environment by sourcing your profile again.
  
−
You can go ahead and [[zpool#Creating_a_pool|create your pools]] at this point.
+
<syntaxhighlight lang="bash">
 +
source ~/.bash_profile
 +
</syntaxhighlight>
  
−
===Running ZFS from the source build===
+
Try running
−
 
+
−
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="bash">
−
<syntaxhighlight lang="text" highlight="1,2,3,6,7,10,12,14">
+
sudo zpool
−
$ 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>
 
</syntaxhighlight>
  
−
===Upgrading a source install===
+
to see if everything is installed and configured properly.
 +
 
 +
You can go ahead and [[zpool#Creating_a_pool|create your pools]] at this point.
 +
 
 
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.
 
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.
  
Line 242: Line 156:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
zpool list
+
sudo zpool list
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 251: Line 165:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Alternatively, you can run:
+
in order to prevent a kernel panic when the kexts are unloaded.
−
<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">
−
zpool status
+
sudo zpool status
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
It should say, "no pools available."
 
It should say, "no pools available."
  
−
Get any [[zfsadm]] updates:
+
Now you should be able to upgrade your ZFS installation safely.
−
<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 289: Line 191:
  
 
# Assuming the build completed successfully,
 
# Assuming the build completed successfully,
−
# unload the kexts.
+
# unload the kexts. If you did not export all of
 +
# your pools this will panic:
  
 
zfsadm -u
 
zfsadm -u
Line 304: Line 207:
 
# And verify they reloaded automatically
 
# And verify they reloaded automatically
  
−
kextstat | grep lundman
+
sudo kextstat | grep lundman
  
 
# If not, make sure kextd is aware of them
 
# If not, make sure kextd is aware of them
  
−
sudo touch /Library/Extensions /System/Library/Extensions
+
sudo touch /System/Library/Extensions
 
sudo killall -HUP kextd
 
sudo killall -HUP kextd
  
 
# and check again
 
# and check again
  
−
kextstat | grep lundman
+
sudo kextstat | grep lundman
  
 
# if they they still have not loaded automatically
 
# if they they still have not loaded automatically
Line 322: Line 225:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
===Uninstalling a source install===
+
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 [[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 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
 +
 +
<syntaxhighlight lang="bash">
 +
cd /Volumes/osx.zfs*/64
 +
</syntaxhighlight>
 +
 +
* Run install_zfs.sh
 +
<syntaxhighlight lang="bash">
 +
sudo ./install_zfs.sh
 +
</syntaxhighlight>
 +
 +
If you ever want to uninstall, follow the instructions for [[Uninstall#Uninstalling_a_development_build_DMG|uninstalling a development build dmg]].
  
 
== Using without actually installing (development) ==
 
== Using without actually installing (development) ==
Line 336: Line 263:
 
</syntaxhighlight>
 
</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.
+
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:
 
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 346: Line 273:
  
 
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 358: Line 285:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
~/Developer/zfs/cmd.sh zfs
+
cd ~/Developer/zfs
 +
sudo ./cmd.sh zfs status
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Migrating old pools (from MacZFS or ZEVO) ==
+
== 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.
 
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.
Line 374: Line 302:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
zpool status
+
sudo zpool status
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 394: Line 322:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
zpool status
+
sudo zpool status
 
</syntaxhighlight>
 
</syntaxhighlight>
  

Please note that all contributions to OpenZFS on OS X may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see OpenZFS on OS X:Copyrights for details). Do not submit copyrighted work without permission!

Cancel | Editing help (opens in new window)
Retrieved from "https://openzfsonosx.org/wiki/Install"