Node installation guide

01 What you need

• A VPS or dedicated server with a public IP (shared hosting is fine if you can upload PHP and use HTTPS)
• Ubuntu 22.04+ or AlmaLinux 8/9
• Web server + PHP 8.0+ with curl, openssl, and json
• Public HTTPS URL for the agent file (required by default)
• Outbound access for IPv4/IPv6 ping, TCP, UDP, and DNS, plus traceroute and mtr

Suggested VPS size

A small VPS is enough:

• CPU: 1 core
• RAM: 512 MB
• Disk: 15 GB
• Network: normal public connectivity

Bigger plans work too. The agent is light and only runs short jobs when the hub asks.

02 Install web server and PHP on Ubuntu

These steps use Nginx + PHP-FPM on Ubuntu 22.04 / 24.04. Run them as root or with sudo.

Update packages

sudo apt update && sudo apt upgrade -y

Install Nginx and PHP

sudo apt install -y \
  nginx \
  php-fpm \
  php-cli \
  php-curl \
  php-xml \
  php-mbstring \
  traceroute \
  mtr-tiny

Check PHP version

php -v

You should see PHP 8.0 or newer.

Enable PHP in Nginx

Edit the default site (change the PHP socket if your version differs, for example php8.3-fpm):

sudo nano /etc/nginx/sites-available/default

Inside the server { ... } block, use something like:

root /var/www/html;
index index.php index.html;

location / {
    try_files $uri $uri/ =404;
}

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}

Find your socket path if needed:

ls /run/php/

Reload services

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl enable --now php8.3-fpm

Replace php8.3-fpm with the version you saw under /run/php/.

Optional: HTTPS with Let's Encrypt

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example

03 Install web server and PHP on AlmaLinux

Steps for AlmaLinux 8/9 with Nginx + PHP-FPM.

Update packages

sudo dnf update -y

Enable PHP modules (AlmaLinux 8)

sudo dnf module reset php -y
sudo dnf module enable php:8.2 -y

On AlmaLinux 9 a recent PHP stream is usually ready already. Use dnf module list php if you are unsure.

Install Nginx and PHP

sudo dnf install -y \
  nginx \
  php-fpm \
  php-cli \
  php-curl \
  php-xml \
  php-mbstring \
  traceroute \
  mtr

Start services

sudo systemctl enable --now nginx
sudo systemctl enable --now php-fpm

Configure Nginx for PHP

Create or edit a site file, for example /etc/nginx/conf.d/netstats-node.conf:

server {
    listen 80;
    server_name your-domain.example;
    root /usr/share/nginx/html;
    index index.php index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php-fpm/www.sock;
    }
}

Confirm the PHP-FPM socket:

ls /run/php-fpm/

Open firewall (if firewalld is on)

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Test and reload

sudo nginx -t
sudo systemctl reload nginx

Optional: HTTPS with Let's Encrypt

sudo dnf install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example

04 Deploy the agent

Download

Download netstats-node.php

Or pull it on the server:

cd /var/www/html          # Ubuntu default
# or: cd /usr/share/nginx/html   # AlmaLinux default

sudo curl -fsSL -o netstats-node.php \
  "https://netstats.ir/agent/download.php"

Permissions

sudo chown www-data:www-data netstats-node.php   # Ubuntu
# AlmaLinux often uses: sudo chown nginx:nginx netstats-node.php
sudo chmod 640 netstats-node.php

Config

Edit the top of the file:

sudo nano netstats-node.php

const HUB_URL = 'https://netstats.ir';
const NODE_TOKEN = '';
const HUB_HMAC_SECRET = '';
const NODE_NAME = 'my-node';
const ALLOW_PRIVATE_TARGETS = false;

Leave the token fields empty until you are approved.

Test

Open https://your-domain.example/netstats-node.php?action=health in a browser. You should see JSON with "ok":1.

If you get that JSON, the agent is up. That is what NetStats checks before join.

IPv6 examples for checks later: 2001:db8::1, [2001:db8::1]:443, http://[2001:db8::1]/.

05 Traffic profile and operator responsibility

When your node is approved, the hub may ask it to run short public-target checks submitted by site users. Expect small outbound probes from your server IP:

• Ping: a few ICMP echoes
• HTTP: one GET, no redirect following, response body capped (~16 KB), short timeout
• TCP / UDP: a brief connect or one-byte probe to a chosen port
• DNS / path checks: resolver queries, traceroute, or MTR when those features are enabled

Private, loopback, and link-local targets are blocked unless you set ALLOW_PRIVATE_TARGETS = true in the agent (off by default; the hub alone cannot force this).

If you do not want your IP used as a check source, do not join, or filter egress on your firewall. Abuse complaints for probe traffic land with the node operator as well as the hub.

06 Join the network

Submit your public agent URL on the join form. An admin reviews every request. After approval you receive NODE_TOKEN and HUB_HMAC_SECRET by email (when the hub SMTP is configured). Put them into the agent config and keep the agent online.