diff --git a/docs/Getting Started/RHEL and CentOS.rst b/docs/Getting Started/RHEL and CentOS.rst index a3bcc7b..80d50f9 100644 --- a/docs/Getting Started/RHEL and CentOS.rst +++ b/docs/Getting Started/RHEL and CentOS.rst @@ -1,53 +1,38 @@ RHEL and CentOS =============== -`kABI-tracking -kmod `__ -or -`DKMS `__ -style packages are provided for RHEL / CentOS based distributions from -the official zfsonlinux.org repository. These packages track the -official ZFS on Linux tags and are updated as new versions are released. -Packages are available for the following configurations: +`DKMS`_ or `kABI-tracking kmod`_ style packages are provided for RHEL and +CentOS based distributions from the OpenZFS repository. These packages are +updated as new versions are released. Only the current repository for each +major release is updated with new packages. Packages are available for the +following configurations: -| **EL Releases:** 6.x, 7.x, 8.x +| **EL Releases:** 6, 7.9, 8.2 | **Architectures:** x86_64 -To simplify installation a zfs-release package is provided which -includes a zfs.repo configuration file and the ZFS on Linux public -signing key. All official ZFS on Linux packages are signed using this -key, and by default yum will verify a package's signature before -allowing it be to installed. Users are strongly encouraged to verify the -authenticity of the ZFS on Linux public key using the fingerprint listed -here. +To simplify installation a *zfs-release* package is provided which includes +a zfs.repo configuration file and public signing key. All official OpenZFS +packages are signed using this key, and by default yum or dnf will verify a +package's signature before allowing it be to installed. Users are strongly +encouraged to verify the authenticity of the ZFS on Linux public key using +the fingerprint listed here. | **Location:** /etc/pki/rpm-gpg/RPM-GPG-KEY-zfsonlinux | **EL6 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el6.noarch.rpm `__ -| **EL7.5 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el7_5.noarch.rpm `__ -| **EL7.6 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el7_6.noarch.rpm `__ -| **EL7.7 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el7_7.noarch.rpm `__ -| **EL7.8 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el7_8.noarch.rpm `__ + `http://download.zfsonlinux.org/epel/zfs-release.el6.noarch.rpm `__ (zfs-0.8.x) | **EL7.9 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el7_9.noarch.rpm `__ -| **EL8.0 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el8_0.noarch.rpm `__ -| **EL8.1 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el8_1.noarch.rpm `__ + `http://download.zfsonlinux.org/epel/zfs-release.el7_9.noarch.rpm `__ (zfs-0.8.x) | **EL8.2 Package:** - `http://download.zfsonlinux.org/epel/zfs-release.el8_2.noarch.rpm `__ -| **Note:** Starting with EL7.7 **zfs-0.8** will become the default, - EL7.6 and older will continue to track the **zfs-0.7** point releases. + `http://download.zfsonlinux.org/epel/zfs-release.el8_2.noarch.rpm `__ (zfs-0.8.x) +| **Archived Repositories:** `el7_5`_, `el7_6`_, `el7_7`_, `el7_8`_, `el8_0`_, `el8_1`_ | **Download from:** `pgp.mit.edu `__ | **Fingerprint:** C93A FFFD 9F3F 7B03 C310 CEB6 A9D5 A1C0 F14A B620 -:: +For RHEL/CentOS versions 6 and 7 run: + +.. code:: sh $ sudo yum install http://download.zfsonlinux.org/epel/zfs-release..noarch.rpm $ gpg --quiet --with-fingerprint /etc/pki/rpm-gpg/RPM-GPG-KEY-zfsonlinux @@ -55,119 +40,126 @@ here. Key fingerprint = C93A FFFD 9F3F 7B03 C310 CEB6 A9D5 A1C0 F14A B620 sub 2048R/99685629 2013-03-21 -After installing the zfs-release package and verifying the public key -users can opt to install ether the kABI-tracking kmod or DKMS style -packages. For most users the kABI-tracking kmod packages are recommended -in order to avoid needing to rebuild ZFS for every kernel update. DKMS -packages are recommended for users running a non-distribution kernel or -for users who wish to apply local customizations to ZFS on Linux. +And for RHEL/CentOS 8 and newer: -kABI-tracking kmod ------------------- +.. code:: sh -By default the zfs-release package is configured to install DKMS style -packages so they will work with a wide range of kernels. In order to -install the kABI-tracking kmods the default repository in the -*/etc/yum.repos.d/zfs.repo* file must be switch from *zfs* to -*zfs-kmod*. Keep in mind that the kABI-tracking kmods are only verified -to work with the distribution provided kernel. + $ sudo dnf install http://download.zfsonlinux.org/epel/zfs-release..noarch.rpm + $ gpg --quiet --with-fingerprint /etc/pki/rpm-gpg/RPM-GPG-KEY-zfsonlinux + pub 2048R/F14AB620 2013-03-21 ZFS on Linux + Key fingerprint = C93A FFFD 9F3F 7B03 C310 CEB6 A9D5 A1C0 F14A B620 + sub 2048R/99685629 2013-03-21 -.. code:: diff - - # /etc/yum.repos.d/zfs.repo - [zfs] - name=ZFS on Linux for EL 7 - dkms - baseurl=http://download.zfsonlinux.org/epel/7/$basearch/ - -enabled=1 - +enabled=0 - metadata_expire=7d - gpgcheck=1 - gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-zfsonlinux - @@ -9,7 +9,7 @@ - [zfs-kmod] - name=ZFS on Linux for EL 7 - kmod - baseurl=http://download.zfsonlinux.org/epel/7/kmod/$basearch/ - -enabled=0 - +enabled=1 - metadata_expire=7d - gpgcheck=1 - gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-zfsonlinux - -The ZFS on Linux packages can now be installed using yum. - -:: - - $ sudo yum install zfs +After installing the *zfs-release* package and verifying the public key +users can opt to install ether the DKMS or kABI-tracking kmod style packages. +DKMS packages are recommended for users running a non-distribution kernel or +for users who wish to apply local customizations to OpenZFS. For most users +the kABI-tracking kmod packages are recommended in order to avoid needing to +rebuild OpenZFS for every kernel update. DKMS ---- -To install DKMS style packages issue the following yum commands. First -add the `EPEL repository `__ which -provides DKMS by installing the *epel-release* package, then the -*kernel-devel* and *zfs* packages. Note that it is important to make -sure that the matching *kernel-devel* package is installed for the -running kernel since DKMS requires it to build ZFS. +To install DKMS style packages issue the following commands. First add the +`EPEL repository`_ which provides DKMS by installing the *epel-release* +package, then the *kernel-devel* and *zfs* packages. Note that it is +important to make sure that the matching *kernel-devel* package is installed +for the running kernel since DKMS requires it to build OpenZFS. -:: +For RHEL/CentOS versions 6 and 7 run: + +.. code:: sh $ sudo yum install epel-release - $ sudo yum install "kernel-devel-uname-r == $(uname -r)" zfs + $ sudo yum install kernel-devel zfs -Important Notices ------------------ +And for RHEL/CentOS 8 and newer: -.. _rhelcentos-7x-kmod-package-upgrade: +.. code:: sh -RHEL/CentOS 7.x kmod package upgrade -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + $ sudo dnf install epel-release + $ sudo dnf install kernel-devel zfs -When updating to a new RHEL/CentOS 7.x release the existing kmod -packages will not work due to upstream kABI changes in the kernel. After -upgrading to 7.x users must uninstall ZFS and then reinstall it as -described in the `kABI-tracking -kmod `__ -section. Compatible kmod packages will be installed from the matching -CentOS 7.x repository. +.. note:: + When switching from DKMS to kABI-tracking kmods first uninstall the + existing DKMS packages. This should remove the kernel modules for all + installed kernels, then the kABI-tracking kmods can be installed as + described in the section below. -:: +kABI-tracking kmod +------------------ - $ sudo yum remove zfs zfs-kmod spl spl-kmod libzfs2 libnvpair1 libuutil1 libzpool2 zfs-release - $ sudo yum install http://download.zfsonlinux.org/epel/zfs-release.el7_6.noarch.rpm - $ sudo yum autoremove - $ sudo yum clean metadata - $ sudo yum install zfs +By default the *zfs-release* package is configured to install DKMS style +packages so they will work with a wide range of kernels. In order to +install the kABI-tracking kmods the default repository must be switched +from *zfs* to *zfs-kmod*. Keep in mind that the kABI-tracking kmods are +only verified to work with the distribution provided kernel. -Switching from DKMS to kABI-tracking kmod -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +For RHEL/CentOS versions 6 and 7 run: -When switching from DKMS to kABI-tracking kmods first uninstall the -existing DKMS packages. This should remove the kernel modules for all -installed kernels but in practice it's not always perfectly reliable. -Therefore, it's recommended that you manually remove any remaining ZFS -kernel modules as shown. At this point the kABI-tracking kmods can be -installed as described in the section above. +.. code:: sh -:: + $ sudo yum-config-manager --disable zfs + $ sudo yum-config-manager --enable zfs-kmod + $ sudo yum install zfs - $ sudo yum remove zfs zfs-kmod spl spl-kmod libzfs2 libnvpair1 libuutil1 libzpool2 zfs-release +And for RHEL/CentOS 8 and newer: - $ sudo find /lib/modules/ \( -name "splat.ko" -or -name "zcommon.ko" \ - -or -name "zpios.ko" -or -name "spl.ko" -or -name "zavl.ko" -or \ - -name "zfs.ko" -or -name "znvpair.ko" -or -name "zunicode.ko" \) \ - -exec /bin/rm {} \; +.. code:: sh + + $ sudo dnf config-manager --disable zfs + $ sudo dnf config-manager --enable zfs-kmod + $ sudo dnf install zfs + +By default the OpenZFS kernel modules are automatically loaded when a ZFS +pool is detected. If you would prefer to always load the modules at boot +time you must create an ``/etc/modules-load.d/zfs.conf`` file. + +.. code:: sh + + $ sudo sh -c "echo zfs >/etc/modules-load.d/zfs.conf" + +.. note:: + When updating to a new RHEL/CentOS minor release the existing kmod + packages may not work due to upstream kABI changes in the kernel. + After upgrading users must uninstall OpenZFS and then reinstall it + from the matching repository as described in this section. Testing Repositories -------------------- In addition to the primary *zfs* repository a *zfs-testing* repository is available. This repository, which is disabled by default, contains -the latest version of ZFS on Linux which is under active development. -These packages are made available in order to get feedback from users -regarding the functionality and stability of upcoming releases. These -packages **should not** be used on production systems. Packages from the -testing repository can be installed as follows. +the latest version of OpenZFS which is under active development. These +packages are made available in order to get feedback from users regarding +the functionality and stability of upcoming releases. These packages +**should not** be used on production systems. Packages from the testing +repository can be installed as follows. -:: +For RHEL/CentOS versions 6 and 7 run: - $ sudo yum --enablerepo=zfs-testing install kernel-devel zfs +.. code:: sh + + $ sudo yum-config-manager --enable zfs-testing + $ sudo yum install kernel-devel zfs + +And for RHEL/CentOS 8 and newer: + +.. code:: sh + + $ sudo dnf config-manager --enable zfs-testing + $ sudo dnf install kernel-devel zfs + +.. note:: + Use *zfs-testing* for DKMS packages and *zfs-testing-kmod* + kABI-tracking kmod packages. + +.. _kABI-tracking kmod: https://elrepoproject.blogspot.com/2016/02/kabi-tracking-kmod-packages.html +.. _DKMS: https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support +.. _el7_5: http://download.zfsonlinux.org/epel/zfs-release.el7_5.noarch.rpm +.. _el7_6: http://download.zfsonlinux.org/epel/zfs-release.el7_6.noarch.rpm +.. _el7_7: http://download.zfsonlinux.org/epel/zfs-release.el7_7.noarch.rpm +.. _el7_8: http://download.zfsonlinux.org/epel/zfs-release.el7_8.noarch.rpm +.. _el8_0: http://download.zfsonlinux.org/epel/zfs-release.el8_0.noarch.rpm +.. _el8_1: http://download.zfsonlinux.org/epel/zfs-release.el8_1.noarch.rpm +.. _EPEL repository: https://fedoraproject.org/wiki/EPEL