Guida utente

Da una Debian fresca a un sito funzionante con HTTPS in circa dieci minuti. Poi le cose quotidiane — backup, PHP multi-versione, filtro outbound, troubleshooting.

In questa pagina
  1. Prerequisiti
  2. Installa arx
  3. Primo login
  4. Crea il primo sito
  5. SSL con Let's Encrypt
  6. PHP multi-versione
  7. Filtro outbound per sito
  8. Firewall e ban
  9. Backup e migrazione
  10. Troubleshooting

1. Prerequisiti

  • Una macchina Debian 12 (bookworm) o Debian 13 (trixie) pulita: VPS, Raspberry Pi 4/5 con SSD, oppure un container LXC su Proxmox. 2 GB di RAM è il minimo sensato per uno o due siti PHP; un Pi 4 da 4 GB regge un cluster homelab senza problemi.
  • Accesso root. arx gira come root perché modifica /etc/nginx/, lancia useradd, nft, certbot.
  • Un IP pubblico con porte 80 e 443 raggiungibili dall'esterno (per Let's Encrypt e per servire i siti).
  • Almeno un hostname col DNS che punta alla macchina. Per convenzione panel.example.com per arx stesso più uno per ogni sito che ospiti.

2. Installa arx

Aggiungi il repo apt di NetForge, poi installa. apt risolve nginx, certbot, Squid, nftables, WireGuard, GoAccess, e tutto il resto dello stack che arx gestisce. (Non BIND9 né Postfix — quelli sono di nomina e missus.) 

curl -fsSL https://apt.netforge.it/free/key.gpg \
    | sudo gpg --dearmor -o /usr/share/keyrings/netforge.gpg
echo "deb [signed-by=/usr/share/keyrings/netforge.gpg] https://apt.netforge.it/free stable main" \
    | sudo tee /etc/apt/sources.list.d/netforge.list
sudo apt update
sudo apt install arx

Crea il primo admin e avvia il servizio:

sudo arx admin create iltuonome
sudo systemctl start arx
sudo systemctl status arx --no-pager

