Background

Serokell maintains a set of Linux packages for the Tezos reference implementation Octez. There’s nothing wrong with the Serokell packages but last year the core development team added different packages to Octez directly. This article shows you how to migrate from the Serokell packages to the in-tree versions. For more details on the in-tree packages, please see my article.

Our assumptions:

  • Running on Ubuntu 22
  • Packages installed using apt using Serokell’s repository. We added the repository with add-apt-repository -yu ppa:serokell/tezos
  • The basic baking set up including client, node and baker. We installed this with apt-get install -y tezos-baking.
  • The node was set up on Quebecnet using the tezos-setup tool.

Before you do anything, make sure that:

  • You have taken a full backup of your machine.
  • Particularly that you have taken a full backup of your .tezos-client wallet from /var/lib/tezos.
  • If you are baking make sure you have the nonce files from the .tezos-client wallet safely stored.
  • Make sure that your baking keys (whether consensus or master keys) are appropriately stored somewhere else.
  • Did I mention taking a full backup of your machine?

This procedure comes with the Ming Vase license - if it breaks you get to keep the pieces. No warranty from me I’m afraid.

An exercise for the reader who has nothing to do: You can reverse this procedure and convert from the in-tree packages to Serokell’s.

Replacing the software

If you are using Serokell’s Apt repository, you will have installed softare with apt and there will be packages on your system. List them with dpkg --list.

$ dpkg --list | grep tezos
ii  tezos-baker-psparisc             2:21.3-0ubuntu1~jammy                   amd64        Daemon for baking
ii  tezos-baker-psquebec             2:21.3-0ubuntu1~jammy                   amd64        Daemon for baking
ii  tezos-baking                     2:21.3-0ubuntu1~jammy                   amd64        Package that provides systemd services that orchestrate other services from Tezos packages
ii  tezos-client                     2:21.3-0ubuntu1~jammy                   amd64        CLI client for interacting with tezos blockchain
ii  tezos-node                       2:21.3-0ubuntu1~jammy                   amd64        Entry point for initializing, configuring and running a Tezos node
ii  tezos-sapling-params             2:20.2-0ubuntu1~jammy                   amd64        Sapling params required in the runtime by the Tezos binaries

The client package tezos-client will be replaced by octez-client. The packages tezos-node and tezos-sapling-params will be replaced by octez-node. The baker packages tezos-baker-psparisc, tezos-baker-psquebec and tezos-baking will be replaced by octez-baker.

The above is the standard baking setup. The processes run under the tezos user.

$ ps auxww | grep octez
tezos       4286 12.6  1.1 718716 366804 ?       Ssl  12:49   0:01 /usr/bin/octez-node run --config-file /var/lib/tezos/node-quebecnet/config.json
tezos       4298  8.6  0.8 401892 277628 ?       Sl   12:49   0:00 octez-validator --socket-dir /tmp
tezos       4321  9.1  0.4 500540 163820 ?       Sl   12:49   0:00 /usr/bin/octez-baker-PsQuebec --endpoint http://127.0.0.1:8732 run with local node /var/lib/tezos/node-quebecnet --liquidity-baking-toggle-vote pass --without-dal baker

The new packages attempt to install a tezos user but we can reuse the one that exists. However we will need to modify it.

1. As root, change the shell for the tezos user to /bin/bash.

$ sudo chsh tezos
Changing the login shell for tezos
Enter the new value, or press ENTER for the default
        Login Shell [/bin/false]: /bin/bash

2. Stop the node and baking daemons. Check which services are running and stop them:

$ sudo systemctl | grep tezos
  tezos-baker-psquebec@quebecnet.service    loaded active running   Instantiated tezos baker daemon service
  tezos-baking-quebecnet.service            loaded active exited    Tezos baking instance for quebecnet
  tezos-node-quebecnet.service              loaded active running   Tezos node quebecnet
  system-tezos\x2dbaker\x2dpsquebec.slice   loaded active active    Slice /system/tezos-baker-psquebec

For example:

