Run a liteserver

Run a liteserver node with MyTonCtrl

Objective

This guide describes how to set up a liteserver using MyTonCtrl.

Prerequisites

• A server meeting the minimal hardware requirements
• An OS meeting the requirements

Step 1: Prepare environment

1.1 Minimal hardware requirements

• 16-core CPU
• 64 GB RAM
• At least 1 TB of NVMe Gen4+ SSD storage (Enterprise grade preferred) or Provisioned 64k+ IOPS storage.
• 1 Gbit/s symmetric connectivity (both inbound and outbound), ~16 TB/month at peak load
• Fixed (static) public IP address

1.2 OS and system requirements

• Ubuntu 22.04/24.04 LTS or Debian 11/12
• Python 3.10 or higher

1.3 Subscribe to official channels

Subscribe and follow the announcements provided for liteservers in the following Telegram channels:

Channel	Network
@tonstatus	TON Mainnet
@testnetstatus	TON Testnet

1.4 Free space requirements

Ensure sufficient free disk space for the initial download and extraction of the database dump.

• The /tmp directory requires over 235 GB of free space.
• The /var directory requires over 740 GB of free space.

1.5 Prepare the operator account

To create a dedicated operator user and switch to it before installing MyTonCtrl:

• Create a non-root user:

# Create a non-root operator user
sudo adduser <USERNAME>
sudo usermod -aG sudo <USERNAME>

Define placeholders:

• <USERNAME> - name of the non-root operator user.

• <SERVER_IP> - public IP address of the server.

• <SSH_PORT> - custom SSH port number configured in Step 1.7.

• Switch to the new operator account by reconnecting via SSH:

# Option 1: Reconnect using the standard port
exit
ssh <USERNAME>@<SERVER_IP>

# Option 2: Reconnect using the custom SSH port
exit
ssh <USERNAME>@<SERVER_IP> -p <SSH_PORT>

1.6 Benchmark server performance

Before installing, verify that the server meets performance requirements. Inadequate disk or network performance is the most common cause of validator instability.

1.6.1 Network latency

Check latency to TON beacon nodes. Expect approximately 50 milliseconds to the nearest beacon and up to 300 milliseconds to the farthest:

ping beacon-eu-01.toncenter.com -c 6
ping beacon-apac-01.toncenter.com -c 6

1.6.2 Disk IOPS

Install fio and run a random read/write benchmark:

sudo apt install -y fio
fio --randrepeat=1 --ioengine=psync --direct=1 --gtod_reduce=1 --name=tlstest --bs=4k --iodepth=1 --size=40G  --readwrite=randrw --numjobs=1 --group_reporting --filename=/var/ton-work/testfile --time_based=1 --runtime=60
rm /var/ton-work/testfile

Minimum acceptable results:

Metric	Minimum
Read	10k IOPS
Write	10k IOPS

1.6.3 Network bandwidth

Verify network throughput with speedtest-cli:

sudo apt install -y speedtest-cli
speedtest-cli

Ensure download and upload speeds meet the 1 Gbit/s requirement.

1.7 Harden server security

SSH hardening

Apply the following SSH configuration changes in /etc/ssh/sshd_config:

• Enable key-based authentication and disable password login:

PasswordAuthentication no
PubkeyAuthentication yes

• Disable root login:

PermitRootLogin no

• Change the default SSH port:

Port <SSH_PORT>

• Restrict SSH access to specific IP addresses using the Match Address directive:

Match Address <ALLOWED_IP>
  AllowUsers <USERNAME>

Define placeholders:

• <SSH_PORT> - a custom non-default port number (for example, 2222).
• <ALLOWED_IP> - IP address or subnet permitted to connect via SSH.
• <USERNAME> - name of the operator user.

Restart the SSH service after changes:

sudo systemctl restart sshd

Firewall configuration

Enable the firewall and allow only the SSH port. The node UDP port and liteserver port are added after installation in open the node UDP port and the liteserver port.

sudo apt install -y ufw
sudo ufw allow <SSH_PORT>
sudo ufw enable
sudo ufw status

Additional security measures

• Use a unique, strong password for the root user.

• Set a GRUB bootloader password to prevent unauthorized boot modifications.

• Enable Fail2ban for SSH brute-force protection:

  sudo apt install -y fail2ban
  sudo systemctl enable fail2ban
  sudo systemctl start fail2ban
  

