Editing FAQ

[[Category:About O3X]]

Besides the questions covered below, you may find [[Documentation]] and [[OpenZFS on OS X]] helpful. Both articles contain a good deal of information about OpenZFS on OS X.

== General ==

===Q) What is OpenZFS on OS X?===
'''A)''' See the article entitled [[OpenZFS on OS X]].

===Q) What does O3X mean?===
'''A)''' O3X = O O O X = '''O'''penZFS '''o'''n '''O'''S '''X'''.

===Q) What version of ZFS do you use?===
'''A)''' OpenZFS. Pool version 5000. File system version 5. Pool version 5000 is pool version 28 plus support for feature flags. We support pool version 5000 and pool versions less than or equal to 28. We do not support the closed-source Oracle Solaris ZFS pool versions 29 and up.

===Q) Can I set up a test pool using files instead of disks?===
'''A)''' Yes. The example uses simple files, its also possible to use disk images.

  $ cd /tmp
  $ mkfile 10G aaa
  $ mkfile 10G bbb
  $ mkfile 10G ccc
  $ sudo zpool create tank raidz /tmp/aaa /tmp/bbb /tmp/ccc
  $

===Q) I compiled from source, how do I know that I am running what I compiled?===
'''A)''' There are a couple of sysctls that can be read to determine what commit was compiled into your custom kexts. Assuming you used zfsadm to build, or that you executed the autoconf, and configure steps before compiling the following works.

  $ sysctl -a | grep kext
      spl.kext_version: 1.5.2-2_g'''115aa2f'''
      zfs.kext_version: 1.5.2-33_g'''9ac66a7'''

  $ cd <path to source code>/zfs
  $ git log -n 1
      commit '''9ac66a7'''1e53636eec04f4718b0b3870a18f07840
         Merge: 3326995 890ef86
         Author: zadmin <zadmin@jerry.local>
         Date:   Thu Jun 16 17:19:24 2016 +1000

         Merge branch 'master' of https://github.com/openzfsonosx/zfs

  $ cd <path to source code>/spl
  $ git log -n 2
       commit f1ff660a2f1fa340d451c2afa5f726f9bd3e609d
       Author: Brendon Humphrey <brendon.humphrey@mac.com>
       Date:   Sat Jun 18 20:25:09 2016 -0700
       ...
       commit '''115aa2f'''05b6f843e0d39d4f6bf999602db120113
       Author: Jorgen Lundman <lundman@lundman.net>
       Date:   Thu May 12 09:48:31 2016 +0900
       ...

I have highlighted the relevant text to match. You can see that this machine is running the latest ZFS, and is one commit behind the latest SPL.

If you make a small local change to the code then this technique will not work. One workaround for that is to edit your file(s) and commit them in your repository clone, that way it will have a commit id.

== Best practices ==

===Q) Do I have to use mirrors or raidz? ===
'''A)''' Have to? No. Should you? Virtually always. ZFS will not be able to repair errors it finds unless you have redundancy at the vdev level.

===Q) Can I set copies=2 in lieu of using mirrors or raidz? ===
Setting copies=2 is a poor substitute for vdev-level redundancy. Two copies on a broken drive are worthless. That being said, yes, you can set copies=2. Do so at your own risk.

== Administration ==

===Q) How can I access the .zfs snapshot directories?===
'''A)''' You need to set snapdir visible and manually mount a snapshot.
<syntaxhighlight lang="bash">
$ sudo zfs set snapdir=visible tank/bob
$ sudo zfs mount tank/bob@yesterday
$ ls -l /tank/bob/.zfs/snapshot/yesterday/
</syntaxhighlight>
You can see existing snapshots via:
<syntaxhighlight lang="bash">
$ zfs list -t snapshot
</syntaxhighlight>

===Q) Is .zfs snapdir auto-mounting supported?===
'''A)''' No, not at this time. You must manually "zfs mount" snapshots manually to see them in the snapdir.

===Q) OK, I manually mounted my snapshot but still cannot see it in Finder. What gives?===
'''A)''' Currently mounted snapshots are only visible from Terminal, not from Finder.
<syntaxhighlight lang="bash">
$ ls -l /tank/bob/.zfs/snapshot/yesterday/
</syntaxhighlight>

===Q) Why does OSX server not allow the server storage to be on ZFS?===
'''A)''' OSX Server has been coded in such a way as to only allow the server storage area to be an HFS formatted drive. O3X offers a feature that causes ZFS datasets to identify themselves as HFS. This is sufficient for OSX server to allow storage on a ZFS filesystem. HFS mimic is enabled by setting the com.apple.mimic_hfs property on a per dataset basis.

In addition as of OSX Server 5.x it seems that the Application Store Caching server can only store its cache on HFS. This is a new behaviour. I just used an HFS formatted ZVOL to get around this. 

  sudo zfs create -o volblocksize=1m -s -V 250g tank/cachingzvol

== Interoperability ==