sudo systemctl stop tezos-baker-psquebec
sudo systemctl stop tezos-baker-psparisc
sudo systemctl stop tezos-baking-quebecnet
sudo systemctl stop tezos-node-quebecnet
sudo systemctl stop system-tezos\x2dbaker\x2dpsquebec.slice 

Check for processes again with ps auxww | grep octez.

3. Remove the packages:

sudo dpkg --remove tezos-baking tezos-baker-psparisc tezos-baker-psquebec
sudo dpkg --remove tezos-node tezos-client tezos-sapling-params

4. Remove the remote apt repository.

cd /etc/apt/sources.list.d/
sudo rm serokell-ubuntu-tezos-jammy.list 
sudo apt update

5. Install the new packages.

Two choices. i. Use the Nomadic Labs Apt repository. As root:

sudo -s
apt install -y curl gpg
curl -s "https://packages.nomadic-labs.com/ubuntu/octez.asc" |  \
    gpg --dearmor -o /etc/apt/keyrings/octez.gpg
echo "deb [signed-by=/etc/apt/keyrings/octez.gpg] https://packages.nomadic-labs.com/ubuntu jammy main" \
    > /etc/apt/sources.list.d/octez.list
apt update
apt install -y octez-client octez-node octez-baker

ii. Or direct downloads:

wget https://packages.tzinit.org/ubuntu-2204-lts/octez-client_21.3-1_amd64.deb
wget https://packages.tzinit.org/ubuntu-2204-lts/octez-node_21.3-1_amd64.deb
wget https://packages.tzinit.org/ubuntu-2204-lts/octez-baker_21.3-1_amd64.deb
sudo apt install -y ./octez-client_21.3-1_amd64.deb
sudo apt install -y ./octez-node_21.3-1_amd64.deb
sudo apt install -y ./octez-baker_21.3-1_amd64.deb

6. Reconfigure the node and start it.

The Serokell installation has node directories for mainnet, ghostnet and quebecnet. We were using the quebecnet one.

$ sudo su - tezos
$ ls -l
drwxr-xr-x 2 root  root  4096 Feb  4 12:40 node-custom
drwxr-xr-x 2 tezos tezos 4096 Feb  4 12:40 node-ghostnet
drwxr-xr-x 2 tezos tezos 4096 Feb  4 12:40 node-mainnet
drwxr-xr-x 5 tezos tezos 4096 Feb  4 12:54 node-quebecnet
-rw-r--r-- 1 root  root  5431 Feb  4 12:40 teztnets.json

As root, change the node directory in /etc/octez/node.conf as follows:

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

Now you can start your node again:

$ sudo systemctl enable octez-node
octez-node.service is not a native service, redirecting to systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable octez-node
$ sudo systemctl start octez-node
$ sudo tail -f /var/log/tezos/node.log 
Feb 04 13:07:03.525: initializing irmin context at /var/lib/tezos/node-quebecnet/context
Feb 04 13:07:03.829: activate chain NetXuTeGinLEqxp
Feb 04 13:07:03.830: synchronisation status: unsynced
Feb 04 13:07:03.830: too few connections (0)
Feb 04 13:07:03.830: starting local RPC server on ::ffff:127.0.0.1:8732 (acl = AllowAll)
Feb 04 13:07:03.831: the Tezos node is now running

7. Reconfigure your baker and start it.

The baker keys are exactly where we expect them:

$ sudo su - tezos
$ octez-client list known addresses
baker: tz1ctZpUQdGiHVJtiG48q9gdyNJSbUhYCrAm (unencrypted sk known)

As root, edit /etc/octez/baker.conf to use the key. Also set your liquidity baking preferences.

# These must be set and are local to you
#
# Liquidity baking (must be set to yay, nay or pass)
lq_vote="pass"

# Once you have setup a wallet or ledger (or similar), you are ready
# to bake. Setup your key alias here (must be set).
baking_key="baker"

Now you are ready to start your baker:

