(Updated on 25/7/2024 to cover the DAL package)

Octez packages

A few of us Tezos folk are working 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.

The experimental packages can be downloaded for Debian Linux and Ubuntu Linux https://pkgbeta.tzinit.org/. There are also Raspberry Pi packages.

There are several packages:

  • octez-client - the client for manipulating wallets and signing items
  • octez-node - the Octez 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:

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

or

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

On AWS Linux, use yum:

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

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"

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 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.

lq_vote="pass"
baking_key="baker_key"

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 DAL package

The DAL package is independent of the other packages. Once installed, edit the file /etc/octez/dal-node.conf. Then switch to the tezos user and configure the DAL node. For a DAL node supporting a baker:

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

For DAL boot node:

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

You can run octez-node on the same machine and leave off endpoint if you want.

Then as root enable and start the package.

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

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.

Migrating from previous experimental versions

The tezos and tzsigner users

Originally the tezos and tzsigner users were setup as “system” users on Debian-based systems. Recently we have set these up as normal users. It’s possible that the system users will conflict with Debian or Ubuntu’s plans in the future. If you want to change your users and groups to the new way:

  1. Stop the daemons you are using.
  2. Remove the tezos and tzsigner users and groups from the system (e.g. vipw and vi /etc/group)
  3. Reinstall the packages.
  4. Use chown -R tezos:tezos on the relevant working directories in /var/tezos
  5. Use chown -R tzsigner:tzsigner on the relevant working directories in /var/tzsigner if you are using the signer package.