• Configure two-factor authentication for SSH using libpam-google-authenticator or a similar PAM module.

Step 2: Liteserver installation

The installation process consists of two stages (in total, this can take up to three hours):

• Download DB damp and install the liteserver
• Final synchronization of the liteserver

2.1 Download DB damp and install the liteserver

2.1.1 Install prerequisites and download installer (MyTonCtrl)

  sudo apt update
  sudo apt install -y curl wget git ca-certificates python3-pip
  wget https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/scripts/install.sh

2.1.2 Run liteserver installation

Run the installer from the operator account with sudo so it can create system users and services:

Mainnet

ARCHIVE_TTL=2592000 && STATE_TTL=86400 && sudo -v && nohup sudo bash install.sh -m liteserver -n mainnet -d > mytonctrl_installation.log 2>&1 &

Installation runs in the background.

Monitor the progress using the following command:

tail -f mytonctrl_installation.log

During the download process, the log contains entries like the following:

[#cf6515 8.5GiB/218GiB(3%) CN:8 DL:242MiB ETA:14m44s]
[#cf6515 8.7GiB/218GiB(4%) CN:8 DL:247MiB ETA:14m27s]
[#cf6515 9.0GiB/218GiB(4%) CN:8 DL:252MiB ETA:14m7s]

Upon successful completion of the installation, the following line appears in the log:

[5/5] Mytonctrl installation completed

2.2 Final synchronization of liteserver

This process starts automatically after installation and can take from one to several hours depending on server performance.

Monitor the progress using MyTonCtrl:

mytonctrl --cmd status

Check the Local validator initial sync status field. The value indicates how old the last imported block was. On a fully synchronized node, this value should be less than 20 seconds.

2.2.1 Open the node UDP port and the liteserver port

At this stage, the node UDP port and liteserver port should be opened to make the archive liteserver available for syncing blocks from other nodes.

Identify the node UDP port and liteserver port from the config.json file:

sudo grep -A5 '"addrs"' -n /var/ton-work/db/config.json | grep '"port"' | head -1
sudo grep -A5 '"liteservers"' -n /var/ton-work/db/config.json | grep '"port"' | head -1

Update security groups or configure ufw on bare-metal hosts:

sudo ufw allow <NODE_UDP_PORT>
sudo ufw allow <LITESERVER_PORT>
sudo ufw status

Define placeholders:

• <NODE_UDP_PORT> - UDP port of the validator engine.
• <LITESERVER_PORT> - TCP port of the liteserver.

Step 3: Maintenance

3.1 Set up alerting

Set up alerting in MyTonCtrl to get a notification of critical issues with the liteserver. For more information, see MyTonCtrl private alerting bot.

3.2 Set up monitoring

Set up monitoring dashboards for RAM, disk, network, CPU usage, and other metrics.

For system-level metrics, integrate Prometheus with node_exporter with MyTonCtrl.

It is critical to use the monitoring system to:

• monitor server stability
• monitor synchronization parameters
• check for memory leaks

For technical assistance, contact @mytonctrl_help_bot.

3.3 Perform software updates

Follow the @tonstatus channel, turn on notifications, and be prepared for urgent updates if needed.

Update the node software and MyTonCtrl:

mytonctrl --cmd "update master"
mytonctrl --cmd "upgrade master"

These commands will check for new versions of the TON node binaries and MyTonCtrl, download them, and apply the updates.

Troubleshooting

Monitor logs

To see detailed logs of synchronization process, increase the log verbosity from the MyTonCtrl console:

mytonctrl --cmd "installer set_node_argument --verbosity 3"

Then follow the log file from a separate terminal:

tail -f /var/ton-work/log*

Set verbosity back to 1 after checking logs to avoid excessive disk I/O overhead:

mytonctrl --cmd "installer set_node_argument --verbosity 1"

Performance issues

Logs containing “Importing archive for masterchain seqno #… from net” accompanied by timeout errors indicate insufficient storage performance. Ensure the disk meets the IOPS requirements listed in Minimal hardware requirements.

To verify disk and system performance, run the built-in mytonctrl benchmark:

1. Stop the validator service:

sudo systemctl stop validator.service

2. Run the benchmark:

mytonctrl --cmd benchmark

For stable liteserver operation, the benchmark score should be greater than 70%.

Support

For technical assistance, join the official support channel: @ton_node_help.

See also

• TON node types
• Run a node with MyTonCtrl