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.
Solo su macchine pulite. arx prende in
mano nginx, PHP-FPM e Squid: fa puntare la loro configurazione
di sistema ai file che genera in /srv/arx
(/etc/nginx/conf.d/zz-arx.conf, un pool per sito
in /etc/php/<ver>/fpm/pool.d/, un drop-in
systemd che fa leggere a Squid /srv/arx/squid/squid.conf).
Vhost, pool o regole Squid già presenti non vengono importati,
e togliere arx non li rimette a posto.
2. Installa arx
Aggiungi il repo apt di NetForge, poi installa. apt risolve
nginx, certbot, Squid (squid-openssl), nftables, GoAccess, e
tutto il resto dello stack che arx gestisce. (Non BIND9 né
Postfix — quelli sono di nomina e missus.) Se aggiorni una
macchina che ha il pacchetto squid normale, usa
apt full-upgrade (o apt install arx):
il semplice apt upgrade lascia arx indietro.
curl -fsSL https://apt.netforge.it/netforge.asc \
| sudo gpg --dearmor -o /usr/share/keyrings/netforge.gpg
echo "deb [signed-by=/usr/share/keyrings/netforge.gpg] https://apt.netforge.it/free $(. /etc/os-release; echo $VERSION_CODENAME) 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:
| Tipo | Cosa fa nginx | Per cosa |
|---|
| PHP | Serve i file da htdocs/, passa i .php a un pool PHP-FPM dedicato | WordPress, Laravel, PHP custom |
| Static | Serve i file da htdocs/, restituisce 404 per quello che manca | Output Hugo/Astro/Jekyll, SPA statiche |
| Reverse proxy | Inoltra ogni richiesta a un upstream — o bilancia su più backend | missus, 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
Il firewall di arx è solo in uscita: una tabella
nftables, inet arx, generata in
/srv/arx/nftables/arx.nft. L'utente di ogni sito
passa dalla sua catena e raggiunge solo le destinazioni che
autorizzi nella pagina del sito; con Squid acceso, il traffico
web viene controllato per dominio. Il traffico di sistema (root,
apt, SSH, nginx) non viene mai filtrato. Caricato a ogni avvio,
e ricaricato entro un minuto se qualcosa svuota le regole.
Il firewall in ingresso della macchina è tuo.
NetForge ha un template pronto per ogni combinazione di arx,
nomina e missus (SSH aperto con limite per IP, 80/443, 53, porte
della posta). Caricalo in modo che sostituisca solo la sua
tabella, mai con flush ruleset, che toglierebbe
anche quella di arx. La pagina System rules
mostra tutte le tabelle della macchina, in sola lettura.
Per spegnerlo: il pulsante Turn off
now del pannello, oppure nft delete table inet
arx, toglie le regole di arx. Non può chiuderti fuori:
arx non ha regole in ingresso.
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. 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.
