Move long code pieces to separate files
Formatting fixes separate files Signed-off-by: Maurice Zhou <ja@apvc.uk>
This commit is contained in:
Maurice Zhou
committed by
Richard Laager
Richard Laager
parent
578f2901a7
commit
ff20f0b5d7
@@ -3,298 +3,83 @@
|
||||
Arch Linux
|
||||
============
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
Contents
|
||||
--------
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
*
|
||||
|
||||
Support
|
||||
-------
|
||||
|
||||
If you need help, reach out to the community using the :ref:`mailing_lists` or IRC at
|
||||
Reach out to the community using the :ref:`mailing_lists` or IRC at
|
||||
`#zfsonlinux <irc://irc.freenode.net/#zfsonlinux>`__ on `freenode
|
||||
<https://freenode.net/>`__. If you have a bug report or feature request
|
||||
<https://freenode.net/>`__.
|
||||
|
||||
If you have a bug report or feature request
|
||||
related to this HOWTO, please `file a new issue and mention @ne9z
|
||||
<https://github.com/openzfs/openzfs-docs/issues/new?body=@ne9z,%20I%20have%20the%20following%20issue%20with%20the%20Arch%20Linux%20ZFS%20HOWTO:>`__.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Due to license incompatibility,
|
||||
ZFS support is provided by out-of-tree kernel modules.
|
||||
ZFS is not available in Arch Linux official repo.
|
||||
|
||||
ZFS kernel modules can be installed with:
|
||||
|
||||
- ``zfs-linux*``, provides prebuilt ZFS kernel modules
|
||||
- ``zfs-dkms``, provides Dynamic Kernel Module Service support
|
||||
|
||||
zfs-linux*
|
||||
~~~~~~~~~~
|
||||
``zfs-linux*`` packages are the most
|
||||
risk-free way to obtain ZFS support.
|
||||
|
||||
Prebuilt modules are kernel-specific, i.e.,
|
||||
module built for 5.11.1 is incompatible
|
||||
with 5.11.2. For this reason, ``zfs-linux*``
|
||||
depends on a particular kernel version.
|
||||
Example: if linux-5.11.2 is available, but
|
||||
``zfs-linux-5.11.2`` is not available, you can not
|
||||
upgrade to linux-5.11.2 until ``zfs-linux-5.11.2``
|
||||
came out.
|
||||
|
||||
``zfs-linux*`` is recommended for users who are using stock kernels
|
||||
from official Arch Linux repo and can accept kernel update delays for
|
||||
up to a few days.
|
||||
|
||||
zfs-dkms
|
||||
~~~~~~~~
|
||||
``zfs-dkms`` package is the more versatile choice.
|
||||
After installation, Dynamic Kernel Module Support
|
||||
will automatically build ZFS kernel modules for installed
|
||||
kernels and does not interfere with kernel updates.
|
||||
|
||||
However, there are several disadvantages:
|
||||
|
||||
- somewhat slow to build
|
||||
- little warning when DKMS build fails
|
||||
- does not check kernel compatibility, manual checks required
|
||||
|
||||
``zfs-dkms`` is required for users who are using custom kernels or
|
||||
do not accept delays for kernel updates. This package is also required for derivative
|
||||
distros such as `Artix Linux <https://artixlinux.org>`__.
|
||||
ZFS support is provided by third-party `archzfs repo <https://github.com/archzfs/archzfs>`__.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
If you want to use ZFS as your root filesystem, see the `Root on ZFS`_
|
||||
links below instead.
|
||||
Note: this is for installing ZFS on an existing Arch
|
||||
Linux installation. To use ZFS as root file system,
|
||||
see below.
|
||||
|
||||
archzfs repo
|
||||
~~~~~~~~~~~~
|
||||
#. `Add archzfs repo to pacman <0-archzfs-repo.html>`__.
|
||||
|
||||
ZFS packages are provided by the third-party
|
||||
`archzfs repository <https://github.com/archzfs/archzfs>`__.
|
||||
You can use it as follows.
|
||||
#. Install `zfs-linux* <1-zfs-linux.html>`__
|
||||
or `zfs-dkms <2-zfs-dkms.html>`__ depending on your needs.
|
||||
See the respective pages for details.
|
||||
|
||||
#. Import keys of archzfs repository::
|
||||
|
||||
curl -L https://archzfs.com/archzfs.gpg | pacman-key -a -
|
||||
curl -L https://git.io/JtQpl | xargs -i{} pacman-key --lsign-key {}
|
||||
curl -L https://git.io/JtQp4 > /etc/pacman.d/mirrorlist-archzfs
|
||||
|
||||
#. Add archzfs repository::
|
||||
|
||||
tee -a /etc/pacman.conf <<- 'EOF'
|
||||
|
||||
#[archzfs-testing]
|
||||
#Include = /etc/pacman.d/mirrorlist-archzfs
|
||||
|
||||
[archzfs]
|
||||
Include = /etc/pacman.d/mirrorlist-archzfs
|
||||
EOF
|
||||
|
||||
#. Update pacman database::
|
||||
|
||||
pacman -Sy
|
||||
|
||||
zfs-linux* package
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When using unmodified Arch Linux kernels,
|
||||
prebuilt ``zfs-linux*`` packages are available.
|
||||
You can also switch between ``zfs-linux*`` and ``zfs-dkms``
|
||||
packages later.
|
||||
|
||||
For other kernels or Arch-based distros, use zfs-dkms package.
|
||||
|
||||
#. Check kernel variant::
|
||||
|
||||
INST_LINVAR=$(sed 's|.*linux|linux|' /proc/cmdline | sed 's|.img||g' | awk '{ print $1 }')
|
||||
|
||||
#. Check compatible kernel version::
|
||||
|
||||
INST_LINVER=$(pacman -Si zfs-${INST_LINVAR} | grep 'Depends On' | sed "s|.*${INST_LINVAR}=||" | awk '{ print $1 }')
|
||||
|
||||
#. Install kernel. Download from archive if kernel is not available::
|
||||
|
||||
if [ ${INST_LINVER} == \
|
||||
$(pacman -Si ${INST_LINVAR} | grep Version | awk '{ print $3 }') ]; then
|
||||
pacman -S --noconfirm --needed ${INST_LINVAR}
|
||||
else
|
||||
pacman -U --noconfirm --needed \
|
||||
https://archive.archlinux.org/packages/l/${INST_LINVAR}/${INST_LINVAR}-${INST_LINVER}-x86_64.pkg.tar.zst
|
||||
fi
|
||||
|
||||
#. Install zfs-linux*::
|
||||
|
||||
pacman -Sy zfs-${INST_LINVAR}
|
||||
|
||||
#. Ignore kernel updates::
|
||||
|
||||
sed -i 's/#IgnorePkg/IgnorePkg/' /etc/pacman.conf
|
||||
sed -i "/^IgnorePkg/ s/$/ ${INST_LINVAR} ${INST_LINVAR}-headers zfs-${INST_LINVAR} zfs-utils/" /etc/pacman.conf
|
||||
|
||||
#. To update kernel, run::
|
||||
|
||||
INST_LINVAR=$(sed 's|.*linux|linux|' /proc/cmdline | sed 's|.img||g' | awk '{ print $1 }')
|
||||
pacman -Sy --needed --noconfirm ${INST_LINVAR} ${INST_LINVAR}-headers zfs-${INST_LINVAR} zfs-utils
|
||||
|
||||
zfs-dkms package
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
#. Check kernel variant::
|
||||
|
||||
INST_LINVAR=$(sed 's|.*linux|linux|' /proc/cmdline | sed 's|.img||g' | awk '{ print $1 }')
|
||||
|
||||
#. Check kernel version::
|
||||
|
||||
INST_LINVER=$(pacman -Qi ${INST_LINVAR} | grep Version | awk '{ print $3 }')
|
||||
|
||||
If you are updating kernel, use the following command::
|
||||
|
||||
INST_LINVER=$(pacman -Syi ${INST_LINVAR} | grep Version | awk '{ print $3 }')
|
||||
|
||||
#. Install kernel headers::
|
||||
|
||||
pacman -U \
|
||||
https://archive.archlinux.org/packages/l/${INST_LINVAR}-headers/${INST_LINVAR}-headers-${INST_LINVER}-x86_64.pkg.tar.zst
|
||||
|
||||
#. Install zfs-dkms::
|
||||
|
||||
pacman -Sy zfs-dkms
|
||||
|
||||
If you are updating kernel, use the following command::
|
||||
|
||||
pacman -Sy $INST_LINVAR $INST_LINVAR-headers zfs-dkms
|
||||
|
||||
If pacman output contains the following error message,
|
||||
then the kernel needs a `downgrade <#zfs-dkms-compatible-kernel>`__,
|
||||
or you can try ``zfs-dkms-git`` package::
|
||||
|
||||
(3/4) Install DKMS modules
|
||||
==> dkms install --no-depmod -m zfs -v 2.0.4 -k 5.12.0-rc5-1-git-00030-gd19cc4bfbff1
|
||||
configure: error:
|
||||
*** None of the expected "capability" interfaces were detected.
|
||||
*** This may be because your kernel version is newer than what is
|
||||
*** supported, or you are using a patched custom kernel with
|
||||
*** incompatible modifications.
|
||||
***
|
||||
*** ZFS Version: zfs-2.0.4-1
|
||||
*** Compatible Kernels: 3.10 - 5.11
|
||||
|
||||
#. Ignore kernel package from updates::
|
||||
|
||||
sed -i 's/#IgnorePkg/IgnorePkg/' /etc/pacman.conf
|
||||
sed -i "/^IgnorePkg/ s/$/ ${INST_LINVAR} ${INST_LINVAR}-headers/" /etc/pacman.conf
|
||||
|
||||
To update kernel, go throught the above procedure
|
||||
again.
|
||||
|
||||
zfs-dkms compatible kernel
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If the installed kernel is not
|
||||
compatible with ZFS, a kernel downgrade
|
||||
is needed.
|
||||
|
||||
#. Choose kernel variant. Available variants are:
|
||||
|
||||
* linux
|
||||
* linux-lts
|
||||
* linux-zen
|
||||
* linux-hardened
|
||||
|
||||
::
|
||||
|
||||
INST_LINVAR=linux
|
||||
|
||||
#. Install kernels available when the package was built. Check build date::
|
||||
|
||||
DKMS_DATE=$(pacman -Syi zfs-dkms \
|
||||
| grep 'Build Date' \
|
||||
| sed 's/.*: //' \
|
||||
| LC_ALL=C xargs -i{} date -d {} -u +%Y/%m/%d)
|
||||
|
||||
#. Check kernel version::
|
||||
|
||||
INST_LINVER=$(curl https://archive.archlinux.org/repos/${DKMS_DATE}/core/os/x86_64/ \
|
||||
| grep \"${INST_LINVAR}-'[0-9]' \
|
||||
| grep -v sig \
|
||||
| sed "s|.*$INST_LINVAR-||" \
|
||||
| sed "s|-x86_64.*||")
|
||||
|
||||
#. Install compatible kernel and headers::
|
||||
|
||||
pacman -U \
|
||||
https://archive.archlinux.org/packages/l/${INST_LINVAR}/${INST_LINVAR}-${INST_LINVER}-x86_64.pkg.tar.zst \
|
||||
https://archive.archlinux.org/packages/l/${INST_LINVAR}-headers/${INST_LINVAR}-headers-${INST_LINVER}-x86_64.pkg.tar.zst
|
||||
|
||||
#. Install zfs-dkms::
|
||||
|
||||
pacman -Sy zfs-dkms
|
||||
|
||||
#. Hold kernel package from updates::
|
||||
|
||||
sed -i 's/#IgnorePkg/IgnorePkg/' /etc/pacman.conf
|
||||
sed -i "/^IgnorePkg/ s/$/ ${INST_LINVAR} ${INST_LINVAR}-headers/" /etc/pacman.conf
|
||||
|
||||
Kernel must be manually updated, see above.
|
||||
|
||||
Live Image
|
||||
Live image
|
||||
----------
|
||||
|
||||
Latest live image might contain a kernel incompatible with
|
||||
ZFS. Check the compatibility with the following procedure.
|
||||
|
||||
Alternatively, an unofficial Arch Linux live
|
||||
image with ZFS is available at
|
||||
`here <https://gitlab.com/m_zhou/archiso>`__.
|
||||
Use at your own discretion.
|
||||
|
||||
#. Choose a mirror::
|
||||
|
||||
https://archlinux.org/mirrorlist/all/
|
||||
https://gitea.artixlinux.org/packagesA/artix-mirrorlist/src/branch/master/trunk/mirrorlist
|
||||
|
||||
#. Check the build date of the
|
||||
latest Arch Linux live image::
|
||||
|
||||
https://mirrors.dotsrc.org/archlinux/iso/latest/
|
||||
https://mirrors.dotsrc.org/artix-linux/iso/
|
||||
# archlinux-2021.01.01-x86_64.iso
|
||||
|
||||
#. Check the kernel version of the live image::
|
||||
|
||||
https://archive.archlinux.org/repos/2021/01/01/core/os/x86_64
|
||||
https://archive.artixlinux.org/repos/2021/01/01/system/os/x86_64
|
||||
# linux-5.10.3.arch1-1-x86_64.pkg.tar.zst
|
||||
|
||||
#. Check latest zfs-dkms package version::
|
||||
|
||||
https://archzfs.com/archzfs/x86_64/
|
||||
# zfs-dkms-2.0.1-1-x86_64.pkg.tar.zst
|
||||
# zfs-linux-2.0.1_5.10.10.arch1.1-1-x86_64.pkg.tar.zst
|
||||
|
||||
#. Visit OpenZFS release page::
|
||||
|
||||
curl -L https://github.com/openzfs/zfs/raw/zfs-2.0.1/META \
|
||||
| grep Linux
|
||||
# Linux-Maximum: 5.10
|
||||
# Linux-Minimum: 3.10
|
||||
|
||||
- If compatible, download the latest live image::
|
||||
|
||||
https://mirrors.dotsrc.org/archlinux/iso/latest/archlinux-2021.01.01-x86_64.iso
|
||||
https://mirrors.dotsrc.org/artix-linux/iso/artix-base-openrc-20210101-x86_64.iso
|
||||
|
||||
- If not compatible, use an older live image and verify that it contains
|
||||
a supported kernel using the above method::
|
||||
|
||||
https://mirrors.dotsrc.org/archlinux/iso/
|
||||
https://iso.artixlinux.org/archived-isos.php
|
||||
Kernel package shipped with latest live image might
|
||||
not be compatible with ZFS, user should check kernel version
|
||||
following instructions `here <3-live.html>`__.
|
||||
|
||||
Root on ZFS
|
||||
-----------
|
||||
ZFS can be used as root file system for Arch Linux.
|
||||
An installation guide is available.
|
||||
|
||||
`Start here <Root%20on%20ZFS/0-overview.html>`__.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
*Root on ZFS
|
||||
Root on ZFS/*
|
||||
|
||||
Contribute
|
||||
----------
|
||||
#. Fork and clone `this repo <https://github.com/openzfs/openzfs-docs>`__.
|
||||
|
||||
#. Install the tools::
|
||||
|
||||
sudo pacman -S --needed python-pip make
|
||||
|
||||
pip3 install -r docs/requirements.txt
|
||||
|
||||
# Add ~/.local/bin to your $PATH, e.g. by adding this to ~/.bashrc:
|
||||
[ -d $HOME/.local/bin ] && export PATH=$HOME/.local/bin:$PATH
|
||||
|
||||
#. Make your changes.
|
||||
|
||||
#. Test::
|
||||
|
||||
cd docs
|
||||
make html
|
||||
sensible-browser _build/html/index.html
|
||||
|
||||
#. ``git commit --signoff`` to a branch, ``git push``, and create a pull
|
||||
request. Mention @rlaager.
|
||||
|
||||
Reference in New Issue
Block a user