From 878b5f238bf73cec5970d1faf201e83345fa313c Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 13 May 2024 13:43:15 +0200 Subject: [PATCH 1/2] doc: add page services.rst in Intro Co-authored-by: Zettez <1766551-zettez@users.noreply.gitlab.com> --- docs/index.rst | 1 + docs/introduction/services.rst | 224 +++++++++++++++++++++++++++++++++ 2 files changed, 225 insertions(+) create mode 100644 docs/introduction/services.rst diff --git a/docs/index.rst b/docs/index.rst index cc32b172cc70..fdfc8fef5f7c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -149,6 +149,7 @@ Platform developers are also provided reference materials for internal APIs of O introduction/howtoget introduction/howtouse introduction/howtorun + introduction/services introduction/versioning BREAKING CHANGES diff --git a/docs/introduction/services.rst b/docs/introduction/services.rst new file mode 100644 index 000000000000..59b4f13443dd --- /dev/null +++ b/docs/introduction/services.rst @@ -0,0 +1,224 @@ +Setting up Octez Services +========================= + +The Octez suite consists of :ref:`several executables `, some to be run interactively, while others are to be run as daemons. + +Previous tutorials in this section showed how to :doc:`get started with the different executables <./howtouse>`, and different :doc:`options for participating to Tezos <./howtorun>` such as delegating or baking. +However, in these tutorials, daemons are just run in background or left in another terminal. +This page shows how Octez daemons can be safely run from the official binary packages, as Unix services, which can ensure that they are started automatically and restarted in case of failures. + +Why Use Binary Packages? +------------------------ + +When it comes to installing software, especially for critical +applications like Tezos/Octez, it’s crucial to ensure a secure and +stable environment. While compiling from source can provide +customization options, it often introduces complexities and risks. +Instead, opting for binary packages from a trusted source simplifies +installation and enhances security. + +Binary packages compiled for a specific platform should be always +preferred over source or statically compiled packages. These packages +can be used to simplify the creation of OCI images or deployed on bare +metal. + +Using the official binary packages offers several advantages: + +- **Security**: Binary packages are pre-compiled and thoroughly tested, + reducing the risk of vulnerabilities introduced during compilation. + All our packages are signed and our supply chain is strictly + monitored to make sure the packages that we deliver only use + components that were vetted by our engineering team. + +- **Stability**: Binaries from a trusted repository undergo rigorous + testing, ensuring stability and compatibility with the target system. + We make sure to compile our binaries in a clean environment and + using an up-to-date software distribution. We use LTS (long-term service) distributions to + enhance stability and reduce the attack surface. + +- **Ease of Installation**: Binary packages can be installed using + standard package management tools, streamlining the process. For instance, ``apt`` is + ubiquitous in the Debian world. These tools allow us to sign our packages + that can be automatically verified by the end user during installation. We + provide packages that allow the end user to easily tailor their + installation for different use cases. + +- **Reduced Downtime**: With reliable binaries and straightforward + installation, system downtime due to installation errors or + compatibility issues is minimized. We carefully test the upgrade + process of our packages to make sure that end users can enjoy a click and go + upgrade process with near to zero downtime. + +Installing Octez +---------------- + +First of all, you must :ref:`install Octez from binary packages `, as explained in the installation tutorial. + +To make things concrete, we are assuming here that you installed Octez Debian packages, but most commands should apply to other distributions. + +Verify Installation +~~~~~~~~~~~~~~~~~~~ + +After installation, verify that Octez components are installed correctly: + +.. code:: shell + + octez-node --version + octez-client --version + +These binaries can be used by any user. However, to run Octez in +production our package setup a special user named ``tezos`` to run all +daemons via ``systemd`` and without direct user intervention. + +Enabling Daemons +---------------- + +To ensure that Octez services start automatically on system boot and can +be managed using ``systemd``, we need to enable the services. +Indeed, these services are installed by ``apt`` but left disabled by default. + +For example, to enable the Octez node ``systemd`` service: + +.. code:: shell + + sudo systemctl enable octez-node + +Configuring the node +-------------------- + +Octez packages provide a very basic configuration in +``/etc/default/octez-*`` files. These are to be read as configuration +files for the ``systemd`` services. We took a non opinionated approach +regarding the basic configuration provided by default. We do not make +assumptions on the setup of the machine or try to imagine all possible +use cases. To create more advanced configurations, the user can directly +configure each daemon using commands such as: + +.. code:: shell + + sudo su tezos -c "octez-node config ..." + +For more details on configuring the Octez node, see :doc:`../user/setup-node`. +In particular: + +- to accelerate the node's bootstrap, you usually :ref:`import a snapshot file ` before starting the node; +- you may want to connect to a test network if your goal is learning, developing, or testing. + +Running the Octez node +~~~~~~~~~~~~~~~~~~~~~~ + +Once the node is configured, we can use ``systemd`` to start the daemon: + +.. code:: shell + + sudo systemctl start octez-node + +We can also check the status of the daemon in the logs of the node that +are stored by default in ``/var/log/tezos/node.log``. Logs are +automatically rotated using ``logrotate``. + +The Octez baker can be configured in a similar way. However, because of +the sensitive nature of the private keys needed by the baker to +function, we suggest hereafter a slightly more involved configuration procedure +using the Octez signer. + +Configuring the signer +---------------------- + +First, logged as the user chosen to run the signer, we must create a set of keys. These are the +private keys that will be entrusted to the signer to actually sign +operations on behalf of the baker. The signer will run in a different +process (possibly on a separate host), and ideally using a hardware +enclave such as a :ref:`hardware ledger `. For the sake of brevity, in this +example, the keys will be simply stored on the disk, but this is not a +recomended setting for a production baker. + +We create an authentication key that is going to be used to authenticate +the baker with the signer, and a signing key to sign the operations. + +.. code:: shell + + # create a signing key + $ octez-signer gen keys alice + + # create an authentication key + $ octez-client gen keys auth + + $ octez-client show address auth + Hash: tz1V7TgBR52wAjjqsh24w8y9CymFGdegt9qs + Public Key: edpk123456789.... + + # add the auth key to the octez-signer. This is the default options set in the octez-signer.service file + $ octez-signer add authorized key edpk123456789... --name auth + +Now we need to configure the ``octez-signer`` service. We use again ``systemd`` and +we run it as a user service. The ``octez-signer.service`` file can be +customized by the user if needed to allow for more complex and secure scenarios. + +.. code:: shell + + # customize the signer service if needed + $ mkdir -p ~/.config/systemd/user/ + $ cp /usr/share/doc/octez-signer/octez-signer.service ~/.config/systemd/user/ + + # start the service + $ systemctl --user start octez-signer + + # examine the logs + $ journalctl --user-unit octez-signer + +For more advanced configurations, see the :ref:`signer guide `. + +Configuring the baker +--------------------- + +Now that the signer is running, we need to configure the baker. +Since the baker runs as the user ``tezos``, we use ``sudo su tezos -c`` to wrap the configuration command below: + +.. code:: shell + + # Get the tz1 address of our signing key + $ octez-signer show address alice + Hash: tz1V7TgBR52wAjjqsh24w8y9CymFGdegt9qs + Public Key: edpkvGAz71r8SZomcvF7LGajXT3AnhYX9CrmK3JWgA2xk8rf8CudY8 + + # Configure the baker to use the remote signer + sudo su tezos -c "octez-client -R tcp://localhost:7732 import secret key alice remote:tz1V7TgBR52wAjjqsh24w8y9CymFGdegt9qs" + +Now that everything is in place, as for the node, we can first enable, +then start the Octez baker. + +.. code:: shell + + sudo systemctl enable octez-baker-active.service + sudo systemctl start octez-baker-active.service + +The logs of the baker are available in ``/var/log/tezos/baker-active.log``. + +Notice that the Octez baker package defines two services, +``octez-baker-active`` and ``octez-baker-next`` respectively associated +with the active protocol and the next proposed protocol upgrade. The +names of the protocols associated with these daemons are specified in +``/etc/default/octez-baker-*`` files. ``octez-baker-next`` +should be used for testing and during a protocol upgrade. Running +``octez-baker-next`` together with ``octez-baker-active`` is +possible and recommended to avoid downtime. + +Upgrading Octez +--------------- + +To upgrade Octez to the latest version, see the corresponding section in +the :doc:`installation guide <./howtoget>`. + +In our case, we can simply proceed as follows: + +.. code:: shell + + sudo apt-get update + sudo apt-get upgrade octez-node octez-client octez-baker + +When necessary, the upgrade scripts will make the user aware of breaking +changes and required actions such as new configuration parameters or +changes in governance. + +Mind restarting the running services using ``systemctl restart ``. -- GitLab From 4546578df49a4e89784650b16d5090c9f382a136 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 3 Sep 2024 13:29:41 +0200 Subject: [PATCH 2/2] doc: explain apt install of new packages --- docs/introduction/howtoget.rst | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index 52283821f19c..fcbb4a3d4284 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -92,7 +92,7 @@ There are several packages: Ubuntu and Debian Octez packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you're using Ubuntu or Debian, you can also install packages with Octez binaries +If you're using Ubuntu or Debian, you can install the same packages as in the release page using ``apt`` directly from our APT repository, instead of going to the Octez release page as explained above. @@ -150,6 +150,26 @@ possible to configure the software to use a different user (even root). The documentation for these packages, originally developed by Chris Pinnock, can be found here: https://chrispinnock.com/tezos/packages/ +New set of Debian packages +"""""""""""""""""""""""""" + +There is also a new generation of Debian packages that are available for testing. +These packages will replace the currently available packages mentioned above. + +The new set of packages can be installed by adding the following apt repository:: + + export distribution=debian + export release=bookworm + export bucket="tezos-linux-protected-repo" + + curl "https://$bucket.storage.googleapis.com/next/$distribution/octez.asc" | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/octez.gpg + echo "deb [arch=amd64] https://$bucket.storage.googleapis.com/next/$distribution $release main" | sudo tee /etc/apt/sources.list.d/octez.list + sudo apt-get update + sudo apt-get install octez-node ... + +Once the Octez binary packages are installed, they can be set up as services +as explained in :doc:`./services`. + Fedora Octez packages ~~~~~~~~~~~~~~~~~~~~~ -- GitLab