===Q) How do I create an O3X compatible pool on another OpenZFS platform? ===
'''A)''' Only enable feature flags supported by O3X, as discussed [https://openzfsonosx.org/wiki/Zpool#Feature_flags here].

===Q) Can I import my ZEVO pools?===
'''A)''' Yes. O3X can import pool version 28, which means it can import ZEVO pools.

===Q) Can I import my MacZFS pools?===
'''A)''' Yes. O3X can import pool version 8, which means it can import MacZFS pools.

===Q) Do HFS-only applications such as Photos, iCloud Drive and macOS Server work on ZFS?===
'''A)''' Sometimes. Apple codes some software to only work when stored on HFS. We can't change that. We have provided a property that causes ZFS filesystems to identify themselves as a HFS when enabled. We are unable to guarantee that the application will work 100% correctly as HFS may have specific behaviours that the application depends on, and ZFS may not behave identically.
   
    sudo zfs set com.apple.mimic_hfs=on <dataset>

===Q) Does Spotlight work? ===
'''A)''' Yes. Spotlight works on O3X 1.3.1+.

===Q) Can Time Machine backups be stored on ZFS? ===
'''A)''' Yes. It is possible to host a TimeMachine backup within a SparseImage on ZFS, or an HFS formatted ZVOL On ZFS.  See: https://openzfsonosx.org/wiki/Time_Machine_Backups

===Q) Updating crypto to 2.0 ===
'''A)''' If you go from 1.9.4 (or earlier) and use crypto, you will get "mount returns -1". This is due to missing
features userobjquota, groupobjquota and projectquotas. The pool will need "zpool upgrade" before you can mount it. 
Please remember this means you can not go back to 1.9.4, as with all pool upgrades.

===Q) Updating crypto to 2.0 from earlier 2.0-rc ===
'''A)''' There was a few early releases of 2.0-rc, where the MAC was calculated incorrectly, and you will see:
         rpool/crypt:<0x0>
However, issuing "zpool scrub" will clear this issue (as it re-computes the MAC).

===Q) Uninstalling on Big Sur and later ===
'''A)''' Unfortunately, macOS from BigSur has a tendency to "hold on" to kexts, and the best way to
         make sure the kext is not loaded:
         Boot into recovery mode
         Launch Terminal
         # kmutil trigger-panic-medic --volume-root /Volumes/<YourVolumeName> 
         As in "/Volumes/MacintoshHD" or similar.
         reboot normally. 
         trigger-panic-medic will remove all 3rd party kexts, so you need to "Approve" any kexts
         you want to keep, just make sure to skip zfs.kext.
         Clean up all files:
         # sudo rm -rf /Library/Extensions/zfs.kext /usr/local/zfs/

== Limitations ==

===Q) Can I use finder permissions aka ACLs? ===
'''A)''' Not yet. There is work to go in this area. See https://github.com/openzfsonosx/zfs/issues/275

===Q) Can I boot my computer off of O3X?===
'''A)''' Yes. See https://openzfsonosx.org/wiki/ZFS_on_Boot

===Q) So if I use O3X, that means I don't need to back up, right? ===
'''A)''' Wrong. Wrong. Wrong. 

===Q) Can TimeMachine backup the contents of a ZFS volume? ===
'''A)''' No. We believe that when "Issue 116" is resolved it may be supportable. At the present time TimeMachine excludes ZFS filesystems from the list of available backup targets.

===Q) How does auto-import work ? ===
'''A)''' Auto-import on boot is handled by Launchd, from the file '''/Library/LaunchDaemons/org.openzfsonosx.zpool-import-all.plist'''. Which executes the script
'''/usr/local/libexec/zfs/launchd.d/zpool-import-all.sh''' to import files. You can unload the plist, or if you want to temporarily stop auto-import, simply comment
out the line '''"${ZPOOL}" import -a -d /var/run/disk/by-id''' by placing a '''#''' in front of it.

On newer versions (tested on 2.1.0) the script calls '''/Library/LaunchDaemons/org.openzfsonosx.zpool-import.plist''' which runs the command to import it upon boot.  If you wish to take advantage of naming the physical drives by their path, which generally shouldn't change, edit this file and change '''<string>/var/run/disk/by-id</string>''' to '''<string>/var/run/disk/by-path</string>'''

===Q) I can't see my pools? ===
'''A)''' First make sure that '''diskutil list''' will show the disk(s) used in your pool. If not, you have a hardware and/or OsX problem to solve. Second step is running '''zpool import''' and possibly '''zpool import -d /dev''' to make ZFS inspect all disks on your system, looking for pools. The command will list any pools that it can find, and the state they are in, except for pools already imported (You can run '''zpool list''' to display the imported pools). After that, you would run '''zpool import poolname''' to import the pool, where ''poolname'' is replaced with the name of your pool. If you need further assistance, ask on the forum, irc, or, in the case of panics, create a ticket under the github repository.

===Q) Auto-import fails after Catalina? ===
'''A)''' System Preferences -> Security & Privacy -> Full Disk Access by allowing bash. (bash used by auto-import script, change to 'sh' for lingon.)