This is a refresh of my article from 2023.

Octez packages

A few of us Tezos folk worked on a set of Octez packages in Debian and Red Hat packaging formats. Octez is the reference implementation of the Tezos blockchain software. If you have read my Tezos articles on this site, you will have seen them already.

They can be downloaded for Debian, Ubuntu and Rocky Linux from https://packages.tzinit.org/. They are also available from the Octez release page. However note they don’t build packages for the EVM node as the version numbers are handled differently.

There are several packages:

octez-client - the client for manipulating wallets and signing items
octez-node - the Octez node
octez-dal-node - the Octez DAL node
octez-baker - the Octez baking daemons and VDF
octez-smartrollup - the Octez smart rollup daemons
octez-signer - the remote signer, to hold keys on a different machine from the baker or client

Also there are some experimental packages:

octez-experimental - binaries that are considered experimental including the alpha baker and smart rollup node.
octez-evm-node - the EVM endpoint node for Etherlink

The packages are setup to run under a dedicated user. The node, baker and smartrollup packages use a user and group called tezos. The signer package uses a user and group called tzsigner. It’s possible to configure the software to use a different user (even root).

Installing the packages

On Debian and Ubuntu Linux, you can install the packages using dpkg or apt. For example, to install the client use either:

apt install ./octez-client_21.3-1_amd64.deb

dpkg -i octez-client_21.3-1_amd64.deb

On Rocky Linux, use yum:

yum install ./octez-client-21.3-1.x86_64.rpm

For the below we will assume that you are running everything on the same server.

Setting up the node

Install the octez-node package using either dpkg or yum as appropriate. The file /etc/octez/node.conf ships with the package and is used to declare settings that the start and stop scripts use. The defaults should be good for most sites, but you might want to change the default directories for the node and log files. Additional command line options can be given using othercliopts_node.

# node.conf
# User to run as
#
user=tezos
group=tezos

# Data Directory
# An independent mount point of /var/tezos is recommended
#
nodedir=/var/tezos/.tezos-node

# Logfile
#
logdir=/var/log/tezos
logfile=${logdir}/node.log
rotateonstart=yes

# Other options to pass the node
#
othercliopts_node=""

As the node will be running as tezos , you will need to configure it by assuming the role of the user. For example:

sudo su - tezos
octez-node config init --network=mainnet \
			--history-mode=rolling \
			--net-addr="[::]:9732" \
			--rpc-addr="127.0.0.1:8732"

Replace mainnet with the network URL of your choice. For example, ghostnet or https://teztnets.com/.

As root, you can start the node as follows:

systemctl enable octez-node
systemctl start octez-node

The service will restart on boot.

The daemon has been setup to log to a file in /var/log/tezos. This can be changed in /etc/octez/node.conf. Observe the logs as follows:

tail -f /var/log/tezos/node.log

Setting up the DAL node

The Data Availability Layer will become mandatory in future Tezos releases so it’s good to get into the practice of running it now. The DAL package is independent of the other packages.

To configure the DAL node, switch to the tezos user. For a DAL node supporting a baker:

sudo su - tezos
octez-dal-node config init --endpoint http://mynode:8732 \
			--net-addr="[::]"

If you know your baking address now, it’s better to add --attester-profiles=tz1... to the above.

If run octez-node on the same machine, you can leave off the endpoint statement.

Then as root enable and start the package.

systemctl enable octez-dal-node
systemctl start octez-dal-node

You can customise the file /etc/octez/dal-node.conf but it is probably not necessary.

Setting up the baker

The baker package currently needs the node to be on the same machine. So you will need the node package installed. We assume that you are baking with a key aliased as baker_key. If not done already, self-delegate the key.

octez-client register key baker_key as delegate

