Skip to content

Latest commit

 

History

History
289 lines (198 loc) · 16.2 KB

freebsd_ton_fullnode_config.md

File metadata and controls

289 lines (198 loc) · 16.2 KB
Raw

FreeBSD Telegram Open Network full node configuration guide

Configuration and initialization of TON full node

This guide outlines process of conifguration and initialization of full node / validator for Telegram Open Network based blockchain networks on FreeBSD host, based on example of Newton Blockchain Testnet.

Following this guide you should be able to spawn nodes for other networks as well, even on the same machine / virtual host if you desire.

Table of content

[TODO]

Prerequesites / assumptions

Completion of chapter 1 of FreeBSD Telegram Open Network installation guide and as a result:

  • Compiled and installed distribution under /usr/local/opt/ton
  • Presence of /var/db/ton data directory
  • Access to internet from the host

We also assume that you chose to create a dedicated user called tond and this user has read/write access to /var/db/ton directory. You can substitute this username for any other user, just make sure that this account can access /var/db/ton.

Chapter 1: Create work directory for your node

In our example node work directory will be named: /var/db/ton/newton-testnet-node.

sudo -u tond mkdir -p /var/db/ton/newton-testnet-node/{etc,db,log}
sudo -u tond chmod -R 700 /var/db/ton/newton-testnet-node

This should work if you have a user tond and this user has r/w rights to /var/db/ton

Result

We have created a work directory for our ton node.

Chapter 2: Download global network configuration

Configuration of each TON node begins with downloading of global configuration file for your network. This file contains some basic information about network, for example it specifies at least one node with fixed IP address from which ton software can download additional network information.

Each network (Newton testnet, TFC testnet, TON testnet2, Freeton etc.) has it's own global configuration file. Source of those files depends on the network. We will be using Newton Blockchain testnet global configuration file:

sudo -u tond fetch https://raw.githubusercontent.com/newton-blockchain/newton-blockchain.github.io/master/newton-test.global.config.json -o /var/db/ton/newton-testnet-node/etc/global_config.json

After this file you should have a file /var/db/ton/newton-testnet-node/etc/global_config.json with some data in it. Please do not edit this file, there is nothing what you as node operator need to change there.

Result

We have downloaded global configuration file for our node, now we can generate local configuration.

Chapter 3: Initialize local configuration

Next step is to create local configuration using global configuration file downloaded in previous step.

sudo -u tond /usr/local/opt/ton/bin/validator-engine --global-config /var/db/ton/newton-testnet-node/etc/global_config.json --db /var/db/ton/newton-testnet-node/db --ip IP:PORT --logname /var/db/ton/newton-testnet-node/log/init.log

Replace IP and PORT with fixed public IP of your node and PORT number of your choice, I would advise to use high port number beginning from 20000.

This command will run and exit without any output but if execution was success then local configuration file /var/db/ton/newton-testnet-node/db/config.json would be generated. If the file is not there then something went wrong, check log files.

Important: Please note that the command used here is pretty much identical to the one that is used to run actual node. If the local configuration file already exists then you will start a node. (command will not exit automatically). This is not a problem, just break it off (ctrl_c).

Result

We have generated a local configuration file /var/db/ton/newton-testnet-node/db/config.json for our node. This file contains quite a few things: our IP address, network port, generated adnl address etc. This is the holy grail of our node.

Essentially, this is it: your machine can operate as a network node, you can try and start it by running:

sudo -u tond /usr/local/opt/ton/bin/validator-engine --global-config /var/db/ton/newton-testnet-node/etc/global_config.json --db /var/db/ton/newton-testnet-node/db --logname /var/db/ton/newton-testnet-node/log/node.log

If all went well then this command should stay in foreground as long as you do not kill it.

But does it work?

Well, if process stays in foreground and does not exit immediately then this is already good news. You really need to check log files to see what is going on. There can be many messages, please see common node errors section of FAQ for some of the most common ones.

Depending on the state of the net you are trying to connect to it can take quite a while to even find state, let alone sync. It can easily take days for a full node to completely sync even on fastest internet line with very quick hardware.

Here are some other indications (besides logs) that your node does something:

  • validator-engine process uses CPU: anything over 20% of a single core on a modern CPU means that your node is doing something and not just idling.
  • Node generates network traffic: Anything over 1mbps of summetric up/down UDP traffic means that something is going on.
  • database directory (/var/db/ton/newton-testnet-node/db in our case) is growing.

Automate the node