Il postinst crea /srv/arx/ (siti, stato, backup, certificati), genera un session secret a 256 bit in /etc/arx/env, e abilita tre timer: arx-renew (Let's Encrypt due volte al giorno), arx-refresh-cf-ips (range Cloudflare ogni settimana), arx-stats-refresh (GoAccess ogni giorno).

3. Primo login

arx si lega a 127.0.0.1:9443 di proposito — il pannello non è esposto sul mondo. Raggiungilo dal tuo portatile con un tunnel SSH: 

ssh -L 9443:127.0.0.1:9443 root@tuo-server

Apri http://127.0.0.1:9443/ nel browser. Login con l'admin che hai creato, attiva 2FA su /account (consigliato).

Promuovi a HTTPS pubblico appena puoi: crea un sito di tipo reverse_proxy (vedi prossima sezione) che punti a 127.0.0.1:9443 con hostname panel.example.com. arx richiede un certificato Let's Encrypt e serve sé stesso in HTTPS — a quel punto puoi chiudere il tunnel SSH e usare l'URL del pannello.

4. Crea il primo sito

arx supporta tre tipi di sito. Scegli al click di + Nuovo sito su /sites:

TipoCosa fa nginxPer cosa
PHPServe i file da htdocs/, passa i .php a un pool PHP-FPM dedicatoWordPress, Laravel, PHP custom
StaticServe i file da htdocs/, restituisce 404 per quello che mancaOutput Hugo/Astro/Jekyll, SPA statiche
Reverse proxyInoltra ogni richiesta a un upstream — o bilancia su più backendmissus, nomina, app Node/Go, qualsiasi cosa con un proprio listener
Load balancing: un sito reverse proxy può distribuire il traffico su più backend con qualunque metodo nginx open-source — round-robin (default), least_conn, ip_hash (sticky per IP client), hash (sticky su una chiave a scelta, anche consistent) o random. Ogni backend accetta i parametri per-server weight, max_fails, fail_timeout, max_conns, più backup e down (per svuotare un nodo in manutenzione), e il pool può tenere aperte connessioni keepalive inattive. Il pool si modifica in qualsiasi momento dalla pagina di dettaglio del sito. Il rilevamento guasti è passivo (max_fails/fail_timeout): gli health check attivi richiedono NGINX Plus e non sono offerti qui.

Per ogni sito arx crea un utente Unix dedicato e una webroot isolata in /srv/arx/sites/<dominio>/htdocs/. L'utente possiede i suoi file; nginx li legge tramite group membership. Gli utenti di altri siti non possono leggere le webroot altrui.

Solo SFTP: puoi marcare un sito come "SFTP-only" — l'utente Unix riceve shell /usr/sbin/nologin e la home è chrootata. Utile quando dai accesso a un developer su un sito senza dargli shell sulla macchina.

5. SSL con Let's Encrypt

Ogni sito ha un pannello SSL. Click su Emetti certificato; arx lancia certbot --webroot contro /.well-known/acme-challenge/ sull'nginx live (zero downtime), salva il cert in /etc/letsencrypt/live/<dominio>/ e ricarica nginx.

Il timer systemd arx-renew.timer esegue arx ssl renew due volte al giorno con jitter di 1 h (stessa cadenza del certbot.timer standard). I rinnovi vengono deployati e nginx ricaricato in automatico.

Puoi anche caricare un certificato emesso a mano (intermediate + chiave + chain) dallo stesso pannello — utile per wildcard di altre CA.

6. PHP multi-versione

arx pre-configura il repo di Ondřej Surý (packages.sury.org/php) al momento dell'install, quindi tutte le versioni PHP da 7.x a 8.4 sono a un apt di distanza: 

sudo apt install php8.4-fpm php8.4-mysql php8.4-curl php8.4-mbstring \
                 php8.4-xml php8.4-zip php8.4-gd php8.4-intl

Il pannello rileva ogni versione installata. Quando crei un sito PHP scegli la versione da un dropdown; arx genera un pool FPM per-sito sotto /srv/arx/php/pools/<versione>/<dominio>.conf e fa il symlink in /etc/php/<versione>/fpm/pool.d/.

Ogni pool riceve open_basedir, una directory tmp dedicata e un tuning FPM editabile per sito (preset minimal, light, wordpress, heavy, custom) — oppure lascia stare, i default vanno bene per il tipo di workload che hai scelto.

7. Filtro outbound per sito

Per default un sito ospitato può connettersi ovunque. Plugin WordPress, pacchetti Composer, API esterne — a volte utile, a volte un appiglio per un attaccante. arx filtra l'outbound a livello HTTP/HTTPS, per sito:

  • Squid SNI peek + nftables NAT per-UID — il TCP outbound dell'UID Unix del sito viene rediretto verso Squid; Squid sbircia l'SNI TLS e accetta solo gli hostname nell'allowlist del sito. Nessuna config dell'app, nessuna variabile proxy — è imposto a livello di rete, per UID.

Un'allowlist per sito in /srv/arx/whitelist/<dominio>.txt. Modifica, poi click su Applica — arx rigenera l'ACL Squid in modo atomico.

Profili: wordpress (api.wordpress.org, repo plugin, gravatar, ...), laravel, static, custom. Parti da un profilo e aggiungi quel che serve davvero al tuo sito.

Modalità learning: con il toggle in passthru + log verbose, lasci il sito girare un giorno, poi leggi quali hostname ha chiamato davvero e li trasformi in un'allowlist stretta. Molto meno tirar a indovinare.
Il filtro a livello DNS non è compito di arx. arx non tocca mai BIND — niente RPZ, niente zone. Se vuoi anche il blocco a livello DNS (NXDOMAIN per i nomi fuori lista), affianca ad arx nomina e configura lì la RPZ. I due coesistono puliti sulla stessa box.

8. Firewall e ban

arx possiede una sola tabella nftables — inet arx — renderizzata in /srv/arx/nftables/arx.nft e applicata via nft -f. INPUT default drop; loopback, connessioni stabilite, WireGuard e porte 80/443 sono accettate; SSH e pannello sono ristretti a una lista di CIDR admin.

La pagina Firewall mostra il ruleset live e un set nftables blocklist con flags timeout. Click su Banna IP, inserisci un indirizzo e una durata (1 h, 24 h, 30 g, …) e arx lo aggiunge al set. Il kernel lo droppa senza passare da un demone userspace.

WireGuard come admin plane: arx ha un generator WireGuard a un click. Setup di wg0 + una config client per il tuo portatile, poi chiudi :22 pubblica e l'accesso al pannello — entrambi restano raggiungibili solo via mesh WG. arx aspetta un heartbeat prima di committare la chiusura, così una regola mal configurata fa rollback automatico prima di chiudertici fuori.

9. Backup e migrazione

Tutto quello che arx possiede vive in /srv/arx/: webroot dei siti, state.db, cache certificati, sorgenti dei pool FPM, whitelist per sito, chiavi WireGuard. Il backup è rsync. 

# sulla macchina sorgente
sudo rsync -aHAX --delete /srv/arx/ backup-host:/srv/arx-snapshot/

# sulla nuova macchina, dopo `apt install arx`
sudo rsync -aHAX backup-host:/srv/arx-snapshot/ /srv/arx/
sudo arx rehydrate

arx rehydrate legge /srv/arx/ e ricrea i side-effect che non vivono lì: utenti Unix per sito (useradd), i symlink dei pool FPM in /etc/php/<ver>/fpm/pool.d/, lo stub di include nginx, il ruleset nftables, e ricarica i demoni.

Per i tarball per sito, la pagina Backup dentro ogni sito impacchetta webroot + dump DB (se hai configurato un host DB) in un singolo <dominio>_<timestamp>.tar.gz in /srv/arx/backups/.

10. Troubleshooting

Prima fermata:

sudo arx check

Cammina sul filesystem, demoni, porte in ascolto, certificati SSL, e riporta ogni voce ✓ / ! / ✗. Quasi tutte le domande "perché non funziona?" hanno risposta chiara nell'output di arx check.

Log dei servizi:

sudo journalctl -u arx -n 100 --no-pager
sudo journalctl -u nginx -n 100 --no-pager
sudo journalctl -u php8.4-fpm -n 100 --no-pager

Log per sito (nginx access + error):

tail -f /srv/arx/logs/nginx/<dominio>/access.log
tail -f /srv/arx/logs/nginx/<dominio>/error.log

La dashboard Live del pannello (/system/live) aggrega connessioni attive nginx e request rate con i worker dei pool PHP-FPM per sito, aggiornata ogni pochi secondi.

Se devi rifare arx da zero: apt purge arx di proposito non cancella /srv/arx/. Anche le purge a cascata da rimozione di pacchetti non collegati lasciano i tuoi dati intatti. Per cancellare davvero, rimuovi le directory a mano — sudo rm -rf /srv/arx /etc/arx — è un'azione esplicita e deliberata che devi prendere tu.