mirror of
https://github.com/zrepl/zrepl.git
synced 2024-11-24 09:24:09 +01:00
docs: add FreeBSD jail tutorial + reorg 'instalation' section
This commit is contained in:
John Ramsden
Christian Schwarz
parent
6f441c55dc
commit
c5a8f6635f
@ -1,138 +1,19 @@
|
||||
.. _binary releases: https://github.com/zrepl/zrepl/releases
|
||||
|
||||
.. _installation:
|
||||
.. _installation_toc:
|
||||
|
||||
************
|
||||
Installation
|
||||
============
|
||||
************
|
||||
|
||||
.. TIP::
|
||||
|
||||
Note: check out the :ref:`tutorial` if you want a first impression of zrepl.
|
||||
|
||||
User Privileges
|
||||
---------------
|
||||
.. toctree::
|
||||
|
||||
It is possible to run zrepl as an unprivileged user in combination with
|
||||
`ZFS delegation <https://www.freebsd.org/doc/handbook/zfs-zfs-allow.html>`_.
|
||||
Also, there is the possibility to run it in a jail on FreeBSD by delegating a dataset to the jail.
|
||||
However, until we get around documenting those setups, you will have to run zrepl as root or experiment yourself :)
|
||||
|
||||
Packages
|
||||
--------
|
||||
|
||||
zrepl source releases are signed & tagged by the author in the git repository.
|
||||
Your OS vendor may provide binary packages of zrepl through the package manager.
|
||||
Additionally, `binary releases`_ are provided on GitHub.
|
||||
The following list may be incomplete, feel free to submit a PR with an update:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - OS / Distro
|
||||
- Install Command
|
||||
- Link
|
||||
* - FreeBSD
|
||||
- ``pkg install zrepl``
|
||||
- `<https://www.freshports.org/sysutils/zrepl/>`_
|
||||
* - MacOS
|
||||
- ``brew install zrepl``
|
||||
- Available on `homebrew <https://brew.sh>`_
|
||||
* - Arch Linux
|
||||
- ``yay install zrepl``
|
||||
- Available on `AUR <https://aur.archlinux.org/packages/zrepl>`_
|
||||
* - Fedora
|
||||
- ``dnf install zrepl``
|
||||
- Available on `COPR <https://copr.fedorainfracloud.org/coprs/poettlerric/zrepl/>`_
|
||||
* - CentOS/RHEL
|
||||
- ``yum install zrepl``
|
||||
- Available on `COPR <https://copr.fedorainfracloud.org/coprs/poettlerric/zrepl/>`_
|
||||
* - Debian + Ubuntu
|
||||
- ``apt install zrepl``
|
||||
- APT repository config :ref:`see below <installation-apt-repos>`
|
||||
* - OmniOS
|
||||
- ``pkg install zrepl``
|
||||
- Available since `r151030 <https://pkg.omniosce.org/r151030/extra/en/search.shtml?token=zrepl&action=Search>`_
|
||||
* - Void Linux
|
||||
- ``xbps-install zrepl``
|
||||
- Available since `a88a2a4 <https://github.com/void-linux/void-packages/commit/a88a2a4d7bf56072dadf61ab56b8424e39155890>`_
|
||||
* - Others
|
||||
-
|
||||
- Use `binary releases`_ or build from source.
|
||||
|
||||
.. _installation-apt-repos:
|
||||
|
||||
Debian / Ubuntu APT repositories
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We maintain APT repositories for Debian, Ubuntu and derivatives.
|
||||
The fingerprint of the signing key is ``E101 418F D3D6 FBCB 9D65 A62D 7086 99FC 5F2E BF16``.
|
||||
It is available at `<https://zrepl.cschwarz.com/apt/apt-key.asc>`_ .
|
||||
Please open an issue `in the packaging repository <https://github.com/zrepl/debian-binary-packaging>`_ if you encounter any issues with the repository.
|
||||
|
||||
The following snippet configure the repository for your Debian or Ubuntu release:
|
||||
|
||||
::
|
||||
|
||||
apt update && apt install curl gnupg lsb-release; \
|
||||
ARCH="$(dpkg --print-architecture)"; \
|
||||
CODENAME="$(lsb_release -i -s | tr '[:upper:]' '[:lower:]') $(lsb_release -c -s | tr '[:upper:]' '[:lower:]')"; \
|
||||
echo "Using Distro and Codename: $CODENAME"; \
|
||||
(curl https://zrepl.cschwarz.com/apt/apt-key.asc | apt-key add -) && \
|
||||
(echo "deb [arch=$ARCH] https://zrepl.cschwarz.com/apt/$CODENAME main" > /etc/apt/sources.list.d/zrepl.list) && \
|
||||
apt update
|
||||
|
||||
|
||||
.. NOTE::
|
||||
|
||||
Until zrepl reaches 1.0, all APT repositories will be updated to the latest zrepl release immediately.
|
||||
This includes breaking changes between zrepl versions.
|
||||
Use ``apt-mark hold zrepl`` to prevent upgrades of zrepl.
|
||||
|
||||
Compile From Source
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Producing a release requires **Go 1.11** or newer and **Python 3** + **pip3** + ``docs/requirements.txt`` for the Sphinx documentation.
|
||||
A tutorial to install Go is available over at `golang.org <https://golang.org/doc/install>`_.
|
||||
Python and pip3 should probably be installed via your distro's package manager.
|
||||
|
||||
Alternatively, you can use the Docker build process:
|
||||
it is used to produce the official zrepl `binary releases`_
|
||||
and serves as a reference for build dependencies and procedure:
|
||||
|
||||
::
|
||||
|
||||
git clone https://github.com/zrepl/zrepl.git && \
|
||||
cd zrepl && \
|
||||
sudo docker build -t zrepl_build -f build.Dockerfile . && \
|
||||
sudo docker run -it --rm \
|
||||
-v "${PWD}:/src" \
|
||||
--user "$(id -u):$(id -g)" \
|
||||
zrepl_build make release
|
||||
|
||||
Alternatively, you can install build dependencies on your local system and then build in your ``$GOPATH``:
|
||||
|
||||
::
|
||||
|
||||
mkdir -p "${GOPATH}/src/github.com/zrepl/zrepl"
|
||||
git clone https://github.com/zrepl/zrepl.git "${GOPATH}/src/github.com/zrepl/zrepl"
|
||||
cd "${GOPATH}/src/github.com/zrepl/zrepl"
|
||||
python3 -m venv3
|
||||
source venv3/bin/activate
|
||||
./lazy.sh devsetup
|
||||
make release
|
||||
|
||||
The Python venv is used for the documentation build dependencies.
|
||||
If you just want to build the zrepl binary, leave it out and use `./lazy.sh godep` instead.
|
||||
Either way, all build results are located in the ``artifacts/`` directory.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
It is your job to install the appropriate binary in the zrepl users's ``$PATH``, e.g. ``/usr/local/bin/zrepl``.
|
||||
Otherwise, the examples in the :ref:`tutorial` may need to be adjusted.
|
||||
|
||||
What next?
|
||||
----------
|
||||
|
||||
Read the :ref:`configuration chapter<configuration_toc>` and then continue with the :ref:`usage chapter<usage>`.
|
||||
|
||||
**Reminder**: If you want a quick introduction, please read the :ref:`tutorial`.
|
||||
installation/user-privileges
|
||||
installation/packages
|
||||
installation/apt-repos
|
||||
installation/compile-from-source
|
||||
installation/freebsd-jail-with-iocage
|
||||
installation/what-next
|
||||
|
||||
29
docs/installation/apt-repos.rst
Normal file
29
docs/installation/apt-repos.rst
Normal file
@ -0,0 +1,29 @@
|
||||
|
||||
.. _installation-apt-repos:
|
||||
|
||||
Debian / Ubuntu APT repositories
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We maintain APT repositories for Debian, Ubuntu and derivatives.
|
||||
The fingerprint of the signing key is ``E101 418F D3D6 FBCB 9D65 A62D 7086 99FC 5F2E BF16``.
|
||||
It is available at `<https://zrepl.cschwarz.com/apt/apt-key.asc>`_ .
|
||||
Please open an issue `in the packaging repository <https://github.com/zrepl/debian-binary-packaging>`_ if you encounter any issues with the repository.
|
||||
|
||||
The following snippet configure the repository for your Debian or Ubuntu release:
|
||||
|
||||
::
|
||||
|
||||
apt update && apt install curl gnupg lsb-release; \
|
||||
ARCH="$(dpkg --print-architecture)"; \
|
||||
CODENAME="$(lsb_release -i -s | tr '[:upper:]' '[:lower:]') $(lsb_release -c -s | tr '[:upper:]' '[:lower:]')"; \
|
||||
echo "Using Distro and Codename: $CODENAME"; \
|
||||
(curl https://zrepl.cschwarz.com/apt/apt-key.asc | apt-key add -) && \
|
||||
(echo "deb [arch=$ARCH] https://zrepl.cschwarz.com/apt/$CODENAME main" > /etc/apt/sources.list.d/zrepl.list) && \
|
||||
apt update
|
||||
|
||||
|
||||
.. NOTE::
|
||||
|
||||
Until zrepl reaches 1.0, all APT repositories will be updated to the latest zrepl release immediately.
|
||||
This includes breaking changes between zrepl versions.
|
||||
Use ``apt-mark hold zrepl`` to prevent upgrades of zrepl.
|
||||
45
docs/installation/compile-from-source.rst
Normal file
45
docs/installation/compile-from-source.rst
Normal file
@ -0,0 +1,45 @@
|
||||
.. _binary releases: https://github.com/zrepl/zrepl/releases
|
||||
|
||||
.. _installation-compile-from-source:
|
||||
|
||||
Compile From Source
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Producing a release requires **Go 1.11** or newer and **Python 3** + **pip3** + ``docs/requirements.txt`` for the Sphinx documentation.
|
||||
A tutorial to install Go is available over at `golang.org <https://golang.org/doc/install>`_.
|
||||
Python and pip3 should probably be installed via your distro's package manager.
|
||||
|
||||
Alternatively, you can use the Docker build process:
|
||||
it is used to produce the official zrepl `binary releases`_
|
||||
and serves as a reference for build dependencies and procedure:
|
||||
|
||||
::
|
||||
|
||||
git clone https://github.com/zrepl/zrepl.git && \
|
||||
cd zrepl && \
|
||||
sudo docker build -t zrepl_build -f build.Dockerfile . && \
|
||||
sudo docker run -it --rm \
|
||||
-v "${PWD}:/src" \
|
||||
--user "$(id -u):$(id -g)" \
|
||||
zrepl_build make release
|
||||
|
||||
Alternatively, you can install build dependencies on your local system and then build in your ``$GOPATH``:
|
||||
|
||||
::
|
||||
|
||||
mkdir -p "${GOPATH}/src/github.com/zrepl/zrepl"
|
||||
git clone https://github.com/zrepl/zrepl.git "${GOPATH}/src/github.com/zrepl/zrepl"
|
||||
cd "${GOPATH}/src/github.com/zrepl/zrepl"
|
||||
python3 -m venv3
|
||||
source venv3/bin/activate
|
||||
./lazy.sh devsetup
|
||||
make release
|
||||
|
||||
The Python venv is used for the documentation build dependencies.
|
||||
If you just want to build the zrepl binary, leave it out and use `./lazy.sh godep` instead.
|
||||
Either way, all build results are located in the ``artifacts/`` directory.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
It is your job to install the appropriate binary in the zrepl users's ``$PATH``, e.g. ``/usr/local/bin/zrepl``.
|
||||
Otherwise, the examples in the :ref:`tutorial` may need to be adjusted.
|
||||
140
docs/installation/freebsd-jail-with-iocage.rst
Normal file
140
docs/installation/freebsd-jail-with-iocage.rst
Normal file
@ -0,0 +1,140 @@
|
||||
.. include:: ../global.rst.inc
|
||||
|
||||
.. _installation-freebsd-jail-with-iocage:
|
||||
|
||||
FreeBSD Jail With iocage
|
||||
========================
|
||||
|
||||
|
||||
This tutorial shows how zrepl can be installed on FreeBSD, or FreeNAS in a jail using iocage.
|
||||
While this tutorial focuses on using iocage, much of the setup would be similar
|
||||
using a different jail manager.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
From a security perspective, just keep in mind that ``zfs send``/``recv`` was never designed with
|
||||
jails in mind, an attacker could probably crash the receive-side kernel or worse induce stateful
|
||||
damage to the receive-side pool if they were able to get access to the jail.
|
||||
|
||||
The jail doesn't provide security benefits, but only management ones.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
A dataset that will be delegated to the jail needs to be created if one does not already exist.
|
||||
For the tutorial ``tank/zrepl`` will be used.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
zfs create -o mountpoint=none tank/zrepl
|
||||
|
||||
The only software requirements on the host system are ``iocage``, which can be installed
|
||||
from ports or packages.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pkg install py37-iocage
|
||||
|
||||
.. NOTE::
|
||||
|
||||
By default ``iocage`` will "activate" on first use which will set up some defaults such as
|
||||
which pool will be used. To activate ``iocage`` manually the ``iocage activate`` command can be used.
|
||||
|
||||
Jail Creation
|
||||
-------------
|
||||
|
||||
There are two options for jail creation using FreeBSD.
|
||||
|
||||
1. Manually set up the jail from scratch
|
||||
2. Create the jail using the ``zrepl`` plugin. On FreeNAS this is possible from the user interface using the community index.
|
||||
|
||||
Manual Jail
|
||||
###########
|
||||
|
||||
Create a jail, using the same release as the host, called ``zrepl`` that will be automatically started at boot.
|
||||
The jail will have ``tank/zrepl`` delegated into it.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
iocage create --release "$(freebsd-version -k | cut -d '-' -f '1,2')" --name zrepl \
|
||||
boot=on nat=1 \
|
||||
jail_zfs=on \
|
||||
jail_zfs_dataset=zrepl \
|
||||
jail_zfs_mountpoint='none'
|
||||
|
||||
Enter the jail:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
iocage console zrepl
|
||||
|
||||
Install ``zrepl``
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pkg update && pkg upgrade
|
||||
pkg install zrepl
|
||||
|
||||
Create the log file ``/var/log/zrepl.log``
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
touch /var/log/zrepl.log && service newsyslog restart
|
||||
|
||||
Tell syslogd to redirect facility local0 to the ``zrepl.log`` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
service syslogd reload
|
||||
|
||||
Enable the zrepl daemon to start automatically at boot:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sysrc zrepl_enable="YES"
|
||||
|
||||
|
||||
Plugin
|
||||
######
|
||||
|
||||
When using the plugin, ``zrepl`` will be installed for you in a jail using the following ``iocage`` properties.
|
||||
|
||||
* ``nat=1``
|
||||
* ``jail_zfs=on``
|
||||
* ``jail_zfs_mountpoint=none``
|
||||
|
||||
Additionally the delegated dataset should be specified upon creation, and optionally start on boot can be set.
|
||||
This can also be done from the FreeNAS webui.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fetch https://raw.githubusercontent.com/ix-plugin-hub/iocage-plugin-index/master/zrepl.json -o /tmp/zrepl.json
|
||||
iocage fetch -P /tmp/zrepl.json --name zrepl jail_zfs_dataset=zrepl boot=on
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Now ``zrepl`` can be configured.
|
||||
|
||||
Enter the jail.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
iocage console zrepl
|
||||
|
||||
Modify the ``/usr/local/etc/zrepl/zrepl.yml`` configuration file.
|
||||
|
||||
.. TIP::
|
||||
|
||||
Note: check out the :ref:`tutorial` for examples of a ``sink`` job.
|
||||
|
||||
Now ``zrepl`` can be started.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
service zrepl start
|
||||
|
||||
Summary
|
||||
-------
|
||||
|
||||
Congratulations, you have a working jail!
|
||||
50
docs/installation/packages.rst
Normal file
50
docs/installation/packages.rst
Normal file
@ -0,0 +1,50 @@
|
||||
.. _installation-packages:
|
||||
|
||||
.. _binary releases: https://github.com/zrepl/zrepl/releases
|
||||
|
||||
Packages
|
||||
--------
|
||||
|
||||
zrepl source releases are signed & tagged by the author in the git repository.
|
||||
Your OS vendor may provide binary packages of zrepl through the package manager.
|
||||
Additionally, `binary releases`_ are provided on GitHub.
|
||||
The following list may be incomplete, feel free to submit a PR with an update:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - OS / Distro
|
||||
- Install Command
|
||||
- Link
|
||||
* - FreeBSD
|
||||
- ``pkg install zrepl``
|
||||
- `<https://www.freshports.org/sysutils/zrepl/>`_
|
||||
|
||||
:ref:`installation-freebsd-jail-with-iocage`
|
||||
* - FreeNAS
|
||||
-
|
||||
- :ref:`installation-freebsd-jail-with-iocage`
|
||||
* - MacOS
|
||||
- ``brew install zrepl``
|
||||
- Available on `homebrew <https://brew.sh>`_
|
||||
* - Arch Linux
|
||||
- ``yay install zrepl``
|
||||
- Available on `AUR <https://aur.archlinux.org/packages/zrepl>`_
|
||||
* - Fedora
|
||||
- ``dnf install zrepl``
|
||||
- Available on `COPR <https://copr.fedorainfracloud.org/coprs/poettlerric/zrepl/>`_
|
||||
* - CentOS/RHEL
|
||||
- ``yum install zrepl``
|
||||
- Available on `COPR <https://copr.fedorainfracloud.org/coprs/poettlerric/zrepl/>`_
|
||||
* - Debian + Ubuntu
|
||||
- ``apt install zrepl``
|
||||
- APT repository config :ref:`see below <installation-apt-repos>`
|
||||
* - OmniOS
|
||||
- ``pkg install zrepl``
|
||||
- Available since `r151030 <https://pkg.omniosce.org/r151030/extra/en/search.shtml?token=zrepl&action=Search>`_
|
||||
* - Void Linux
|
||||
- ``xbps-install zrepl``
|
||||
- Available since `a88a2a4 <https://github.com/void-linux/void-packages/commit/a88a2a4d7bf56072dadf61ab56b8424e39155890>`_
|
||||
* - Others
|
||||
-
|
||||
- Use `binary releases`_ or build from source.
|
||||
12
docs/installation/user-privileges.rst
Normal file
12
docs/installation/user-privileges.rst
Normal file
@ -0,0 +1,12 @@
|
||||
.. _installation-user-privileges:
|
||||
|
||||
User Privileges
|
||||
---------------
|
||||
|
||||
It is possible to run zrepl as an unprivileged user in combination with
|
||||
`ZFS delegation <https://www.freebsd.org/doc/handbook/zfs-zfs-allow.html>`_.
|
||||
Also, there is the possibility to run it in a jail on FreeBSD by delegating a dataset to the jail.
|
||||
|
||||
.. TIP::
|
||||
|
||||
Note: check out the :ref:`installation-freebsd-jail-with-iocage` for FreeBSD jail setup instructions.
|
||||
8
docs/installation/what-next.rst
Normal file
8
docs/installation/what-next.rst
Normal file
@ -0,0 +1,8 @@
|
||||
.. _installation-what-next:
|
||||
|
||||
What next?
|
||||
----------
|
||||
|
||||
Read the :ref:`configuration chapter<configuration_toc>` and then continue with the :ref:`usage chapter<usage>`.
|
||||
|
||||
**Reminder**: If you want a quick introduction, please read the :ref:`tutorial`.
|
||||
@ -47,7 +47,7 @@ We can model this situation as two jobs:
|
||||
Install zrepl
|
||||
-------------
|
||||
|
||||
Follow the :ref:`OS-specific installation instructions <installation>` and come back here.
|
||||
Follow the :ref:`OS-specific installation instructions <installation_toc>` and come back here.
|
||||
|
||||
Generate TLS Certificates
|
||||
-------------------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user