diff --git a/docs/installation.rst b/docs/installation.rst index 0d0b4f3..6b23092 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -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 `_. -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`` - - ``_ - * - MacOS - - ``brew install zrepl`` - - Available on `homebrew `_ - * - Arch Linux - - ``yay install zrepl`` - - Available on `AUR `_ - * - Fedora - - ``dnf install zrepl`` - - Available on `COPR `_ - * - CentOS/RHEL - - ``yum install zrepl`` - - Available on `COPR `_ - * - Debian + Ubuntu - - ``apt install zrepl`` - - APT repository config :ref:`see below ` - * - OmniOS - - ``pkg install zrepl`` - - Available since `r151030 `_ - * - Void Linux - - ``xbps-install zrepl`` - - Available since `a88a2a4 `_ - * - 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 ``_ . -Please open an issue `in the packaging repository `_ 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 `_. -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` and then continue with the :ref:`usage chapter`. - -**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 diff --git a/docs/installation/apt-repos.rst b/docs/installation/apt-repos.rst new file mode 100644 index 0000000..0188469 --- /dev/null +++ b/docs/installation/apt-repos.rst @@ -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 ``_ . +Please open an issue `in the packaging repository `_ 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. diff --git a/docs/installation/compile-from-source.rst b/docs/installation/compile-from-source.rst new file mode 100644 index 0000000..b2f41aa --- /dev/null +++ b/docs/installation/compile-from-source.rst @@ -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 `_. +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. diff --git a/docs/installation/freebsd-jail-with-iocage.rst b/docs/installation/freebsd-jail-with-iocage.rst new file mode 100644 index 0000000..00a6269 --- /dev/null +++ b/docs/installation/freebsd-jail-with-iocage.rst @@ -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! diff --git a/docs/installation/packages.rst b/docs/installation/packages.rst new file mode 100644 index 0000000..754fe33 --- /dev/null +++ b/docs/installation/packages.rst @@ -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`` + - ``_ + + :ref:`installation-freebsd-jail-with-iocage` + * - FreeNAS + - + - :ref:`installation-freebsd-jail-with-iocage` + * - MacOS + - ``brew install zrepl`` + - Available on `homebrew `_ + * - Arch Linux + - ``yay install zrepl`` + - Available on `AUR `_ + * - Fedora + - ``dnf install zrepl`` + - Available on `COPR `_ + * - CentOS/RHEL + - ``yum install zrepl`` + - Available on `COPR `_ + * - Debian + Ubuntu + - ``apt install zrepl`` + - APT repository config :ref:`see below ` + * - OmniOS + - ``pkg install zrepl`` + - Available since `r151030 `_ + * - Void Linux + - ``xbps-install zrepl`` + - Available since `a88a2a4 `_ + * - Others + - + - Use `binary releases`_ or build from source. diff --git a/docs/installation/user-privileges.rst b/docs/installation/user-privileges.rst new file mode 100644 index 0000000..40d0868 --- /dev/null +++ b/docs/installation/user-privileges.rst @@ -0,0 +1,12 @@ +.. _installation-user-privileges: + +User Privileges +--------------- + +It is possible to run zrepl as an unprivileged user in combination with +`ZFS delegation `_. +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. diff --git a/docs/installation/what-next.rst b/docs/installation/what-next.rst new file mode 100644 index 0000000..79d495b --- /dev/null +++ b/docs/installation/what-next.rst @@ -0,0 +1,8 @@ +.. _installation-what-next: + +What next? +---------- + +Read the :ref:`configuration chapter` and then continue with the :ref:`usage chapter`. + +**Reminder**: If you want a quick introduction, please read the :ref:`tutorial`. diff --git a/docs/tutorial.rst b/docs/tutorial.rst index bbdb382..aacc8a0 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -47,7 +47,7 @@ We can model this situation as two jobs: Install zrepl ------------- -Follow the :ref:`OS-specific installation instructions ` and come back here. +Follow the :ref:`OS-specific installation instructions ` and come back here. Generate TLS Certificates -------------------------