Skip to content

How To Install Telos, A Block Producer’s Guide

Jerry Huff edited this page Jul 28, 2019 · 41 revisions


The intent of this document is to provide guidance and best practices around the setup and configuration of a Telos block producing “node” (henceforth referred to as an “instance”). This is intended for a technical audience, such as system administrators, as a certain level of experience, and fundamental understanding of the concepts described herein is expected.

Note: all commands to be executed look like this.

Note from J.T. @ Big Iron BP - I love scripts (I have scripts that do all the below) but I find that it just leads to people who want to push a button and be done then not understand what is really going on under the hood. Below are some instructions to install and run a Telos node, then register it as a block producer.

There are a large number of ways to accomplish this. This one works for me and my team. I don’t run docker and I don’t actually install Telos to give me more management flexibility and to be able to switch between versions easily if needed to roll back due to software bugs.


  • Ubuntu 16.04 LTS that has been fully updated and rebooted (Ubuntu 18.x.x LTS has also been reported to work but everything below is built on v.16)

sudo apt update

sudo apt upgrade

  • Your BP instance has been assigned a public IP, and is either running on your own hardware (“bare metal”), or running on a hosted service like Digital Ocean, Vultr, AWS, etc...

  • If the instance is behind a firewall, you’ll need to port forward the appropriate ports and protocols (http, p2p, etc. over tcp)

Best Practices:

You never want to run anything Telos with root access. If all you have is a root account, create a new account with sudo privileges. (Sudo privileges can be removed after your first build)

adduser <username>

usermod -aG sudo <username>

usermod -m -d /telosdata <username>

Exit your root session, and login as the newly created user.

Partitioning: It is highly recommended that you create separate partitions for OS, log, block and state directories. While partitioning is beyond the scope of this article, here is an excellent article re the performance benefits that can be realized as a result of partitioning: All of the required directories can by symlinked or mounted onto the separate partitions.

Time synchronization: Its essential that all BP instances are set to sync with a time server. Here's an excellent article on setting up NTP on Linux:

Building Telos

Note: The paths shown here are only examples, feel free to specify paths that work for your environment.

Create a working directory for the Telos software, and change to that directory. In our example, we're using the existing home directory for our newly created (non-root) user located at /telosdata.

cd /telosdata/

Clone the Telos code repository:

git clone

cd telos

git checkout <tag of version> (current tag "v1.7.4")

git submodule update --init --recursive

./scripts/ -s TLOS

If you have never run the build script before, it will install all the prerequisites (this is where sudo privileges are required) and build the telos software. You do not need to run this script as sudo as it will ask you for a sudoers password during the install process. Depending on your instance's cpu power, this script will take some time to run, so be patient.

If you get this, you’ve done good:

You can now run the commands displayed. Be advised that at this time, a few of the tests have not been re-written for Telos and will likely fail.

Finally, run the install script:

sudo ./scripts/

Once installation is complete, verify the compiled version of nodeos matches the tag you checked out:

nodeos --version

Setting up your environment:

As you’ll be calling Telos commands regularly (nodeos, teclos), being able to call the commands without specifying the entire path to the executable is convenient. Add the nodeos and teclos binaries to your path.

Using your preferred editor (vi, nano, etc...) edit ~/.profile

Add the following at the end of the file to provide the paths to the teclos and nodeos executables:

export PATH=/telosdata/telos/build/programs/cleos:$PATH

export PATH=/telosdata/telos/build/programs/nodeos:$PATH

For the changes to take effect, run:

source ~/.profile

Key Management:

Create the multiple keys pairs required to run a BP node. During key creation, these can be output to the console using the “--to-console” flag, or to a file with the “--file” {FILE NAME}) flag. Best practice is to output to the console, and record the keys externally, so the keys are never written to disk.

Note: if you added the "teclos" command to your path (as per the previous step), you can call teclos from anywhere. If not, you'll need to specify the entire path as below.


Create owner key:

cleos create key --to-console

Create active key:

cleos create key --to-console

Create producer key:

cleos create key --to-console

Label ("owner", "active", "producer") and securely record (ie: encrypt) the resulting public and private key pairs. KEEP THESE IN A SECURE PLACE and guard these keys with your life. Two thumb drives stored in diverse locations is highly recommended.