$ sudo systemctl enable octez-baker
octez-baker.service is not a native service, redirecting to systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable octez-baker
$ sudo systemctl start octez-baker
$ tail -f /var/log/tezos/baker_PsQuebec.log 
Feb 04 13:10:26.477: No DAL node endpoint has been provided.
Feb 04 13:10:26.477: It will soon be required to launch a
Feb 04 13:10:26.477:   DAL node before running the baker. For instructions on running a DAL node,
Feb 04 13:10:26.477:   please visit https://docs.tezos.com/tutorials/join-dal-baker.
Feb 04 13:10:26.483: received new head BMdbXgsz98fDhMGUHfmP2rjkiHiu7QCrS4YfaboTzoeZW3Xb67Z at
Feb 04 13:10:26.483:   level 1791746, round 0

Congratulations - you have converted your system to the Nomadic Labs packages.

What about DAL?

If you were running a DAL node before, you can switch DAL nodes very easily.

In step 3:

sudo dpkg --remove tezos-dal-node

In step 5, install the new DAL node:

sudo apt install -y octez-dal-node

There doesn’t appear to be a standard startup method available, so you probably did something custom yourself which will need to be removed.

You can edit /etc/octez/dal.conf to change the location of DAL directory you used. But if you are just baking with DAL there is no harm in starting again. Ideally you should preserve your DAL identity, but the rest of the data can be discarded.

As tezos, configure the DAL node. Use your baking address for the attester profile.

sudo su - tezos
octez-dal-node config init --attester-profiles=tz1...

Then as root, enable and start the DAL node

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

Do I need to do anything special if I have a ledger?

If you use a ledger, the tezos user will need to have access to the ledger USB device. If this hasn’t been done on your system already, it can be fixed quite easily. 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"

What about the Signer package?

The octez-signer package operates using a different user tzsigner to the other packages. You should not really run your signer on the same machine as your node and baker, but if you do at least you will have a bit of file protection from the UNIX security model.

In step 3 above, first check with service you are using and disable it. One of the following should work:

sudo systemctl stop tezos-signer-http
sudo systemctl stop tezos-signer-https
sudo systemctl stop tezos-signer-tcp
sudo systemctl stop tezos-signer-unix

Then remove the package:

sudo dpkg --remove tezos-signer

In step 5, install the new signer:

sudo apt install -y octez-signer

Set the permissions on the signer directory correctly:

sudo chown tzsigner:tzsigner /var/lib/tezos/signer

As root edit /etc/octez/signer.conf and make sure that:

datadir=/var/lib/tezos/signer

Customise the other options in the file. The type variable corresponds to http, https, socket (tcp) and local. Use the correct value depending on which systemctl script you used in the Serokell package. For HTTP and HTTPS make sure that the address variable is set if you want remote access. Make sure that the magic byte restrictions match your expectations. Then start the signer:

systemctl enable octez-signer
systemctl start octez-signer

What about the other packages?

Package Equivalent native package
tezos-accuser-* octez-baker
tezos-admin-client octez-client
tezos-baker-* octez-baker
tezos-baking octez-baker
tezos-client octez-client
tezos-codec octez-client
tezos-dac-client Not used
tezos-dac-node Not used
tezos-node octez-node
tezos-sapling-params octez-node
tezos-signer octez-signer
tezos-smart-rollup-node octez-smartrollup
tezos-smart-rollup-wasm-debugger octez-smartrollup

Alpha bakers and accusers are included in octez-experimental.

What about voting in governance elections?

The Serokell packages come with a voting script. But it is not difficult to vote with the baking key using octez-client. We don’t cover ledgers or remote signers here, but if you use these you should already know what to do to allow the voting operations.

sudo su - tezos
octez-client show voting period

This will output the proposal hash.

Current period: "exploration"
Blocks remaining until end of period: 28307
Current proposal: PtHangzHogokSuiMHemCuowEavgYTP8J5qQ9fQS793MHYFpCY3r
Ballots: { "yay": 10658, "nay": 0, "pass": 12735 }
Current participation 27.71%, necessary quorum 53.60%
Current in favor 10658, needed supermajority 8526

You can use this to vote. Use yay, nay or pass as appropriate.

octez-client submit ballot for baker \
      PtHangzHogokSuiMHemCuowEavgYTP8J5qQ9fQS793MHYFpCY3r pass