jacobpascual/openzfs-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update RHEL/CentOS install documentation

Browse Source 
Refresh the documentation to more clear and to account for changes
for made in the recent RHEL/CentOS releases.

- Replaced most ZFS on Linux references with OpenZFS.

- Condensed the list of repositories and made it clear which repos
  are updated with new packages and which had been archived.

- Added separate instructions for RHEL/CentOS 6,7 and for RHEL/CentOS
  8 and newer since the package manager was changes from yum to dnf.

- Recommend using `yum-config-manager` or `dnf config-manager` rather
  than manually modifing the zfs.repo file.

- Converted the important notices to "notes" and reworded them.  The
  exact commands in the documention were also for much older versions
  of ZFS and were removed entirely.  This should be less of an issue
  with more modern releases.

- Add a comment explaining the modules are automatically loaded
  when a pool is detected, but they can always be loaded at boot
  time by creating a /etc/modules-load.d/zfs.conf file.

Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
This commit is contained in:
Brian Behlendorf
2020-11-25 18:05:27 -08:00
committed by George Melikov
parent 2aa6fd156d
commit 1a774f7dd9
1 changed files with 113 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
docs/Getting Started/RHEL and CentOS.rst
View File

@@ -1,53 +1,38 @@
RHEL and CentOS
===============
`kABI-tracking
kmod <http://elrepoproject.blogspot.com/2016/02/kabi-tracking-kmod-packages.html>`__
or
`DKMS <https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support>`__
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 <http://download.zfsonlinux.org/epel/zfs-release.el6.noarch.rpm>`__
| **EL7.5 Package:**
`http://download.zfsonlinux.org/epel/zfs-release.el7_5.noarch.rpm <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 <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 <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.el7_8.noarch.rpm>`__
`http://download.zfsonlinux.org/epel/zfs-release.el6.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 <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 <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.el8_1.noarch.rpm>`__
`http://download.zfsonlinux.org/epel/zfs-release.el7_9.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 <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 <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 <http://pgp.mit.edu/pks/lookup?search=0xF14AB620&op=index&fingerprint=on>`__
| **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.<dist>.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.<dist>.noarch.rpm
$ gpg --quiet --with-fingerprint /etc/pki/rpm-gpg/RPM-GPG-KEY-zfsonlinux
pub 2048R/F14AB620 2013-03-21 ZFS on Linux <zfs@zfsonlinux.org>
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 <https://fedoraproject.org/wiki/EPEL>`__ 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 <https://github.com/zfsonlinux/zfs/wiki/RHEL-%26-CentOS/#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