# Run a liteserver (https://docs-kyrm16yq7-ton-core-docs.vercel.app/llms/ecosystem/nodes/cpp/run-liteserver/content.md)



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 [#prerequisites]

* A server meeting the [minimal hardware requirements](#1-1-minimal-hardware-requirements)
* An OS meeting the [requirements](#1-2-os-and-system-requirements)

## Step 1: Prepare environment [#step-1-prepare-environment]

### 1.1 Minimal hardware requirements [#11-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

<Callout type="caution">
  If non-Enterprise SSDs are used, Autonomous Power State Transition (APST) must be disabled on the SSD and the `performance` PCIe ASPM policy enabled at the system level:

  ```bash
  echo performance | sudo tee /sys/module/pcie_aspm/parameters/policy
  ```
</Callout>

### 1.2 OS and system requirements [#12-os-and-system-requirements]

* [Ubuntu](https://ubuntu.com/download/server) 22.04/24.04 LTS or [Debian](https://www.debian.org/distrib/) 11/12
* Python 3.10 or higher

### 1.3 Subscribe to official channels [#13-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 |

### 1.4 Free space requirements [#14-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 [#15-prepare-the-operator-account]

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

1. Create a non-root user:

   ```bash
   # 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:

   <CodeGroup>
     <CodeBlockTabs defaultValue="Standard port">
       <CodeBlockTabsList>
         <CodeBlockTabsTrigger value="Standard port">
           Standard port
         </CodeBlockTabsTrigger>

         <CodeBlockTabsTrigger value="Custom SSH port">
           Custom SSH port
         </CodeBlockTabsTrigger>
       </CodeBlockTabsList>

       <CodeBlockTab value="Standard port">
         ```bash
         # Option 1: Reconnect using the standard port
         exit
         ssh <USERNAME>@<SERVER_IP>
         ```
       </CodeBlockTab>

       <CodeBlockTab value="Custom SSH port">
         ```bash
         # Option 2: Reconnect using the custom SSH port
         exit
         ssh <USERNAME>@<SERVER_IP> -p <SSH_PORT>
         ```
       </CodeBlockTab>
     </CodeBlockTabs>
   </CodeGroup>

### 1.6 Benchmark server performance [#16-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 [#161-network-latency]

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

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

#### 1.6.2 Disk IOPS [#162-disk-iops]

Install `fio` and run a random read/write benchmark:

```bash
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 [#163-network-bandwidth]

Verify network throughput with `speedtest-cli`:

```bash
sudo apt install -y speedtest-cli
speedtest-cli
```

Ensure download and upload speeds meet the [1 Gbit/s requirement](#1-1-minimal-hardware-requirements).

### 1.7 Harden server security [#17-harden-server-security]

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

* [SSH hardening](#ssh-hardening)
* [Firewall configuration](#firewall-configuration)
* [Additional security measures](#additional-security-measures)

#### SSH hardening [#ssh-hardening]

<Callout type="caution" title="Avoid locking yourself out">
  Disabling password login, changing the SSH port, and restricting access by `Match Address` can lock the operator out of a remote server. Keep the current SSH session open and confirm a new login succeeds in a second session before closing the first one.
</Callout>

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

* Enable key-based authentication and disable password login:

  ```text
  PasswordAuthentication no
  PubkeyAuthentication yes
  ```

* Disable root login:

  ```text
  PermitRootLogin no
  ```

* Change the default SSH port, e.g., to `2222`:

  ```text
  Port <SSH_PORT>
  ```

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

  ```text
  Match Address <ALLOWED_IP>
    AllowUsers <USERNAME>
  ```

  There, `<USERNAME>` is the name of the operator user.

Restart the SSH service after changes:

```bash
sudo systemctl restart sshd
```

#### Firewall configuration [#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](#2-2-1-open-the-node-udp-port-and-the-liteserver-port).

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

#### Additional security measures [#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.

## Step 2: Liteserver installation [#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 [#21-download-db-dump-and-install-the-liteserver]

#### 2.1.1 Install prerequisites and download installer (MyTonCtrl) [#211-install-prerequisites-and-download-installer-mytonctrl]

```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
```

#### 2.1.2 Run liteserver installation [#212-run-liteserver-installation]

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

<CodeGroup>
  <CodeBlockTabs defaultValue="Mainnet">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Mainnet">
        Mainnet
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Testnet">
        Testnet
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Mainnet">
      ```bash
      export ARCHIVE_TTL=2592000 STATE_TTL=86400 && sudo -v && nohup sudo bash install.sh -m liteserver -n mainnet -d > mytonctrl_installation.log 2>&1 &
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Testnet">
      ```bash
      export ARCHIVE_TTL=2592000 STATE_TTL=86400 && sudo -v && nohup sudo bash install.sh -m liteserver -n testnet -d > mytonctrl_installation.log 2>&1 &
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

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:

```bash
tail -f mytonctrl_installation.log
```

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

```text
[#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]
```

<Callout type="caution">
  If there are no these lines in the log, check whether there is enough free space in accordance with [free space requirements](#1-4-free-space-requirements) or use [manual DB dump download](#manual-db-dump-download).
</Callout>

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

```text
[5/5] Mytonctrl installation completed
```

#### 2.2 Final synchronization of liteserver [#22-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:

```bash
mytonctrl
```

At the `MyTonCtrl>` prompt, run:

```text
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 [#221-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:

```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:

```bash
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 [#step-3-maintenance]

### 3.1 Set up alerting [#31-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](/llms/ecosystem/nodes/cpp/mytonctrl/alerting/content.md).

### 3.2 Set up monitoring [#32-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](/llms/ecosystem/nodes/cpp/integrating-with-prometheus/content.md).

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`](https://t.me/mytonctrl_help_bot).

### 3.3 Perform software updates [#33-perform-software-updates]

<Callout type="note">
  Follow the [`@tonstatus`](https://t.me/tonstatus) channel, turn on notifications, and be prepared for urgent updates.
</Callout>

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

```bash
mytonctrl
```

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

```text
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:

```text
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 [#troubleshooting]

### Monitor logs [#monitor-logs]

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

```bash
mytonctrl
```

At the `MyTonCtrl>` prompt, run:

```text
MyTonCtrl> installer set_node_argument --verbosity 3
```

Then follow the log file from a separate terminal:

```bash
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:

```text
MyTonCtrl> installer set_node_argument --verbosity 1
```

### Performance issues [#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](#1-1-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:

   ```bash
   sudo systemctl stop validator.service
   ```

2. Open the MyTonCtrl console:

   ```bash
   mytonctrl
   ```

   At the `MyTonCtrl>` prompt, run:

   ```text
   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:

   ```bash
   sudo systemctl start validator.service
   ```

### Manual DB dump download [#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](https://dump.ton.org/) for available snapshots.

1. Install `aria2` and `plzip` if not already present:

   ```bash
   sudo apt install -y aria2 plzip
   ```

2. Stop the validator and MyTonCore services:

   ```bash
   sudo systemctl stop mytoncore.service
   sudo systemctl stop validator.service
   ```

3. Download and extract the dump:

   ```bash
   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:

   ```bash
   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:

   ```bash
   sudo systemctl start validator.service
   sudo systemctl start mytoncore.service
   ```

## Support [#support]

For technical assistance, join the official support channel: [`@ton_node_help`](https://t.me/ton_node_help).

## See also [#see-also]

* [Run an archive liteserver node with MyTonCtrl](/llms/ecosystem/nodes/cpp/run-archive-liteserver/content.md)
* [Run a validator node with MyTonCtrl](/llms/ecosystem/nodes/cpp/run-validator/content.md)
* [Set up a node with MyTonCtrl](/llms/ecosystem/nodes/cpp/setup-mytonctrl/content.md)
* [TON node types](/llms/ecosystem/nodes/overview/content.md)