Run a liteserver

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

Unlike the archive liteserver, a regular liteserver node does not store the entire block history of the TON blockchain. Running a non-archive liteserver node is recommended for applications that do not require access to historical data, such as most dApps.

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), sustaining at least 64,000 provisioned IOPS
• 1 Gbit/s symmetric connectivity (both inbound and outbound), ~16 TB/month at peak load
• Fixed (static) public IP address

echo performance | sudo tee /sys/module/pcie_aspm/parameters/policy

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:

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:

1. Create a non-root user:

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

2. Switch to the new operator account by reconnecting via SSH:

   Standard port

   Custom SSH port

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

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 node 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=/tmp/ton-testfile --time_based=1 --runtime=60
rm /tmp/ton-testfile

The minimum acceptable result is 10,000 IOPS for both read and write operations. If disk performance falls below these thresholds, the liteserver may fail to keep up with network traffic. Upgrade storage before proceeding.

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

Apply security hardening steps before exposing the server to the network:

• SSH hardening
• Firewall configuration
• Additional security measures

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, e.g., to 2222:

  Port <SSH_PORT>

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

  Match Address <ALLOWED_IP>
    AllowUsers <USERNAME>

  There, <USERNAME> is the 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 dump and install the liteserver
• Final synchronization of the liteserver

2.1 Download DB dump 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:

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

These environment variables control data retention:

• ARCHIVE_TTL=2592000: Keep archive data for 30 days (2,592,000 seconds)
• STATE_TTL=86400: Keep state data for 1 day (86,400 seconds)

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 from the MyTonCtrl console. Open the console:

mytonctrl

At the MyTonCtrl> prompt, run:

MyTonCtrl> status

While initial sync continues, the Local validator initial sync status field reports how old the last imported block was, decreasing over time. Once initial sync completes, that line disappears and freshness is reported by the Local validator out of sync field. On a fully synchronized node, the out-of-sync time stays below 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 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

There,

• <NODE_UDP_PORT> is the UDP port of the validator engine;
• <LITESERVER_PORT> is the 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

Update the node software and MyTonCtrl from the console. Open the console:

mytonctrl

At the MyTonCtrl> prompt, update MyTonCtrl to the tip of the master branch:

MyTonCtrl> update master

The console exits when update finishes. Reopen it with mytonctrl and upgrade the TON node binaries to the tip of the master branch:

MyTonCtrl> upgrade master

These commands check for new versions of MyTonCtrl and the TON node binaries, download them, and apply the updates. The update process may cause temporary node downtime as the binaries are replaced and services are restarted.

Troubleshooting

Monitor logs

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

mytonctrl

At the MyTonCtrl> prompt, run:

MyTonCtrl> 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. At the MyTonCtrl> prompt, run:

MyTonCtrl> 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, since the benchmark refuses to run while it is active:

   sudo systemctl stop validator.service

2. Open the MyTonCtrl console:

   mytonctrl

   At the MyTonCtrl> prompt, run:

   MyTonCtrl> benchmark

   The benchmark spins up a local test network and requires uv. If uv is not installed, the console prompts to install it. For stable liteserver operation, the reported Avg TPS and Avg blocks/s should each reach at least 70% of their expected values.

3. Restart the validator service once the benchmark finishes:

   sudo systemctl start validator.service

Manual DB dump download

A manual download of the database dump is required if it does not download automatically. Download a pre-built database dump instead of syncing from peers. Check the dump index for available snapshots.

1. Install aria2 and plzip if not already present:

   sudo apt install -y aria2 plzip

2. Stop the validator and MyTonCore services:

   sudo systemctl stop mytoncore.service
   sudo systemctl stop validator.service

3. Download and extract the dump:

   cd /var/ton-work/
   aria2c -x 16 https://dump.ton.org/dumps/latest.tar.lz
   mv /var/ton-work/db /var/ton-work/db_old
   mkdir /var/ton-work/db
   plzip -d -c /var/ton-work/latest.tar.lz | tar -xvf - -C /var/ton-work/db

4. Restore configuration and keys from the original database:

   cp /var/ton-work/db_old/config.json /var/ton-work/db/config.json
   cp -r /var/ton-work/db_old/keyring /var/ton-work/db/keyring
   sudo chown -R validator:validator /var/ton-work/db

5. Start the services again:

   sudo systemctl start validator.service
   sudo systemctl start mytoncore.service

Support

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

See also

• Run an archive liteserver node with MyTonCtrl
• Run a validator node with MyTonCtrl
• Set up a node with MyTonCtrl
• TON node types