It is at this step that I advise you to automate start/stop of the node as a system service, I strongly advise to utilize daemontools do do that, please consult Chapter 2 of FreeBSD Telegram Open Network installation guide.

Chapter 4: Node log files

It is important to understand architecture of validator-engine in order to understand log file structure: validator-engine acts as a main process that takes the command arguments, loads configs and then spawns children processes / threads that do actual job. Each process / thread writes into it's own log file.

The log file you specify with --logname parameter points to log file used by main process, each thread writes it's own log file that has .threadN.log appended to name of main log file. Where N is number of the thread.

As a result, during initiation two logs will be made:

  • /var/db/ton/newton-testnet-node/log/init.log that ideally should be empty
  • /var/db/ton/newton-testnet-node/log/init.log.thread1.log that will contain information from the thread that actually made the local configuration

Chapter 5: Configuring node cli client-server

Why CLI client

[TODO] Describe what the client is used for.

Prerequesites / assumptions

  1. Completion of chapters 1-3 of this guide with the result of working node.
  2. Ability to control the node using daemontools

We also assume that you chose to create a dedicated user tond and initialized the configuration using that user.

Architecture

Transport

CLI functionality is client-server architecture where role of the client is played by binary validator-engine-console and server is the same validator-engine process that runs the node.

Security

Security is based on PKI architecture by utilizing private/public key pairs for both server and clients. Thus, the absolute minimum configuration requires two keypairs: server and client.

Step 1: generation and installation of PKI keypairs

Please see Generation of PKI keypairs for TON for general information on how keypairs are generated.

Server

Each server should have it's own keypair, thus this step is needed for every server instance.

Change into your home directory and execute:

/usr/local/opt/ton/bin/generate-random-id --mode keys --name newton-testnet-node-server

Record the Hex and Base64 representations of generated public key. please see Generation of PKI keypairs for TON for more info.

Install the server private key file into keyring storage of the node instance:

sudo cp newton-testnet-node-server /var/db/ton/newton-testnet-node/db/keyring/##HEX_SERVER_KEY##
sudo chown tond:ton /var/db/ton/newton-testnet-node/db/keyring/##HEX_SERVER_KEY##

Attention: Please make sure to insert proper HEX(!!) public key representation into the command above.

Server public key file newton-testnet-node-server.pub will be used by validator-engine-console and hense should be placed on where it is accesible by validator-engine-console (possibly other machines).

Client

This step should be done only if you do not have a client keypair already. You can reuse same client keypair on different servers, this is identical to ssh keys.

Change into your home directory and execute:

/usr/local/opt/ton/bin/generate-random-id --mode keys --name ton-client

Record the Hex and Base64 representations of generated public key. please see Generation of PKI keypairs for TON for more info.

Client private key file ton-client will be used by validator-engine-console and hense should be placed on where it is accesible by validator-engine-console (possibly other machines).

Step 2: configuration of CLI server in the node

Stop the node

sudo svc -d /var/service/newton-testnet-node

Edit local configuration file

In this step we will tell our node that it should start cli listener, to do so we need to edit local configuration file /var/db/ton/newton-testnet-node/db/config.json.

Attention: Please backup your local configuration file before changing it.

You need to replace control section that is by default empty and looks like this:

"control" : [
],

With this:

"control" : [
  { 
	"id" : "##BASE64_SERVER_KEY##",
    "port" : ##CONTROL_PORT##,
    "allowed" : [
      { 
		"id" : "##BASE64_CLIENT_KEY##",
        "permissions" : 15
      }
    ]
  }
],

Attention: Please make sure to insert proper BASE64(!!) public key representations into the structure above. Also set a port on which to listen for cli connections.

You can also use script mkcontrol.sh. This script takes three arguments:

  • HEX_SERVER_KEY because hex is shell safe....
  • HEX_CLIENT_KEY because hex is shell safe....
  • CONTROL_PORT is a TCP port the node will listen to for control connections.

And will return a proper JSON structure.

Test local configuration file JSON syntax

Using python json.tool module we can validate if our json file is valid, run:

sudo cat /var/db/ton/newton-testnet-node/db/config.json | python -m json.tool

If all is allright then it will show you contents of this file (succesful parse), if there are some errors it will tell you so.

Start the node

sudo svc -u /var/service/newton-testnet-node

Test cli client connection

/usr/local/opt/ton/bin/validator-engine-console -k client -p newton-testnet-node-server.pub -a ##NODE_IP##:##CONTROL_PORT## [TODO]: More info

