From a08fdf3f57f42ad5b7447ef135d2f0285bbb4650 Mon Sep 17 00:00:00 2001 From: ATrump Date: Mon, 4 May 2026 17:51:27 -0300 Subject: [PATCH 1/9] feat(nodes): add guide for running TON archive liteserver Created a new guide for setting up an archive node in liteserver mode. --- docs.json | 1 + .../nodes/cpp/run-archive-liteserver.mdx | 265 ++++++++++++++++++ 2 files changed, 266 insertions(+) create mode 100644 ecosystem/nodes/cpp/run-archive-liteserver.mdx diff --git a/docs.json b/docs.json index e84345fd8..fe3d8080a 100644 --- a/docs.json +++ b/docs.json @@ -305,6 +305,7 @@ "pages": [ "ecosystem/nodes/cpp/setup-mytonctrl", "ecosystem/nodes/cpp/run-validator", + "ecosystem/nodes/cpp/run-archive-liteserver", "ecosystem/nodes/cpp/integrating-with-prometheus", "ecosystem/nodes/cpp/setup-mylocalton", { diff --git a/ecosystem/nodes/cpp/run-archive-liteserver.mdx b/ecosystem/nodes/cpp/run-archive-liteserver.mdx new file mode 100644 index 000000000..6babae85c --- /dev/null +++ b/ecosystem/nodes/cpp/run-archive-liteserver.mdx @@ -0,0 +1,265 @@ +--- +title: "Run an archive liteserver" +description: "Learn how to set up and run a TON archive node in liteserver mode" +--- + +import { Aside } from '/snippets/aside.jsx'; + +## Overview + +An **archive node** is a type of full node that stores the entire block history of the TON blockchain. If you are building a blockchain explorer, an indexer, or any application requiring access to historical data, running an archive node is the recommended approach. + +This guide explains how to set up an archive node in **liteserver mode** using MyTonCtrl and ZFS for efficient storage management. + +## Step 1: Prepare environment + +### 1.1 Minimal hardware requirements + +Running an archive node requires significant storage and network resources. + +- **CPU**: 16-core CPU +- **RAM**: 128 GB RAM +- **Storage**: At least 16TB of SSD storage, 20TB if you will not use ZFS with compression (NVMe recommended), or Provisioned 64k+ IOPS storage +- **Network**: 1 Gbit/s symmetric connectivity (both inbound and outbound) +- **Traffic**: ~16 TB/month at peak load +- **IP**: Fixed (static) public IP address + + + +### 1.2 OS and system requirements + +- **Supported OS**: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, or Debian 11. +- **Open Files Limit**: Must be set above 400,000. + +## Step 2: Install ZFS and prepare volume + +Archive nodes benefit significantly from ZFS due to its native compression and snapshot capabilities. + +### 2.1 Install ZFS + +```bash +sudo apt update +sudo apt install -y zfsutils-linux +``` + +### 2.2 Verify physical block size + +For NVMe drives, it is critical to align the ZFS pool's sector size with the drive's physical block size to avoid significant performance degradation. Most modern NVMe drives use 4K blocks. Verify your drive's physical block size: + +```bash +# Replace nvme0n1 with your device name +cat /sys/block/nvme0n1/queue/physical_block_size +``` + +If the result is `4096`, you must use the `-o ashift=12` parameter during pool creation. + +### 2.3 Create a storage pool + +Create a ZFS pool named `data`. Use `-o ashift=12` for 4K blocks (standard for most NVMe drives): + + + ```bash Single drive + # Replace with your device identifier (e.g., /dev/nvme1n1) + sudo zpool create -o ashift=12 data + ``` + + ```bash Multiple drives (Stripe) + # Combine multiple disks to increase capacity and performance + sudo zpool create -o ashift=12 data + ``` + + + + +### 2.4 Enable compression + +We recommend enabling `lz4` compression to save disk space with minimal CPU overhead: + +```bash +sudo zfs set compression=lz4 data +``` + +### 2.5 Create dataset and mountpoint + +Create the dataset for TON data and set the mount point to `/var/ton-work`: + +```bash +sudo zfs create data/ton-work +sudo zfs set mountpoint=/var/ton-work data/ton-work +``` + +## Step 3: Installation via MyTonCtrl + +### 3.1 Prepare the operator account + +If you still need a dedicated operator, create and switch to it before installing MyTonCtrl: + +```bash +sudo adduser +sudo usermod -aG sudo +# reconnect as the new user +ssh @ +``` + +### 3.2 Install MyTonCtrl + +Run the installer from the operator account with `sudo` so it can create system users and services: + +```bash +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 +sudo bash install.sh +``` + +During installation, select the following options: +1. **Mode**: Select `liteserver`. +2. **Network**: Select `mainnet` (or `testnet` if required). +3. **Archive blocks**: When prompted *"Do you want to download archive blocks via TON Storage?"*, enter `1` (Yes). + + + +## Step 4: Verify and monitor + +### 4.1 Monitor installation progress + +Since the installation runs in the background, you can track the download and setup progress by monitoring the installation log file in the directory where you ran the script: + +```bash +tail -f mytonctrl_installation.log +``` + +This is especially useful for tracking the progress of downloading archive blocks via TON Storage, which can take anywhere from 12 hours to several days depending on your internet connection speed. + +### 4.2 Check synchronization status + +Once the initial setup is complete, you can use the MyTonCtrl console to check the node's synchronization status: + +```sh +mytonctrl +MyTonCtrl> status +``` + +Check the field **Local validator initial sync status**. The value indicates how many blocks are left to sync. + +### 4.3 Verify file ownership + +Ensure the node directories have correct permissions: + +```bash +# Database owner should be the validator user +sudo chown -R validator:validator /var/ton-work/db + +# Keys owner should be the user who installed MyTonCtrl +sudo chown -R : /var/ton-work/keys +``` + +## Step 5: Troubleshooting and Maintenance + +### 5.1 Monitoring import logs + +To see detailed logs of the block import process, increase the log verbosity from the MyTonCtrl console: + +```sh +MyTonCtrl> installer set_node_argument --verbosity 3 +``` + +Then follow the log file from a separate terminal: + +```bash +tail -f /var/ton-work/log* +``` + +You should see entries like: + +```text +[ 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 +``` + + + +### 5.2 ZFS Snapshots + +ZFS allows you to create snapshots for easy rollbacks if data corruption occurs. + +#### Create a snapshot +Snapshots can be created **without** stopping the node: + +```bash +sudo zfs snapshot data/ton-work@backup-date +``` + +#### Roll back to a snapshot +To restore data from a snapshot, you **must** stop the validator service first: + +```bash +# Stop the service +sudo systemctl stop validator.service + +# Roll back to the snapshot +sudo zfs rollback data/ton-work@backup-date + +# Start the service +sudo systemctl start validator.service +``` + +### 5.3 Archiving ZFS snapshots + +Creating a snapshot is instantaneous and happens on the same physical disks where your data is stored. To protect against hardware failure, you should export your snapshots to external storage or a remote server using `zfs send`. + +#### Exporting a snapshot to a file + +Before exporting, estimate the size of the snapshot: + +```bash +sudo zfs send -pc -nv data/ton-work@backup-date +``` + +Example output: +```text +full send of data/ton-work@backup-date 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 will be significantly larger): + +```bash +sudo zfs send -c data/ton-work@backup-date > /external_storage/backup_ton_work.zfs +``` + + + +#### Transferring a snapshot via SSH + +You can stream a snapshot directly to a remote ZFS-enabled server: + +```bash +sudo zfs send -c data/ton-work@backup-date | ssh user@remote_host "sudo zfs recv remote_data/ton-work" +``` + +### 5.4 Performance issues + +If you see logs like `Importing archive for masterchain seqno #... from net` accompanied by timeout errors, it likely indicates that your storage performance is insufficient to keep up with the block import process. Ensure your disk meets the IOPS requirements listed in [section 1.1](#step-1-prepare-environment). + +## Support + +For technical assistance, join the official support channel: [@ton_node_help](https://t.me/ton_node_help). + +## See also + +- [TON node types](/ecosystem/nodes/overview) +- [Run a node with MyTonCtrl](/ecosystem/nodes/cpp/setup-mytonctrl) From 345cde557fe6fc8c4d5990c2f874980f7a5b7d89 Mon Sep 17 00:00:00 2001 From: ATrump Date: Wed, 6 May 2026 17:55:17 -0300 Subject: [PATCH 2/9] Add ufw section and small fixes --- .../nodes/cpp/run-archive-liteserver.mdx | 56 ++++++++++++------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/ecosystem/nodes/cpp/run-archive-liteserver.mdx b/ecosystem/nodes/cpp/run-archive-liteserver.mdx index 6babae85c..3b2049ead 100644 --- a/ecosystem/nodes/cpp/run-archive-liteserver.mdx +++ b/ecosystem/nodes/cpp/run-archive-liteserver.mdx @@ -1,21 +1,21 @@ --- title: "Run an archive liteserver" -description: "Learn how to set up and run a TON archive node in liteserver mode" +description: "Run an archive liteserver node with MyTonCtrl" --- import { Aside } from '/snippets/aside.jsx'; ## Overview -An **archive node** is a type of full node that stores the entire block history of the TON blockchain. If you are building a blockchain explorer, an indexer, or any application requiring access to historical data, running an archive node is the recommended approach. +An **archive liteserver node** is a type of full node that stores the entire block history of the TON blockchain. If you are building a blockchain explorer, an indexer, or any application requiring access to historical data, running an archive liteserver node is the recommended approach. -This guide explains how to set up an archive node in **liteserver mode** using MyTonCtrl and ZFS for efficient storage management. +This guide explains how to set up an archive liteserver node using MyTonCtrl and ZFS for efficient storage management. ## Step 1: Prepare environment ### 1.1 Minimal hardware requirements -Running an archive node requires significant storage and network resources. +Running an archive liteserver node requires significant storage and network resources. - **CPU**: 16-core CPU - **RAM**: 128 GB RAM @@ -39,7 +39,7 @@ Archive nodes benefit significantly from ZFS due to its native compression and s ### 2.1 Install ZFS -```bash +```sh sudo apt update sudo apt install -y zfsutils-linux ``` @@ -48,7 +48,7 @@ sudo apt install -y zfsutils-linux For NVMe drives, it is critical to align the ZFS pool's sector size with the drive's physical block size to avoid significant performance degradation. Most modern NVMe drives use 4K blocks. Verify your drive's physical block size: -```bash +```sh # Replace nvme0n1 with your device name cat /sys/block/nvme0n1/queue/physical_block_size ``` @@ -60,12 +60,12 @@ If the result is `4096`, you must use the `-o ashift=12` parameter during pool c Create a ZFS pool named `data`. Use `-o ashift=12` for 4K blocks (standard for most NVMe drives): - ```bash Single drive + ```sh Single drive # Replace with your device identifier (e.g., /dev/nvme1n1) sudo zpool create -o ashift=12 data ``` - ```bash Multiple drives (Stripe) + ```sh Multiple drives (Stripe) # Combine multiple disks to increase capacity and performance sudo zpool create -o ashift=12 data ``` @@ -79,7 +79,7 @@ Create a ZFS pool named `data`. Use `-o ashift=12` for 4K blocks (standard for m We recommend enabling `lz4` compression to save disk space with minimal CPU overhead: -```bash +```sh sudo zfs set compression=lz4 data ``` @@ -87,7 +87,7 @@ sudo zfs set compression=lz4 data Create the dataset for TON data and set the mount point to `/var/ton-work`: -```bash +```sh sudo zfs create data/ton-work sudo zfs set mountpoint=/var/ton-work data/ton-work ``` @@ -98,7 +98,7 @@ sudo zfs set mountpoint=/var/ton-work data/ton-work If you still need a dedicated operator, create and switch to it before installing MyTonCtrl: -```bash +```sh sudo adduser sudo usermod -aG sudo # reconnect as the new user @@ -109,7 +109,7 @@ ssh @ Run the installer from the operator account with `sudo` so it can create system users and services: -```bash +```sh 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 @@ -131,7 +131,7 @@ During installation, select the following options: Since the installation runs in the background, you can track the download and setup progress by monitoring the installation log file in the directory where you ran the script: -```bash +```sh tail -f mytonctrl_installation.log ``` @@ -152,7 +152,7 @@ Check the field **Local validator initial sync status**. The value indicates how Ensure the node directories have correct permissions: -```bash +```sh # Database owner should be the validator user sudo chown -R validator:validator /var/ton-work/db @@ -160,6 +160,20 @@ sudo chown -R validator:validator /var/ton-work/db sudo chown -R : /var/ton-work/keys ``` +### 4.4 Open the liteserver port + +Check the port in `/var/ton-work/db/config.json` (within the `liteservers` array). + +Update security groups or configure `ufw` on bare-metal hosts: + +```sh +sudo apt install -y ufw +sudo ufw allow ssh +sudo ufw allow +sudo ufw enable +sudo ufw status +``` + ## Step 5: Troubleshooting and Maintenance ### 5.1 Monitoring import logs @@ -167,12 +181,13 @@ sudo chown -R : /var/ton-work/keys To see detailed logs of the block import process, increase the log verbosity from the MyTonCtrl console: ```sh +mytonctrl MyTonCtrl> installer set_node_argument --verbosity 3 ``` Then follow the log file from a separate terminal: -```bash +```sh tail -f /var/ton-work/log* ``` @@ -186,6 +201,7 @@ You should see entries like: Set verbosity back to `1` after checking logs to avoid excessive disk I/O overhead: ```sh + mytonctrl MyTonCtrl> installer set_node_argument --verbosity 1 ``` @@ -197,14 +213,14 @@ ZFS allows you to create snapshots for easy rollbacks if data corruption occurs. #### Create a snapshot Snapshots can be created **without** stopping the node: -```bash +```sh sudo zfs snapshot data/ton-work@backup-date ``` #### Roll back to a snapshot To restore data from a snapshot, you **must** stop the validator service first: -```bash +```sh # Stop the service sudo systemctl stop validator.service @@ -223,7 +239,7 @@ Creating a snapshot is instantaneous and happens on the same physical disks wher Before exporting, estimate the size of the snapshot: -```bash +```sh sudo zfs send -pc -nv data/ton-work@backup-date ``` @@ -235,7 +251,7 @@ 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 will be significantly larger): -```bash +```sh sudo zfs send -c data/ton-work@backup-date > /external_storage/backup_ton_work.zfs ``` @@ -247,7 +263,7 @@ sudo zfs send -c data/ton-work@backup-date > /external_storage/backup_ton_work.z You can stream a snapshot directly to a remote ZFS-enabled server: -```bash +```sh sudo zfs send -c data/ton-work@backup-date | ssh user@remote_host "sudo zfs recv remote_data/ton-work" ``` From b1165e86508bf9f12c125a1310d1f3a8693199e0 Mon Sep 17 00:00:00 2001 From: ATrump Date: Thu, 7 May 2026 18:38:46 -0300 Subject: [PATCH 3/9] Add security hardening, official channel updates, and refined installation steps. --- .../nodes/cpp/run-archive-liteserver.mdx | 242 ++++++++++++++---- 1 file changed, 186 insertions(+), 56 deletions(-) diff --git a/ecosystem/nodes/cpp/run-archive-liteserver.mdx b/ecosystem/nodes/cpp/run-archive-liteserver.mdx index 3b2049ead..fe6d16912 100644 --- a/ecosystem/nodes/cpp/run-archive-liteserver.mdx +++ b/ecosystem/nodes/cpp/run-archive-liteserver.mdx @@ -25,7 +25,7 @@ Running an archive liteserver node requires significant storage and network reso - **IP**: Fixed (static) public IP address ### 1.2 OS and system requirements @@ -33,13 +33,22 @@ Running an archive liteserver node requires significant storage and network reso - **Supported OS**: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, or Debian 11. - **Open Files Limit**: Must be set above 400,000. +### 1.3 Subscribe to official channels + +Subscribe and follow the announcements provided for liteservers in the following Telegram channels: + +| Channel | Network | +| -------------------------------------------- | ----------- | +| [@tonstatus](https://t.me/tonstatus) | TON Mainnet | +| [@testnetstatus](https://t.me/testnetstatus) | TON Testnet | + ## Step 2: Install ZFS and prepare volume Archive nodes benefit significantly from ZFS due to its native compression and snapshot capabilities. ### 2.1 Install ZFS -```sh +```bash sudo apt update sudo apt install -y zfsutils-linux ``` @@ -48,7 +57,7 @@ sudo apt install -y zfsutils-linux For NVMe drives, it is critical to align the ZFS pool's sector size with the drive's physical block size to avoid significant performance degradation. Most modern NVMe drives use 4K blocks. Verify your drive's physical block size: -```sh +```bash # Replace nvme0n1 with your device name cat /sys/block/nvme0n1/queue/physical_block_size ``` @@ -60,12 +69,12 @@ If the result is `4096`, you must use the `-o ashift=12` parameter during pool c Create a ZFS pool named `data`. Use `-o ashift=12` for 4K blocks (standard for most NVMe drives): - ```sh Single drive + ```bash Single drive # Replace with your device identifier (e.g., /dev/nvme1n1) sudo zpool create -o ashift=12 data ``` - ```sh Multiple drives (Stripe) + ```bash Multiple drives (Stripe) # Combine multiple disks to increase capacity and performance sudo zpool create -o ashift=12 data ``` @@ -79,7 +88,7 @@ Create a ZFS pool named `data`. Use `-o ashift=12` for 4K blocks (standard for m We recommend enabling `lz4` compression to save disk space with minimal CPU overhead: -```sh +```bash sudo zfs set compression=lz4 data ``` @@ -87,7 +96,7 @@ sudo zfs set compression=lz4 data Create the dataset for TON data and set the mount point to `/var/ton-work`: -```sh +```bash sudo zfs create data/ton-work sudo zfs set mountpoint=/var/ton-work data/ton-work ``` @@ -98,61 +107,151 @@ sudo zfs set mountpoint=/var/ton-work data/ton-work If you still need a dedicated operator, create and switch to it before installing MyTonCtrl: -```sh -sudo adduser -sudo usermod -aG sudo -# reconnect as the new user -ssh @ +1. Create a non-root user + + ```bash + # Create a non-root operator user + sudo adduser + sudo usermod -aG sudo + ``` + +1. Switch to it by reconnecting to the server via `ssh` + + ```bash + #reconnect as the new user + exit + ssh @ + ``` + +### 3.2 Harden server security + + + +#### SSH hardening + +Apply the following SSH configuration changes in `/etc/ssh/sshd_config`: + +- Enable key-based authentication and disable password login: + +```text +PasswordAuthentication no +PubkeyAuthentication yes ``` -### 3.2 Install MyTonCtrl +- Disable root login: -Run the installer from the operator account with `sudo` so it can create system users and services: +```text +PermitRootLogin no +``` -```sh -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 -sudo bash install.sh +- Change the default SSH port: + +```text +Port ``` -During installation, select the following options: -1. **Mode**: Select `liteserver`. -2. **Network**: Select `mainnet` (or `testnet` if required). -3. **Archive blocks**: When prompted *"Do you want to download archive blocks via TON Storage?"*, enter `1` (Yes). +`` — a non-default port number (for example, `2222`). - +- Restrict SSH access to specific IP addresses using the `Match Address` directive: + +```text +Match Address + AllowUsers +``` + +Restart the SSH service after changes: + +```bash +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 [step 4.4](/ecosystem/nodes/cpp/run-archive-liteserver#4-4). + +```bash +sudo ufw allow /tcp +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: + + ```bash + 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. + +### 3.3 Install MyTonCtrl + +Run the installer from the operator account with `sudo` so it can create system users and services: + + + ```bash Mainnet + 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 + nohup sudo bash install.sh -m liteserver -n mainnet --archive > mytonctrl_installation.log 2>&1 & + ``` + + ```bash Testnet + 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 + nohup sudo bash install.sh -m liteserver -n testnet --archive > mytonctrl_installation.log 2>&1 & + ``` + + +Installation will be run in background. ## Step 4: Verify and monitor -### 4.1 Monitor installation progress +The installation process consists of two lengthy stages (in total, this can take up to a week): + +### Node installation and data download via TON Storage -Since the installation runs in the background, you can track the download and setup progress by monitoring the installation log file in the directory where you ran the script: +This process can take from 12 hours to several days depending on your internet connection speed. You can monitor the progress using the following command: -```sh +```bash tail -f mytonctrl_installation.log ``` -This is especially useful for tracking the progress of downloading archive blocks via TON Storage, which can take anywhere from 12 hours to several days depending on your internet connection speed. +Upon successful completion of this stage, you will see the following line in the log: + +```text +[5/5] Mytonctrl installation completed +``` -### 4.2 Check synchronization status +### Importing downloaded data into the node database and synchronization -Once the initial setup is complete, you can use the MyTonCtrl console to check the node's synchronization status: +This process can take from one to several days depending on your server performance. You can monitor the progress using the following command: -```sh +```bash mytonctrl MyTonCtrl> status ``` -Check the field **Local validator initial sync status**. The value indicates how many blocks are left to sync. +Check the field **Local validator initial sync status**. The value indicates how many blocks are left to sync. On fully synchronized node, this value should be less than 20 seconds. ### 4.3 Verify file ownership Ensure the node directories have correct permissions: -```sh +```bash # Database owner should be the validator user sudo chown -R validator:validator /var/ton-work/db @@ -160,17 +259,21 @@ sudo chown -R validator:validator /var/ton-work/db sudo chown -R : /var/ton-work/keys ``` -### 4.4 Open the liteserver port +### 4.4 Open the node UDP port and the liteserver port + +Print `engine.addr` port and liteserver port from configuration `config.json` file: -Check the port in `/var/ton-work/db/config.json` (within the `liteservers` array). +```bash +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: -```sh +```bash sudo apt install -y ufw -sudo ufw allow ssh -sudo ufw allow -sudo ufw enable +sudo ufw allow +sudo ufw allow sudo ufw status ``` @@ -180,14 +283,14 @@ sudo ufw status To see detailed logs of the block import process, increase the log verbosity from the MyTonCtrl console: -```sh +```bash mytonctrl MyTonCtrl> installer set_node_argument --verbosity 3 ``` Then follow the log file from a separate terminal: -```sh +```bash tail -f /var/ton-work/log* ``` @@ -197,14 +300,12 @@ You should see entries like: [ 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 ``` - +```bash +mytonctrl +MyTonCtrl> installer set_node_argument --verbosity 1 +``` ### 5.2 ZFS Snapshots @@ -213,14 +314,14 @@ ZFS allows you to create snapshots for easy rollbacks if data corruption occurs. #### Create a snapshot Snapshots can be created **without** stopping the node: -```sh +```bash sudo zfs snapshot data/ton-work@backup-date ``` #### Roll back to a snapshot To restore data from a snapshot, you **must** stop the validator service first: -```sh +```bash # Stop the service sudo systemctl stop validator.service @@ -239,7 +340,7 @@ Creating a snapshot is instantaneous and happens on the same physical disks wher Before exporting, estimate the size of the snapshot: -```sh +```bash sudo zfs send -pc -nv data/ton-work@backup-date ``` @@ -251,7 +352,7 @@ 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 will be significantly larger): -```sh +```bash sudo zfs send -c data/ton-work@backup-date > /external_storage/backup_ton_work.zfs ``` @@ -263,11 +364,40 @@ sudo zfs send -c data/ton-work@backup-date > /external_storage/backup_ton_work.z You can stream a snapshot directly to a remote ZFS-enabled server: -```sh +```bash sudo zfs send -c data/ton-work@backup-date | ssh user@remote_host "sudo zfs recv remote_data/ton-work" ``` -### 5.4 Performance issues +### 5.4 Performing software updates + +Before performing any updates, it is highly recommended to create a ZFS snapshot of your data. This allows you to quickly roll back in case the update process fails or corrupts the database. + +```bash +sudo zfs snapshot data/ton-work@before-update-$(date +%Y-%m-%d) +``` + +To update your node software and MyTonCtrl to the latest versions, use the MyTonCtrl console. + +Open the console: + +```bash +mytonctrl +``` + +Inside the console, run the following commands sequentially: + +```bash +MyTonCtrl> update master +MyTonCtrl> upgrade master +``` + +These commands will check for new versions of the TON node binaries and MyTonCtrl, download them, and apply the updates. + + + +### 5.5 Performance issues If you see logs like `Importing archive for masterchain seqno #... from net` accompanied by timeout errors, it likely indicates that your storage performance is insufficient to keep up with the block import process. Ensure your disk meets the IOPS requirements listed in [section 1.1](#step-1-prepare-environment). From 24f47b0866e878b38d8d721b06a329f22181c3cb Mon Sep 17 00:00:00 2001 From: ATrump Date: Thu, 7 May 2026 18:46:43 -0300 Subject: [PATCH 4/9] Small fixes --- .../nodes/cpp/run-archive-liteserver.mdx | 40 ++++++++----------- 1 file changed, 16 insertions(+), 24 deletions(-) diff --git a/ecosystem/nodes/cpp/run-archive-liteserver.mdx b/ecosystem/nodes/cpp/run-archive-liteserver.mdx index fe6d16912..74d603d50 100644 --- a/ecosystem/nodes/cpp/run-archive-liteserver.mdx +++ b/ecosystem/nodes/cpp/run-archive-liteserver.mdx @@ -107,21 +107,21 @@ sudo zfs set mountpoint=/var/ton-work data/ton-work If you still need a dedicated operator, create and switch to it before installing MyTonCtrl: -1. Create a non-root user +- Create a non-root user - ```bash - # Create a non-root operator user - sudo adduser - sudo usermod -aG sudo - ``` +```bash +# Create a non-root operator user +sudo adduser +sudo usermod -aG sudo +``` -1. Switch to it by reconnecting to the server via `ssh` +- Switch to it by reconnecting to the server via `ssh` - ```bash - #reconnect as the new user - exit - ssh @ - ``` +```bash +#reconnect as the new user +exit +ssh @ +``` ### 3.2 Harden server security @@ -222,7 +222,7 @@ Installation will be run in background. The installation process consists of two lengthy stages (in total, this can take up to a week): -### Node installation and data download via TON Storage +### 4.1 Node installation and data download via TON Storage This process can take from 12 hours to several days depending on your internet connection speed. You can monitor the progress using the following command: @@ -236,9 +236,9 @@ Upon successful completion of this stage, you will see the following line in the [5/5] Mytonctrl installation completed ``` -### Importing downloaded data into the node database and synchronization +### 4.2 Importing downloaded data into the node database and synchronization -This process can take from one to several days depending on your server performance. You can monitor the progress using the following command: +This process can take from one to several days depending on your server performance. You can monitor the progress using the MyTonCtrl console: ```bash mytonctrl @@ -376,15 +376,7 @@ Before performing any updates, it is highly recommended to create a ZFS snapshot sudo zfs snapshot data/ton-work@before-update-$(date +%Y-%m-%d) ``` -To update your node software and MyTonCtrl to the latest versions, use the MyTonCtrl console. - -Open the console: - -```bash -mytonctrl -``` - -Inside the console, run the following commands sequentially: +To update your node software and MyTonCtrl to the latest versions, use the MyTonCtrl console: ```bash MyTonCtrl> update master From 6c5143164c156a8e364003f0fd07cf4f4db73a24 Mon Sep 17 00:00:00 2001 From: ATrump Date: Fri, 8 May 2026 20:16:29 -0300 Subject: [PATCH 5/9] Fix after @reveloper review --- .../nodes/cpp/run-archive-liteserver.mdx | 212 +++++++++++------- 1 file changed, 125 insertions(+), 87 deletions(-) diff --git a/ecosystem/nodes/cpp/run-archive-liteserver.mdx b/ecosystem/nodes/cpp/run-archive-liteserver.mdx index 74d603d50..769065e61 100644 --- a/ecosystem/nodes/cpp/run-archive-liteserver.mdx +++ b/ecosystem/nodes/cpp/run-archive-liteserver.mdx @@ -9,20 +9,19 @@ import { Aside } from '/snippets/aside.jsx'; An **archive liteserver node** is a type of full node that stores the entire block history of the TON blockchain. If you are building a blockchain explorer, an indexer, or any application requiring access to historical data, running an archive liteserver node is the recommended approach. -This guide explains how to set up an archive liteserver node using MyTonCtrl and ZFS for efficient storage management. +This guide explains how to set up an archive liteserver using MyTonCtrl and ZFS for efficient storage management. ## Step 1: Prepare environment ### 1.1 Minimal hardware requirements -Running an archive liteserver node requires significant storage and network resources. +Running an archive liteserver requires significant storage and network resources. -- **CPU**: 16-core CPU -- **RAM**: 128 GB RAM -- **Storage**: At least 16TB of SSD storage, 20TB if you will not use ZFS with compression (NVMe recommended), or Provisioned 64k+ IOPS storage -- **Network**: 1 Gbit/s symmetric connectivity (both inbound and outbound) -- **Traffic**: ~16 TB/month at peak load -- **IP**: Fixed (static) public IP address +- 16-core CPU +- 128 GB RAM +- At least 16TB of SSD storage, 20TB if you will not use ZFS with compression (NVMe recommended), 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 -### 2.4 Enable compression +### 1.4.4 Enable compression We recommend enabling `lz4` compression to save disk space with minimal CPU overhead: @@ -92,7 +92,7 @@ We recommend enabling `lz4` compression to save disk space with minimal CPU over sudo zfs set compression=lz4 data ``` -### 2.5 Create dataset and mountpoint +#### 1.4.5 Create dataset and mountpoint Create the dataset for TON data and set the mount point to `/var/ton-work`: @@ -101,11 +101,9 @@ sudo zfs create data/ton-work sudo zfs set mountpoint=/var/ton-work data/ton-work ``` -## Step 3: Installation via MyTonCtrl +### 1.5 Prepare the operator account -### 3.1 Prepare the operator account - -If you still need a dedicated operator, create and switch to it before installing MyTonCtrl: +If you need a dedicated operator user, create it and switch to it before installing MyTonCtrl: - Create a non-root user @@ -118,12 +116,12 @@ sudo usermod -aG sudo - Switch to it by reconnecting to the server via `ssh` ```bash -#reconnect as the new user +# Reconnect as the new user. If you changed the SSH port in Step 1.6, use the -p flag. exit -ssh @ +ssh @ [-p ] ``` -### 3.2 Harden server security +### 1.6 Harden server security +After you have verified that the update was successful and the node is running correctly, it is recommended to delete the snapshot to reclaim disk space. + ### 3.4 ZFS Snapshots ZFS allows you to create snapshots for easy rollbacks if data corruption occurs. @@ -352,6 +354,13 @@ Snapshots can be created **without** stopping the node: sudo zfs snapshot data/ton-work@backup-date ``` +#### List snapshots +To see all existing snapshots for the `data/ton-work` dataset: + +```bash +sudo zfs list -t snapshot data/ton-work +``` + #### Roll back to a snapshot To restore data from a snapshot, you **must** stop the validator service first: @@ -366,6 +375,13 @@ sudo zfs rollback data/ton-work@backup-date sudo systemctl start validator.service ``` +#### Delete a snapshot +Once a snapshot is no longer needed, you can delete it: + +```bash +sudo zfs destroy data/ton-work@backup-date +``` + ### 3.5 Archiving ZFS snapshots Creating a snapshot is instantaneous and happens on the same physical disks where your data is stored. To protect against hardware failure, you should export your snapshots to external storage or a remote server using `zfs send`. From 3e40b7405518e961969c5715080541743b78b8f0 Mon Sep 17 00:00:00 2001 From: ATrump Date: Tue, 12 May 2026 17:05:05 -0300 Subject: [PATCH 8/9] Actualize open files limit --- ecosystem/nodes/cpp/run-archive-liteserver.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ecosystem/nodes/cpp/run-archive-liteserver.mdx b/ecosystem/nodes/cpp/run-archive-liteserver.mdx index 0eac773c4..d656e6443 100644 --- a/ecosystem/nodes/cpp/run-archive-liteserver.mdx +++ b/ecosystem/nodes/cpp/run-archive-liteserver.mdx @@ -31,7 +31,7 @@ Running an archive liteserver requires significant storage and network resources - Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, or Debian 11 - Python 3.10 or higher -- Open Files Limit must be set above 400,000 +- Open Files Limit must be set above 4,000,000 ### 1.3 Subscribe to official channels From 03ce2ac51309c773b4b4955ac3f74484905d86b3 Mon Sep 17 00:00:00 2001 From: ATrump Date: Thu, 14 May 2026 13:24:03 -0300 Subject: [PATCH 9/9] Move 2.1.3 to 2.2.1 --- .../nodes/cpp/run-archive-liteserver.mdx | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/ecosystem/nodes/cpp/run-archive-liteserver.mdx b/ecosystem/nodes/cpp/run-archive-liteserver.mdx index d656e6443..c52c30fbd 100644 --- a/ecosystem/nodes/cpp/run-archive-liteserver.mdx +++ b/ecosystem/nodes/cpp/run-archive-liteserver.mdx @@ -252,7 +252,20 @@ Upon successful completion of the installation, you will see the following line [5/5] Mytonctrl installation completed ``` -### 2.1.3 Open the node UDP port and the liteserver port +### 2.2 Importing downloaded data into the archive liteserver database + +This process starts automatically after installation and can take from one to several days depending on your server performance. + +You can monitor the progress using the MyTonCtrl console: + +```bash +mytonctrl +MyTonCtrl> status +``` + +Check the field **Local validator initial sync status**. 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. @@ -272,19 +285,6 @@ sudo ufw allow sudo ufw status ``` -### 2.2 Importing downloaded data into the archive liteserver database - -This process starts automatically after installation and can take from one to several days depending on your server performance. - -You can monitor the progress using the MyTonCtrl console: - -```bash -mytonctrl -MyTonCtrl> status -``` - -Check the field **Local validator initial sync status**. The value indicates how old the last imported block was and should decrease over time. - ### 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 your server performance.