Skip to content
This repository was archived by the owner on Aug 7, 2025. It is now read-only.

Commit 66876a7

Browse files
AP-FoundationAP-Foundation
authored
Update zfs.rst (#1214)
* Update zfs.rst Update guide for OpenZFS 2.0.0 * Update zfs.rst Corrected a few typos and modified styling / organization. * Update zfs.rst Slight corrections after having tested this.
1 parent baf79c8 commit 66876a7

File tree

1 file changed

+55
-80
lines changed

1 file changed

+55
-80
lines changed

‎source/tutorials/zfs.rst‎

Lines changed: 55 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -39,78 +39,62 @@ Install the DKMS kernel
3939
Bundles
4040
=======
4141

42-
Before you install OpenZFS, install the bundles that contain the build dependencies.
42+
Before installing OpenZFS, install the bundles that contain the build dependencies.
4343

44-
.. code-block:: bash
44+
.. code-block:: console
4545
46-
sudo swupd bundle-add os-core-dev devpkg-openssl devpkg-util-linux
46+
sudo swupd bundle-add wget devpkg-openssl devpkg-util-linux
4747
4848
Install
4949
*******
5050

51-
Clone OpenZFS code
52-
==================
51+
Download OpenZFS release
52+
========================
5353

54+
In this section, we download release 2.0.0 directly from the `OpenZFS repository` (the latest available as of the latest revision of this page).
5455

55-
In this section, you download the source code directly from the `ZFS on Linux repository`_.
56+
Download release 2.0.0
5657

57-
.. note::
58+
.. code-block:: console
5859
59-
OpenZFS will not run from this location. We copy the source code into a DKMS directory in the following steps.
60-
61-
#. Create a directory. In this example, we use :file:`/opt/src/zfs`,
62-
but you can choose any workspace you like.
63-
64-
.. code-block:: bash
65-
66-
sudo mkdir -p /tmp/zfs/
67-
68-
#. Clone the repository.
69-
70-
.. code-block:: bash
71-
72-
git clone https://github.com/openzfs/zfs.git /tmp/zfs
73-
sudo cp -Rv /tmp/zfs /opt/src/zfs
74-
75-
Remember where you clone the git repository because you will need it
76-
when you upgrade ZFS. Do not delete the source location when you have completed this tutorial. You will need it later.
60+
cd /usr/src
61+
sudo wget https://github.com/openzfs/zfs/releases/download/zfs-2.0.0/zfs-2.0.0.tar.gz
62+
sudo tar -xvf zfs-2.0.0.tar.gz
7763
7864
Compile the module
7965
==================
8066

8167
We will build the module using DKMS. This will enable us to keep the module up to date as new kernels are released in the future.
8268

69+
The ZFS distribution provides a script to build a suitable dkms.conf file.
8370

84-
#. Check out the tagged version that you plan to use. As of the time of this
85-
writing, the latest release tag is `0.8.4`:
86-
87-
.. code-block:: bash
88-
89-
cd /opt/src/zfs
90-
git checkout zfs-0.8.4
91-
92-
#. Copy the source code into `/usr/src/zfs-0.8.4`. This exposes the source
93-
code to DKMS. We will build the code from the new location:
94-
95-
.. code-block:: bash
96-
97-
sudo cp -Rv /opt/src/zfs /usr/src/zfs-0.8.4
98-
99-
#. The ZFS distribution provides a script to build a suitable dkms.conf file.
10071
Build dkms.conf and install it into the DKMS tree.
10172

102-
.. code-block:: bash
73+
.. code-block:: console
10374
104-
cd /usr/src/zfs-0.8.4
105-
sudo scripts/dkms.mkconf -n zfs -v 0.8.4 -f dkms.conf
106-
sudo dkms add -m zfs -v 0.8.4
107-
sudo dkms build -m zfs -v 0.8.4
108-
sudo dkms install -m zfs -v 0.8.4
75+
cd /usr/src/zfs-2.0.0
76+
sudo scripts/dkms.mkconf -n zfs -v 2.0.0 -f dkms.conf
77+
sudo dkms add -m zfs -v 2.0.0
78+
sudo dkms build -m zfs -v 2.0.0
79+
sudo dkms install -m zfs -v 2.0.0
80+
81+
Observe that this install the zfs kernel modules to:
10982

110-
#. Observe that this install the zfs kernel modules to:
11183
:file:`/usr/lib/modules/<kernel-name>/extra/zfs`
84+
85+
Compile userspace tools
86+
=======================
87+
88+
Here we compile and install the zfs userspace tools (e.g., zpool, zfs, etc.).
11289

113-
In addition, this installs the zfs userspace tools to:
90+
.. code-block:: console
91+
92+
cd /usr/src/zfs-2.0.0
93+
sudo ./configure
94+
sudo make
95+
sudo make install
96+
97+
The binaries are installed at the following directory. While not required, it's recommended to add :file:`/usr/local/sbin` to your path variable.
11498

11599
.. code-block:: console
116100
@@ -143,21 +127,14 @@ We will build the module using DKMS. This will enable us to keep the module up t
143127
|--ztest
144128
|--zstreamdump
145129
|--+ src/
146-
|--+ zfs-0.8.4/
147-
|--+ spl-0.8.4/
148-
149-
150-
#. Load the new kernel module:
151-
152-
.. code-block: bash
153-
154-
sudo modprobe zfs
130+
|--+ zfs-2.0.0/
131+
|--+ spl-2.0.0/
155132
156133
157134
Set up systemd
158135
==============
159136

160-
You should now have these unit files available.
137+
We now have these unit files available.
161138

162139
.. code-block:: console
163140
@@ -169,19 +146,16 @@ You should now have these unit files available.
169146
zfs-share.service
170147
zfs-volume-wait.service
171148
172-
OpenZFS requires you to explicitly install and enable the services you want.
173-
If you want to use other ZFS service units, you could create symlinks for them, similar to the example below.
174-
175-
To use ZFS automatic zpool import and filesystem mount services, link the systemd.unit files into :file:`/etc` and enable them.
149+
150+
OpenZFS requires that we explicitly install and enable the services desired.
176151

177-
.. code-block:: bash
152+
To use ZFS automatic zpool import and filesystem mount services, enable them.
178153

179-
sudo ln -s ./etc/systemd/system/zfs-import-cache.service /etc/systemd/system/
180-
sudo ln -s ./etc/systemd/system/zfs-mount.service /etc/systemd/system/
154+
.. code-block:: console
181155
182156
sudo systemctl enable zfs-import-cache
183157
sudo systemctl enable zfs-import.target
184-
158+
sudo systemctl enable zfs-import-scan
185159
sudo systemctl enable zfs-mount
186160
sudo systemctl enable zfs.target
187161
@@ -191,60 +165,61 @@ Load the kernel module at boot
191165

192166
OpenZFS kernel modules must be loaded before any OpenZFS filesystems are mounted. For convenience, load the kernel modules at boot.
193167

194-
#. Systemd uses the `/etc/modules-load.d/` directory to load out-of-tree
195-
kernel modules. Make sure that the directory exists:
168+
Systemd uses the `/etc/modules-load.d/` directory to load out-of-tree kernel modules. Make sure that the directory exists:
196169

197170
.. code-block:: bash
198171
199172
sudo mkdir -p /etc/modules-load.d
200173
201-
#. Create the configuration file:
174+
Create the configuration file:
202175

203176
.. code-block:: bash
204177
205178
echo "zfs" | sudo tee /etc/modules-load.d/01-zfs.conf
206179
207-
#. Reboot your system. zfs.ko should be loaded automatically.
180+
Reboot your system. zfs.ko should be loaded automatically (the module should appear in the outout of command :file:`lsmod`).
208181

209182
.. CAUTION::
210183

211-
When the |CL| kernel is upgraded, DKMS will attempt to rebuild your OpenZFS module for the new kernel.
184+
When the |CL| kernel is upgraded, DKMS will attempt to rebuild the OpenZFS module for the new kernel.
212185

213186
- DKMS may not have rebuilt the module
214187
- DKMS may not have auto-installed the module
215188
- The new kernel might introduce breaking changes that prevent zfs
216189
from compiling
217190

218-
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.
191+
To fix this situation, recompile zfs.ko with the new kernel code. OpenZFS *might* not compile at all with the new kernel.
219192

220193
.. CAUTION::
221194

222-
**Be sure you don't put anything on an OpenZFS pool that you would need
223-
in order to rebuild kernel modules.** You must ensure the compatibility of OpenZFS with new Linux kernels when they are released.
195+
**Be sure not to put anything on an OpenZFS pool that will be needed to rebuild kernel modules.** Ensure compatibility of OpenZFS with new Linux kernels when released.
224196

225197
Troubleshooting
226198
===============
227199

228200
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:
229201

230-
.. code-block:: bash
202+
.. code-block:: console
231203
232204
systemctl status dkms-new-kernel.service
233205
234-
Also, the systemd journal may have important information:
206+
The systemd journal may also have important information:
235207

236-
.. code-block:: bash
208+
.. code-block:: console
237209
238210
journalctl -xe
239211
212+
.. CAUTION::
213+
As of OpenZFS 2.0.0, the included file :file:`script/dkms.mkconf` contains a minor incompability -- it calls the command :file:`lsb_release`, which is not available on Clear Linux by default. It is trivial to edit :file:`dkms.mkconf` and remove the singular reference to :file:`lsb_release` without any ill effects, and then execute the :file:`dkms` commands above. However, keeping the file as provided is perfectly fine, but **will result in :file:`dkms` warnings**.
214+
240215
Next steps
241216
**********
242-
You are ready to create zpools and datasets! For more information on using ZFS, see:
217+
You're now ready to create zpools and datasets! For more information on using ZFS, see:
243218

244219
* `FreeBSD Handbook chapter on ZFS`_
245220
* `ZFS-on-Linux issue tracker`_
246221

247222
.. _FreeBSD Handbook chapter on ZFS: https://www.freebsd.org/doc/handbook/zfs.html
248223
.. _ZFS-on-Linux issue tracker: https://github.com/openzfs/zfs/issues/10068
249224
.. _ZFS on Linux repository: https://github.com/openzfs/zfs
250-
.. _OpenZFS* file system and volume manager: https://github.com/openzfs/zfs
225+
.. _OpenZFS* file system and volume manager: https://github.com/openzfs/zfs

0 commit comments

Comments
 (0)