From d6aa1285ce2e2fff7d9a11d5bd33b3666fe3f1dc Mon Sep 17 00:00:00 2001 From: Peter Jackson Date: Fri, 26 Jun 2020 15:50:50 -0400 Subject: [PATCH] peteonrails/add zfs tutorial (#1174) * Initial conversion of markdown guide * More formatting * Update zfs.rst * Acknowlege @zaffle and @rincebrain's work in the clear repo * Update zfs tutorial to reflect a DKMS build * Clean up zfs tutorial * For clarity * Start working on ZFS on Root outline * Update zfs.rst * Sentence casing * Update zfs.rst * Add ZFS to the tutorials list * Fix derp * Formatting and simplification of language * Remove ZFS on root for now * Update zfs.rst * Update zfs.rst * More formatting * Merge * Move links to end note format * More formatting and wording * Link to article on ZFS mount generator * Typo - Update source/tutorials/zfs.rst Co-authored-by: Brett T. Warden <4c0e8e88@tm.wgz.org> * Typo - Update source/tutorials/zfs.rst Co-authored-by: Brett T. Warden <4c0e8e88@tm.wgz.org> * Capitalize LTS - Update source/tutorials/zfs.rst Co-authored-by: Brett T. Warden <4c0e8e88@tm.wgz.org> * Capitalize LTS - Update source/tutorials/zfs.rst Co-authored-by: Brett T. Warden <4c0e8e88@tm.wgz.org> * Remove sudo from systemd 01-zfs.conf creation -- Update source/tutorials/zfs.rst Co-authored-by: Brett T. Warden <4c0e8e88@tm.wgz.org> * Add caution to Background section per PR feedback. * Remove -dev bundle installation -- not necessary * Symlink services into /etc/systemd. Add note about other services. * Remove sig_unenforce since DKMS does this for us * Add troubleshooting info to Caution section * Address more PR feedback -- Link ZFS on Linux repo * Revise wording for legal compliance and correct syntax. Signed-off-by: Michael Vincerra * Respond to reviewer feedback on wording; add sudo to commands as applicable. Signed-off-by: Michael Vincerra * Incorporate reviewer feedback on wording, organization, commands. Signed-off-by: Michael Vincerra * Clarify OpenZFS kernel modules must be loaded before mnounting OpenZFS. Signed-off-by: Michael Vincerra Co-authored-by: Brett T. Warden <4c0e8e88@tm.wgz.org> Co-authored-by: Michael Vincerra --- source/tutorials/index.rst | 3 +- source/tutorials/zfs.rst | 270 +++++++++++++++++++++++++++++++++++++ 2 files changed, 272 insertions(+), 1 deletion(-) create mode 100644 source/tutorials/zfs.rst diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst index cc226fc3..3d9ff446 100644 --- a/source/tutorials/index.rst +++ b/source/tutorials/index.rst @@ -53,6 +53,7 @@ sorted by difficulty level! Learn about :ref:`how we evaluate tutorials /extra/zfs` + + In addition, this installs the zfs userspace tools to: + + .. code-block:: console + + + /usr/local/ + |--+ bin/ + |--zvol_wait + |--zgenhostid + |--raidz_test + |--+ etc/ + |--+ zfs/ + |--* zed.d/ + |--+ zpool.d/ + |--zfs-functions + |--+ include/libzfs/ [contents omitted] + |--+ lib/ + |--+ libexec/ + |--+ zfs/ + |-- zpool.d/ + |-- zed.d + |--+ share/zfs/ [contents omitted] + |--+ sbin/ + |--fsck.zfs + |--zpool + |--zdb + |--zed + |--zfs + |--zhack + |--zinject + |--zpool + |--ztest + |--zstreamdump + |--+ src/ + |--+ zfs-0.8.4/ + |--+ spl-0.8.4/ + + +#. Load the new kernel module: + + .. code-block: bash + + sudo modprobe zfs + + +Set up systemd +============== + +You should now have these unit files available. + +.. code-block:: console + + zfs-env-bootfs.service + zfs-zed.service + zfs-import-cache.service + zfs-import-scan.service + zfs-mount.service + zfs-share.service + zfs-volume-wait.service + +OpenZFS requires you to explicitly install and enable the services you want. +If you want to use other ZFS service units, you could create symlinks for them, similar to the example below. + +To use ZFS automatic zpool import and filesystem mount services, link the systemd.unit files into :file:`/etc` and enable them. + +.. code-block:: bash + + sudo ln -s ./etc/systemd/system/zfs-import-cache.service /etc/systemd/system/ + sudo ln -s ./etc/systemd/system/zfs-mount.service /etc/systemd/system/ + + sudo systemctl enable zfs-import-cache + sudo systemctl enable zfs-import.target + + sudo systemctl enable zfs-mount + sudo systemctl enable zfs.target + + +Load the kernel module at boot +============================== + +OpenZFS kernel modules must be loaded before any OpenZFS filesystems are mounted. For convenience, load the kernel modules at boot. + +#. Systemd uses the `/etc/modules-load.d/` directory to load out-of-tree + kernel modules. Make sure that the directory exists: + + .. code-block:: bash + + sudo mkdir -p /etc/modules-load.d + +#. Create the configuration file: + + .. code-block:: bash + + echo "zfs" | sudo tee /etc/modules-load.d/01-zfs.conf + +#. Reboot your system. zfs.ko should be loaded automatically. + +.. CAUTION:: + + When the |CL| kernel is upgraded, DKMS will attempt to rebuild your OpenZFS module for the new kernel. + + - DKMS may not have rebuilt the module + - DKMS may not have auto-installed the module + - The new kernel might introduce breaking changes that prevent zfs + from compiling + +To fix this situation, you may have to recompile zfs.ko with the new kernel code. OpenZFS *might* not compile at all with the new kernel. + +.. CAUTION:: + + **Be sure you don't put anything on an OpenZFS pool that you would need + in order to rebuild kernel modules.** You must ensure the compatibility of OpenZFS with new Linux kernels when they are released. + +Troubleshooting +=============== + +If you suspect an issue with DKMS rebuilding your module, you can check two places for information. The dkms-new-kernel service will show status that may help in troubleshooting: + +.. code-block:: bash + + systemctl status dkms-new-kernel.service + +Also, the systemd journal may have important information: + +.. code-block:: bash + + journalctl -xe + +Next steps +********** +You are ready to create zpools and datasets! For more information on using ZFS, see: + +* `FreeBSD Handbook chapter on ZFS`_ +* `ZFS-on-Linux issue tracker`_ + +.. _FreeBSD Handbook chapter on ZFS: https://www.freebsd.org/doc/handbook/zfs.html +.. _ZFS-on-Linux issue tracker: https://github.com/openzfs/zfs/issues/10068 +.. _ZFS on Linux repository: https://github.com/openzfs/zfs +.. _OpenZFS* file system and volume manager: https://github.com/openzfs/zfs \ No newline at end of file