OpenZFS on OS X - User contributions [en]

Documentation

2014-04-01T19:22:05Z

84.114.59.37:

[[Category:About O3X]]
[[Category:Getting and installing O3X]]

== Documentation ==

General OpenZFS usage can be found on the [http://open-zfs.org OpenZFS wiki]. But we do need to document some Apple OS X specific things.

=== Getting started ===

* [[zpool|Creating a pool]]

=== Integration ===

* [[Suppressing the annoying popup]]

* [[Autoimport|Automatically importing pools]]

=== Trouble Shooting ===

* [[DegradedPool|Degraded pool]]

* [[panic|Kernel panic]]

DegradedPool

2014-04-01T19:18:05Z

84.114.59.37:

In case you have a degraded pool due to corrupted data on one drive, zpool status will show something like this:

<syntaxhighlight lang="bash">sudo zpool status
pool: tank
id: 4167705491194610230
state: DEGRADED
status: One or more devices contains corrupted data.
action: The pool can be imported despite missing or damaged devices. The
fault tolerance of the pool may be compromised if imported.
see: http://zfsonlinux.org/msg/ZFS-8000-4J
config:

tank DEGRADED
fs DEGRADED
disk1s2 ONLINE
disk2s2 ONLINE
2735026605872377559 FAULTED corrupted data
disk4s2 ONLINE
</syntaxhighlight>

Now, look into DiskUtility and find the disk number of the disk which is missing. (In our case disk3).
If you are certain that the corrupted data was not due to a bad disk, (for example if just the labels were messed up), we would like to delete the partition table of that disk and afterwards format the drive.

If the disk is faulty, take a new disk and skip this step, going directly to the format.

<syntaxhighlight lang="bash">
sudo gpt destroy disk3
</syntaxhighlight>

Now, format in DiskUtility as one partition, using GUID partition table, as hfs+ and look up the new disk partition id in the lower part of the DiskUtility-window. (in our case disk3s2)
Replace the now missing drive in the pool with the newly formatted disk:

<syntaxhighlight lang="bash">
sudo zpool replace tank 2735026605872377559 /dev/disk3s2
</syntaxhighlight>

The number you see is the one which you saw above at the position of the faulted drive in '''sudo zpool status'''.

The system now starts resilvering the drive. This takes a long time. With '''sudo zpool status''' you can see the progress.

DegradedPool

2014-04-01T19:16:30Z

84.114.59.37:

In case you have a degraded pool due to corrupted data on one drive, zpool status will show something like this:

<syntaxhighlight lang="bash">sudo zpool status
pool: tank
id: 4167705491194610230
state: DEGRADED
status: One or more devices contains corrupted data.
action: The pool can be imported despite missing or damaged devices. The
fault tolerance of the pool may be compromised if imported.
see: http://zfsonlinux.org/msg/ZFS-8000-4J
config:

tank DEGRADED
fs DEGRADED
disk1s2 ONLINE
disk2s2 ONLINE
2735026605872377559 FAULTED corrupted data
disk4s2 ONLINE
</syntaxhighlight>

Now, look into DiskUtility and find the disk number of the disk which is missing. (In our case disk3).
If you are certain that the corrupted data was not due to a bad disk, (for example if just the labels were messed up), we would like to delete the partition table of that disk and afterwards format the drive.

If the disk is faulty, take a new disk and skip this step, going directly to the format.

<syntaxhighlight lang="bash">
sudo gpt destroy disk3
</syntaxhighlight>

Now, format in DiskUtility as one partition, using GUID partition table, as hfs+ and look up the new disk partition id in the lower part of the DiskUtility-window. (in our case disk3s2)
Replace the now missing drive in the pool with the newly formatted disk:

<syntaxhighlight lang="bash">
sudo zpool replace tank 2735026605872377559 /dev/disk3s2
</syntaxhighlight>

The number you see is the one which you saw above at the position of the faulted drive in <syntaxhighlight lang="bash">sudo zpool status</syntaxhighlight>.

The system now starts resilvering the drive. This takes a long time. With <syntaxhighlight lang="bash">sudo zpool status</syntaxhighlight> you can see the progress.

DegradedPool

2014-04-01T19:15:23Z

84.114.59.37: replace drive in degraded pool

In case you have a degraded pool due to corrupted data on one drive, zpool status will show something like this:

<syntaxhighlight lang="bash">sudo zpool status
pool: tank
id: 4167705491194610230
state: DEGRADED
status: One or more devices contains corrupted data.
action: The pool can be imported despite missing or damaged devices. The
fault tolerance of the pool may be compromised if imported.
see: http://zfsonlinux.org/msg/ZFS-8000-4J
config:

tank DEGRADED
fs DEGRADED
disk1s2 ONLINE
disk2s2 ONLINE
2735026605872377559 FAULTED corrupted data
disk4s2 ONLINE
</syntaxhighlight>

Now, look into DiskUtility and find the disk number of the disk which is missing. (In our case disk3).
If you are certain that the corrupted data was not due to a bad disk, (for example if just the labels were messed up), we would like to delete the partition table of that disk and afterwards format the drive.

If the disk is faulty, take a new disk and skip this step, going directly to the format.

<syntaxhighlight lang="bash">
sudo gpt destroy disk3
</syntaxhighlight>

Now, format in DiskUtility as one partition, using GUID as hfs+ and look up the new disk partition id in the lower part of the DiskUtility-window. (in our case disk3s2)
Replace the now missing drive in the pool with the newly formatted disk:

<syntaxhighlight lang="bash">
sudo zpool replace tank 2735026605872377559 /dev/disk3s2
</syntaxhighlight>

The number you see is the one which you saw above at the position of the faulted drive in <syntaxhighlight lang="bash">sudo zpool status</syntaxhighlight>.

The system now starts resilvering the drive. This takes a long time. With <syntaxhighlight lang="bash">sudo zpool status</syntaxhighlight> you can see the progress.

Documentation

2014-04-01T18:51:42Z

84.114.59.37:

Documentation

2014-04-01T18:50:34Z

84.114.59.37:

[[Category:About O3X]]
[[Category:Getting and installing O3X]]

== Documentation ==

General OpenZFS usage can be found on the [http://open-zfs.org OpenZFS wiki]. But we do need to document some Apple OS X specific things.

=== Getting started ===

* [[zpool|Creating a pool]]

=== Integration ===

* [[Suppressing the annoying popup]]

* [[Autoimport|Automatically importing pools]]

=== Trouble Shooting ===

* [[zpool|Degraded pool]]

=== Kernel panics ===

* [[panic|Kernel panic]]

Install

2014-03-28T21:52:38Z

84.114.59.37: adding a paragraph about importing pools when migrating ...

[[Category:About O3X]]
[[Category:Getting and installing O3X]]
== Installing the official release ==

Download the most recent dmg from the [[Downloads]] page.

Verify the checksums.

$ md5 OpenZFS_on_OS_X_*.dmg
$ sha1sum OpenZFS_on_OS_X_*.dmg
$ openssl dgst -sha256 OpenZFS_on_OS_X_*.dmg

Open the .dmg file.

Read ReadMe.rtf.

Start the installer by opening OpenZFS_on_OS_X_x.y.z.pkg.

Follow the prompts.

If you ever want to uninstall, follow the instructions for [[Uninstall#Uninstalling_a_release_version|uninstalling a release version]].

== Installing from source ==
(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.

We'll need to fetch the latest source from the [https://github.com/openzfsonosx repository on GitHub] and then compile it.

For this, we'll need some 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])

To install Homebrew:

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

Paste that at a Terminal prompt.

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

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

Create two folders in your home directory.

<syntaxhighlight lang="bash">
mkdir ~/Developer
mkdir ~/bin
</syntaxhighlight>

Add the ~/bin directory to your PATH.

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

and update your environment by sourcing your profile.

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

To acquire the sources and build ZFS, we'll need 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/
chmod +x ~/bin/zfsadm
</syntaxhighlight>

All set. Let's go cloning and building ZFS:

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

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.

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

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

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

And check again.

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

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>

Try running

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

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">
sudo zpool list
</syntaxhighlight>

For every pool listed, run

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

in order to prevent a kernel panic when the kexts are unloaded.

Make sure they have exported successfully.

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

It should say, "no pools available."

Now you should be able to upgrade your ZFS installation safely.

<syntaxhighlight lang="bash">
cd ~/Developer

cd spl
make clean
cd ..

cd zfs
make clean
cd ..

zfsadm

# Assuming the build completed successfully,
# unload the kexts. If you did not export all of
# your pools this will panic:

zfsadm -u

# Now install the upgrade.

cd spl
sudo make install
cd ..

cd zfs
sudo make install

# And verify they reloaded automatically

sudo kextstat | grep lundman

# If not, make sure kextd is aware of them

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

# and check again

sudo kextstat | grep lundman

# if they they still have not loaded automatically

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

If net.lundman.kernel.dependencies has been updated (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]].

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

<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">
cd ~/Developer/zfs
sudo ./cmd.sh zfs status
</syntaxhighlight>

== Migrating old Pools (from MacZFS or ZEVO) ==
When migrating to OpenZFS for MacOSX without exporting the pools, first with your old ZFS system, this is the fastest method to find out pool names and import the pools.

<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 using the zpool status command.

<syntaxhighlight lang="bash">
sudo 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 -f poolname (or guid)
</syntaxhighlight>

To access the information you saw during pool discovery, you will now need to use zpool status instead.

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