On Telos, cleos is the program that manages accounts. To see all the available options for cleos, consult the docs ( or simply use the help command:

cleos --help

While account creation is beyond the scope of this tutorial (see Registration below for easy account creation), please be aware that when creating your producer account, there are restrictions on the allowed characters; the account must be exactly 12 characters in length.

Create a wallet:

cleos wallet create -n my-wallet --to-console

When a wallet is created, you are presented with a password. Securely record that password, and as with your keys - KEEP THIS IN A SECURE PLACE and guard this with your life.

Verify the wallets creation, using the list command. The resulting output should display your wallet by name, with a "*" next to it, indicating its unlocked:

cleos wallet list

Import the keys you had created previously to your wallet:

cleos wallet import -n my-wallet --private-key [...]

cleos wallet import -n my-wallet --private-key [...]

cleos wallet import -n my-wallet --private-key [...]

Verify the keys are present in the wallet, by listing the wallet's private keys. In order to query the wallet for the private keys, you must provide the password:

cleos wallet private_keys -n my-wallet

Working with Nodeos

The nodeos program is one of the core components of Telos. To see all the available options for nodeos, consult the docs ( or simply use the help command:

nodeos --help

Create a working directory for Telos data (ie: /telosdata/data/), and change to that directory. The paths shown here are only examples, so feel free to specify paths that work for your environment. However, it is critical that this is a separate directory from the directory where the Telos software was built (/telosdata/telos/). In our example, we're using the home directory for our newly created (non-root) user located at /telosdata.

mkdir data

cd data

Create a config.ini file in the /telosdata/data/ directory. You can view a sample config.ini file with the recommended settings, and simply copy/paste its content using the text editor of your choice (ie: vi, nano), and change the necessary values to your own.

You'll need to change/update the following values:

  • agent-name = "{producer_name}"
  • producer-name = {producer_name}
  • signature-provider = {Public_key}=KEY:{private_key}
  • replace the list of p2p peers at the end of the file with the current list from here: (be sure and remove the local node from the list!)

Download the genesis.json file to the /telosdata/data/ directory. Note, this file is stage specific, so IF THE CHAIN HAS MOVED TO ANOTHER STAGE THIS FILE WILL NOT WORK (currently v1.7.4).

You can now start nodeos. For the first time, you will need to reference the genesis.json file. In the case you tried to start nodeos prematurely, you'll need to delete all blocks using the following command:

nodeos --delete-all-blocks --data-dir /telosdata/data/ --genesis-json /telosdata/data/genesis.json --config-dir /telosdata/data "$@" > /telosdata/data/stdout.txt 2> /telosdata/data/stderr.txt &

You can verify whether nodeos is running by checking:

ps -elf | grep nodeos

With nodeos running, you should now be able to run:

tail -f /telosdata/data/stderr.txt

...and then see nodeos console output showing blocks syncing every 1000 blocks. You will likely also see several connection errors. These are normal due to bad peers which can be removed from your p2p list as you identify them. Nodeos will need to be restarted for any changes to take effect.

After being fully synced, you can start nodeos in the future with:

nodeos --data-dir /telosdata/data --config-dir /telosdata/data "$@" > /telosdata/data/stdout.txt 2> /telosdata/data/stderr.txt &

When your node is fully synced and all 21 BPs are producing, you will see a block every .5 seconds in stderr.txt.

nodeos can be gracefully stopped with:

pkill nodeos


Finally, you must register your node on the chain as a block producer. To register, issue the following command (replacing the example values with yours):

cleos system regproducer <producer name> <producer public key> "<producer website>" -p <producer name>

Alternatively, you can generate the regproducer command for your node and create an account via the

  1. Enter your configuration into the web form.
  2. Click on the Register button.
  3. Copy the command generated by submitting the form.
  4. Run the generated regproducer command on your local node.

Your account is now created and registered as a producer on the testnet.


As demands increase and more DApps and users come to Telos, performance requirements for BPs will be ever increasing. In addition to keeping pace with the growth of the Telos chain, BPs are expected to perform regular maintenance. Prior to initiating maintenance, you must unregister your producing instance.

To unregister:

cloes system unregprod producername



Tools and scripts to monitor EOS BP:

You can’t perform that action at this time.