Migrating from the Serokell Octez packages
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