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 1: Line 1:
−
[[Category:About O3X]]
+
(Adapted from an [http://zerobsd.tumblr.com/post/62586498252/os-x-with-zfs article by ZeroBSD].)
−
[[Category:Getting and installing O3X]]
+
−
== Installing the official release ==
+
  
−
Download the most recent dmg from the [[Downloads]] page.
+
If you have any other implementation of ZFS installed, you must uninstall it and reboot before proceeding further.
  
−
Verify the checksums.
+
We'll need to fetch the latest source from the [https://github.com/zfs-osx repository on GitHub] and then compile it. For this, we'll need some prerequisites, like 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), and [http://brew.sh/ Homebrew] (or [http://www.macports.org/‎ MacPorts]).
−
 
+
−
$ 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===
+
−
 
+
−
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) :
+
−
<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:
 
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">
+
−
brew prune
+
−
</syntaxhighlight>
+
  
−
Once your system is ready to brew, you should install the following:
 
 
<syntaxhighlight lang="text">
 
<syntaxhighlight lang="text">
−
brew install automake libtool gawk coreutils
+
brew install automake libtool gawk
 
</syntaxhighlight>
 
</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.
+
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 31:
 
</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 37:
 
</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.
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 148: Line 43:
 
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:
+
From now on, if you do this, you can simply run zfsadm from Terminal, without the need to be in your home folder.
 +
 
 +
All set. Let's go cloning and building ZFS:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 156: Line 54:
 
</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.
+
It should take a couple of minutes, not more. Disregard the warnings you may notice on the screen during build, it should be fine.
  
−
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.
+
then everything worked out well. But before using it, there's still some housekeeping to be done. Let's install the binaries:
  
 
<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>
  
−
You can check to see if the kernel extensions loaded automatically with
+
Now load the kernel extensions.
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
kextstat | grep lundman
+
cd /System/Library/Extensions
 +
sudo kextload spl.kext
 +
sudo kextload -d spl.kext zfs.kext
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
You should see something similar to
+
You can always check if they are loaded with
 +
<syntaxhighlight lang="bash">
 +
sudo kextstat | grep lundman
 +
</syntaxhighlight>
  
 +
If you get something similar to
 
<syntaxhighlight lang="text">
 
<syntaxhighlight lang="text">
−
137    1 0xffffff803f61a800 0x20c      0x20c      net.lundman.kernel.dependencies (10.0.0)
+
0xffffff7f80b52000 0xc000 0xc000 net.lundman.spl (1.0.0) <7 5 4 3 1>
−
144    1 0xffffff7f82720000 0xd000    0xd000    net.lundman.spl (1.0.0) <137 7 5 4 3 1>
+
0xffffff800b070a00 0x180 0x180 net.lundman.kernel.dependencies (10.0.0)
−
145    0 0xffffff7f8272d000 0x202000  0x202000  net.lundman.zfs (1.0.0) <144 13 7 5 4 3 1>
+
0xffffff7f8129a000 0x1f3000 0x1f3000 net.lundman.zfs (1.0.0) <92 91 16 7 5 4 3 1>
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
If not, make sure kextd is aware of them.
 
  
−
<syntaxhighlight lang="bash">
+
Add /usr/local/sbin (where you should now find the commands zpool, zfs, zdb, etc.) to your PATH:
−
sudo touch /System/Library/Extensions
+
−
sudo killall -HUP kextd
+
−
</syntaxhighlight>
+
−
 
+
−
Now check again.
+
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
kextstat | grep lundman
+
echo 'export PATH=$PATH:/usr/local/sbin' >> ~/.bash_profile
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
If not, you can load the kexts manually.
+
and update your environment by sourcing your profile again.
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
cd /System/Library/Extensions
+
source ~/.bash_profile
−
sudo kextload spl.kext
+
−
sudo kextload -d spl.kext zfs.kext
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Try running
+
Now you can try running
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
zpool
+
sudo zpool
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
to see if everything is installed and configured properly.
+
to see if everything is installed and configured properly. You can go ahead and create your pools and play with them from now on.
  
−
You can go ahead and [[zpool#Creating_a_pool|create your pools]] at this point.
+
When you want to get the latest commits from 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="text">
 
zpool list
 
zpool list
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 247: Line 116:
 
For every pool listed, run
 
For every pool listed, run
  
−
<syntaxhighlight lang="bash">
+
<syntaxhighlight lang="text">
−
sudo zpool export $poolname
+
zpool export $POOLNAME
 
</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.
+
−
 
+
−
<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.
+
  
 +
Now you should be able to upgrade your ZFS installation safely.
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
cd ~/Developer
 
cd ~/Developer
Line 287: Line 135:
  
 
zfsadm
 
zfsadm
−
 
−
# Assuming the build completed successfully,
 
−
# unload the kexts.
 
−
 
−
zfsadm -u
 
−
 
−
# Now install the upgrade.
 
  
 
cd spl
 
cd spl
Line 301: Line 142:
 
cd zfs
 
cd zfs
 
sudo make install
 
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
 
cd /System/Library/Extensions
Line 322: Line 148:
 
</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]].
+
−
 
+
−
== 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>
+

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"