(If you are a using a ledger, you will need to import the key and set the ledger up to bake. See my how-to on this.

The file /etc/octez/baker.conf contains a few essential variables that must be set. The baking key must match the key used to bake and you must declare a liquidity baking vote of yay, nay or pass. Also specify your DAL node here. If you don’t want to use DAL, leave dalurl blank.

lq_vote="pass"
baking_key="baker_key"
dalurl="http://127.0.0.1:10732"

The bakers can be started with systemctl as root:

systemctl enable octez-baker
systemctl start octez-baker

Running a VDF service

There is very little to do to configure the VDF service, other than setup a rolling node on the same machine. Install the octez-baker package. Then enable the service like so:

systemctl enable octez-vdf
systemctl start octez-vdf

Using the Smart Rollup Package

Install the Smart Rollup Package. Assuming that there is a Smart Rollup initiated and a wallet on your machine, you can configure and run the Smart Rollup daemon as follows, replacing SMARTROLLUP with the rollup identifier and OPERATOR with your operator wallet hash.

sudo su - tezos
octez-smart-rollup-node-PtMumbai \
    init operator config for SMARTROLLUP \
    with operators OPERATOR

Then run the Smart Rollup daemons as root as follows:

systemctl enable octez-smartrollup
systemctl start octez-smartrollup

Using the signer package

The signer package is designed to be independent of the other packages and by default the program runs under the tzsigner user.

Install the signer package. Once installed, edit the file /etc/octez/signer.conf. Key things to note by default:

The signer by default will sign any message it is given and this may not be suitable for your production environment. The configuration needs tuning.
The configuration is setup to run an HTTP daemon but only on localhost. Setting address="0.0.0.0" will open the service.
There are configuration options for the socket file and HTTPS certificates that need tuning if you decide to use these methods
The hwm_check should be set to yes on a production signer supporting baking
You should consider setting magic_bytes to prevent certain operations such as funds transfer
You should also consider some protection between the signer and client such as key authetication. This can be enforced with auth=yes. See below.

If you are baking, once you have self-delegated the baking key a typical configuration to protect from funds transfer and double-baking is:

magic_bytes="0x11,0x12,0x13"
hwm_check=yes

Once setup, you can enable the daemon as follows:

systemctl enable octez-signer
systemctl start octez-signer

By default, the logs are stored in /var/logs/tzsigner.

You can create a key in the tzsigner account:

$ sudo su - tzsigner
$ octez-signer gen keys alice
$ octez-signer list known addresses
alice: tz1aUmQtyXxXZoFu5jPMkJLTPA4CRDd78Yxs (unencrypted sk known)

On the client where you will use the key you can connect it as follows for HTTP:

octez-client import secret key alice http://hostname-of-signer:6732/tz1aUmQtyXxXZoFu5jPMkJLTPA4CRDd78Yxs

or for Socket use:

octez-client import secret key alice tcp://hostname-of-signer:6732/tz1aUmQtyXxXZoFu5jPMkJLTPA4CRDd78Yxs

To check it is working use:

$ octez-client sign bytes 0x03 for alice
Signature: sigTti9DXgXDNYn7Kv8TaYRT4mmkjMQb2sbw4DbPZ48UbXChHCwEpHpQsSxZKrAwEntsboMzjmokNZwshCRnGJVV1tPPsR1Z

To enforce client-signer authentication using keys, make sure auth=yes in the configuration and restart the signer with systemctl. You can observe that the check will now fail:

$ octez-client sign bytes 0x03 for alice
Error:
  remote signer expects authentication signature, but no authorized key was found in the wallet

Then create a key on the client machine:

$ octez-client gen keys vps
$ cat ~/.tezos-client/public_keys
[ { "name": "vps",
    "value":
       "unencrypted:edpk123456789" } ]

And import the key on the signer.

octez-signer add authorized key edpk123456789 \
    --name vps

Now signing works on the client again:

$ octez-client sign bytes 0x03 for alice
Signature: sigTti9DXgXDNYn7Kv8TaYRT4mmkjMQb2sbw4DbPZ48UbXChHCwEpHpQsSxZKrAwEntsboMzjmokNZwshCRnGJVV1tPPsR1Z

There are some suggested options in the configuration file for signers that provide baking keys.

Please see the Octez Signer Manual for more details.

Using a ledger

In Setting up a Tezos Baker in 5 steps we set up a ledger and bake with it. There is more detail there, including how to install the applications on the ledger. The key thing to remember is that the tezos user needs access to the Ledger USB device and this is not done by default. To allow this:

As root, create a file called 20-hw1.rules in the directory /etc/udev/rules.d containing the following lines:

# All ledger devices
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", GROUP="tezos", OWNER="tezos", MODE="0600"

Reload the USB Device service with sudo systemctl reload udev.

You should be able to see the ledger, import the keys from it and setup the Ledger to bake.

sudo su - tezos
octez-client list connected ledgers
octez-client import secret key my_ledger_key \
        "ledger://change-this-tomatch-yours/ed25519/0h/0h"

octez-client setup ledger to bake for my_ledger_key