Run an archive liteserver

This guide describes how to set up an archive liteserver using MyTonCtrl, with ZFS for storage compression and snapshots.

An archive liteserver node stores the entire block history of the TON blockchain. For applications requiring access to historical data, such as blockchain explorers or indexers, running an archive liteserver node is the recommended approach.

Prerequisites

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

Step 1: Prepare environment

1.1 Minimal hardware requirements

Running an archive liteserver requires large storage and network capacity:

• 16-core CPU
• 128 GB RAM
• NVMe Gen4+ SSD storage (Enterprise grade preferred), sustaining at least 64,000 provisioned IOPS:
  • at least 16 TB with ZFS lz4 compression enabled, or
  • at least 20 TB without compression
• 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
• Open Files Limit must be set above 4,000,000

1.3 Subscribe to official channels

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

1.4 Install ZFS and prepare volume

Archive nodes benefit from ZFS due to its native compression and snapshot capabilities.

1.4.1 Install ZFS

sudo apt update
sudo apt install -y zfsutils-linux

1.4.2 Verify physical block size

For NVMe drives, ZFS pool sector size must align with the drive's physical block size to avoid performance degradation. Most modern NVMe drives use 4K blocks. Verify the physical block size:

# Replace nvme0n1 with the target device name
cat /sys/block/nvme0n1/queue/physical_block_size

If the result is 4096, the -o ashift=12 parameter must be used during pool creation.

1.4.3 Create a storage pool

Create a ZFS pool named data. Use -o ashift=12 for 4K blocks (standard for most NVMe drives):

# Replace <DISK> with the device identifier (e.g., /dev/nvme1n1)
sudo zpool create -o ashift=12 data <DISK>

There,

• <DISK> is the target disk device identifier, e.g., /dev/nvme1n1;
• <DISK1>, <DISK2>, and <DISK3> are additional disk device identifiers.

1.4.4 Enable compression

Enable lz4 compression to save disk space with minimal CPU overhead:

sudo zfs set compression=lz4 data

1.4.5 Create dataset and mount point

Create the dataset for TON data and set the mount point to /var/ton-work:

sudo zfs create data/ton-work
sudo zfs set mountpoint=/var/ton-work data/ton-work

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 --refill_buffers --buffer_compress_percentage=0
rm /tmp/ton-testfile

The --refill_buffers and --buffer_compress_percentage=0 flags force incompressible data. Without them, LZ4 on the data/ton-work dataset collapses fio's zero-filled writes and reports IOPS far above what the archive import sustains.

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: Archive liteserver installation

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

• Download historical blocks from TON Storage and install the archive liteserver
• Import downloaded data into the archive liteserver database
• Final synchronization of the archive liteserver

2.1 Download historical blocks from TON Storage and install the archive liteserver

This process can take from one to several days depending on the internet connection speed.

2.1.1 Install prerequisites and download MyTonCtrl installer

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 archive liteserver installation

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

sudo -v && nohup sudo bash install.sh -m liteserver -n mainnet --archive > 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:

[info]    24.04.2026, 14:26:47.609 (UTC)  <ThreadPoolExecutor-0_3>STARTING DOWNLOADING e88e7e805dfa16dc6e7d3864fcc00159a1ee70edde7b421428783c2164453875
[info]    24.04.2026, 14:27:07.611 (UTC)  <ThreadPoolExecutor-0_3>DOWNLOADING e88e7e805dfa16dc6e7d3864fcc00159a1ee70edde7b421428783c2164453875 0% (0.0 / 4296.493726 MB), speed: 0.0 MB/s
[info]    24.04.2026, 14:27:07.623 (UTC)  <ThreadPoolExecutor-0_2>DOWNLOADING 7683b6bc2c19e007fc6d363dc233ff9a405c0fee7533c2904c06943f759c155f 3% (130.766577 / 4295.81461 MB), speed: 15.078028 MB/s
[info]    28.04.2026, 11:43:00.687 (UTC)  <ThreadPoolExecutor-0_1>DOWNLOADING fd41a820efc4f459bb1518c45fcc23023b0a95d9446c683705802bfb9d50a0c9 95% (4072.892954 / 4296.3534 MB), speed: 28.962779 MB/s
[info]    28.04.2026, 11:43:20.700 (UTC)  <ThreadPoolExecutor-0_1>DOWNLOADED fd41a820efc4f459bb1518c45fcc23023b0a95d9446c683705802bfb9d50a0c9

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