Chapter 6: Configuring liteserver and client

Why CLI client

[TODO] Describe what the lite server is used for.

Prerequesites / assumptions

  1. Completion of chapters 1-3 of this guide with the result of working node.
  2. Ability to control the node using daemontools

We also assume that you chose to create a dedicated user tond and initialized the configuration using that user.

Architecture

Transport

Lite server functionality is client-server architecture where role of the client is played by binary lite-client and server is the same validator-engine process that runs the node.

Security

Security is based on PKI architecture by utilizing private/public key pairs for server. In difference to console Lite Server does not authenticate the clients and thus no client key is required.

Step 1: generation and installation of server PKI keypair

Please see Generation of PKI keypairs for TON for general information on how keypairs are generated.

Server

Each server should have it's own keypair, thus this step is needed for every server instance.

Change into your home directory and execute:

/usr/local/opt/ton/bin/generate-random-id --mode keys --name newton-testnet-node-liteserver

Record the Hex and Base64 representations of generated public key. please see Generation of PKI keypairs for TON for more info.

Install the liteserver private key file into keyring storage of the node instance:

sudo cp newton-testnet-node-liteserver /var/db/ton/newton-testnet-node/db/keyring/##HEX_SERVER_KEY##
sudo chown tond:ton /var/db/ton/newton-testnet-node/db/keyring/##HEX_SERVER_KEY##

Attention: Please make sure to insert proper HEX(!!) public key representation into the command above.

Server public key file newton-testnet-node-liteserver.pub will be used by lite-client and hense should be placed on where it is accesible by lite-client (possibly other machines).

Step 2: configuration of liteserver in the node

Stop the node

sudo svc -d /var/service/newton-testnet-node

Edit local configuration file

In this step we will tell our node that it should start liteserver listener, to do so we need to edit local configuration file /var/db/ton/newton-testnet-node/db/config.json.

Attention: Please backup your local configuration file before changing it.

You need to replace liteserver section that is by default empty and looks like this:

"liteservers" : [
],

With this:

"liteservers" : [
  {
	"id" : "##BASE64_SERVER_KEY##",
    "port" : ##CONTROL_PORT##
  }
],

Attention: Please make sure to insert proper BASE64(!!) public key representation into the structure above. Also set a port on which to listen for cli connections.

You can also use script mklite.sh. This script takes two arguments:

  • HEX_LITESERVER_KEY because hex is shell safe....
  • LITESERVER_PORT is a TCP port the node will listen to for liteserver connections.

And will return a proper JSON structure.

Test local configuration file JSON syntax

Using python json.tool module we can validate if our json file is valid, run:

sudo cat /var/db/ton/newton-testnet-node/db/config.json | python -m json.tool

If all is allright then it will show you contents of this file (succesful parse), if there are some errors it will tell you so.

Start the node

sudo svc -u /var/service/newton-testnet-node

Test cli client connection

/usr/local/opt/ton/bin/lite-client -p newton-testnet-node-liteserver.pub -a ##NODE_IP##:##CONTROL_PORT## [TODO]: More info

Generation of PKI keypairs for TON

PKI keypars for ton are generated using /usr/local/opt/ton/bin/generate-random-id executable, each generation results in two files and two strings:

  • Private key file and Public key file
  • Hex public key representation and Base64 public key representation those strings contain the same information as Public key file, just in a different encoding.

/usr/local/opt/ton/bin/generate-random-id takes two arguments:

  • --mode keys that tells that we wish to generate a new PKI keypair.
  • --name that tells under which name to save the output. This can be any string.

Generate the key

Change into your home directory and execute:

/usr/local/opt/ton/bin/generate-random-id --mode keys --name acme

This comand will output a single line with two strings, it will look something like:

F20F63AFEF12926D0B0A023C8AA8217BDFF731E60EEE236D3D21C535E7F88F9C 8g9jr+8Skm0LCgI8iqghe9/3MeYO7iNtPSHFNef4j5w=

but of course your strings will be different.

The first string F20F63AFEF12926D0B0A023C8AA8217BDFF731E60EEE236D3D21C535E7F88F9C is Hex public key representation, second string 8g9jr+8Skm0LCgI8iqghe9/3MeYO7iNtPSHFNef4j5w= is Base64 public key representation. Please record this information as we will need it later

You will also find two files in your directory: acme which is a Private key file and acme.pub which is a Public key file.

[TODO]: Can Base64 and Hex representations be recreated from public key file? How?