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 if your host allows it

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

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

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

From any machine:

curl -H "Accept: application/json" \
  "https://your-domain.example/netstats-node.php?action=health"

Expected:

{"ok":1,"version":"1.0.0","name":"my-node"}

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 Join the network

1. Open the Join page
2. Paste your HTTPS agent URL (the same one that returns health JSON)
3. Fill country, city, and email
4. Submit and wait for admin approval

After approval you get a NODE_TOKEN and HUB_HMAC_SECRET. Put them in the agent config and save. Keep them private.

const NODE_TOKEN = 'paste-here';
const HUB_HMAC_SECRET = 'paste-here';

Security and uninstall

• Prefer HTTPS and do not put a configured agent file in a public git repo
• Turn off directory listing and remove .bak copies of the agent
• The agent blocks private and metadata targets by default
• To leave: delete netstats-node.php and ask an admin to disable your node