[5/5] Mytonctrl installation completed

2.2 Import downloaded data into the archive liteserver database

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

Monitor the progress from the MyTonCtrl console. Open the console:

mytonctrl

At the MyTonCtrl> prompt, run:

MyTonCtrl> status

Check the Local validator initial sync status field. The value indicates how old the last imported block was and should decrease over time.

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

There,

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

2.3 Final synchronization of archive liteserver

This process starts automatically after the importing process finishes and can take from one to several days 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, out-of-sync time stays below 20 seconds.

Step 3: Maintenance

3.1 Set up alerting

Set up alerting in MyTonCtrl to get a notification of critical issues with the archive 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.

It is critical to use the monitoring system to:

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

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

For technical assistance, contact @mytonctrl_help_bot.

3.3 Perform software updates

Before performing updates, create a ZFS snapshot of the data. This allows a quick rollback if the update process fails or corrupts the database.

sudo zfs snapshot data/ton-work@before-update-$(date +%Y-%m-%d)

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.

Once the update is verified as successful and the node is running correctly, delete the snapshot to reclaim disk space.

3.4 ZFS snapshots

ZFS creates snapshots for easy rollbacks if data corruption occurs.

Create a snapshot

Snapshots can be created under a unique identifier without stopping the node :

sudo zfs snapshot data/ton-work@<SNAPSHOT_NAME>

List snapshots

To see all existing snapshots for the data/ton-work dataset:

sudo zfs list -t snapshot data/ton-work

Roll back to a snapshot

# Stop the service
sudo systemctl stop validator.service

# Roll back to the snapshot
sudo zfs rollback data/ton-work@<SNAPSHOT_NAME>

# Start the service
sudo systemctl start validator.service

Delete a snapshot

Delete the snapshot when it is no longer needed:

sudo zfs destroy data/ton-work@<SNAPSHOT_NAME>

3.5 Archive ZFS snapshots

Creating a snapshot is instantaneous and occurs on the same physical disks where the data is stored. To protect against hardware failure, export the snapshots to external storage or a remote server using zfs send.

Export a snapshot to a file

Before exporting, estimate the size of the snapshot:

sudo zfs send -pc -nv data/ton-work@<SNAPSHOT_NAME>

Expected output:

full send of data/ton-work@<SNAPSHOT_NAME> estimated size is 4.07T
total estimated size is 4.07T

To save the snapshot to a file, use the -c flag to preserve LZ4 compression. Without it, the file expands to the uncompressed size of the dataset:

# Ensure the destination directory exists and has enough free space!
sudo zfs send -c data/ton-work@<SNAPSHOT_NAME> > <BACKUP_PATH>

Example destination path on the external storage: /mnt/backup/backup_ton_work.zfs

Transfer a snapshot via SSH

Stream a snapshot directly to a remote ZFS-enabled server:

sudo zfs send -c data/ton-work@<SNAPSHOT_NAME> | ssh <REMOTE_USER>@<REMOTE_HOST> "sudo zfs recv <REMOTE_POOL>/ton-work"

There,

• <REMOTE_USER> is the username on the remote host;
• <REMOTE_HOST> is an IP address or hostname of the remote host;
• <REMOTE_POOL> is the name of the remote ZFS pool.

Troubleshooting

Monitor import logs

To see detailed logs of the block import 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*

Expected log entries:

[ 2][t49][2025-01-01 00:00:00.632][import-db-slice-local.cpp:629][!archiveimport] Imported archive in 2.75s : mc_seqno=761229 shard_seqno=761229

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

Support

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

See also

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