Come installare Ajenti su Ubuntu 22.04 passo dopo passo

Ajenti su Ubuntu 22.04 ha senso solo se vuoi un pannello leggero per amministrazione di base e non un sostituto di una piattaforma completa di orchestration. La differenza pratica sta tutta qui: installarlo bene significa prima capire dipendenze, porta di ascolto, servizio systemd e perimetro di esposizione, poi validare l’accesso web senza aprire più del necessario.

In questa guida parto da un’installazione pulita su Ubuntu 22.04 LTS, con privilegi sudo e accesso root opzionale. Se il server è già in produzione, trattalo come change controllato: prima backup dei file di configurazione esistenti, poi finestra di manutenzione breve, infine verifica da rete esterna.

Prerequisiti reali prima di toccare il sistema

Ajenti richiede un sistema aggiornato, Python compatibile con il pacchetto disponibile e una base pulita lato servizi. Su Ubuntu 22.04 conviene partire con un update completo e verificare che non ci siano problemi di rete o repository bloccati.

Fai subito questi controlli:

• connettività verso i repository Ubuntu;
• spazio disco sufficiente in / e /var;
• porta di management non già occupata;
• accesso sudo funzionante.

Comandi utili per la verifica iniziale:

sudo apt update
sudo apt -y upgrade
hostnamectl
ip a
ss -lntp

Se apt update fallisce, non andare avanti: il problema non è Ajenti ma la base del sistema. In quel caso controlla DNS, proxy, mirror e stato del file /etc/apt/sources.list o delle entry in /etc/apt/sources.list.d/.

Installazione di Ajenti su Ubuntu 22.04

La parte delicata è il repository. Ajenti ha avuto nel tempo cambi di manutenzione e disponibilità dei pacchetti, quindi non dare per scontato che il percorso “classico” sia sempre raggiungibile. Il metodo corretto è verificare prima la fonte del pacchetto, poi installare, poi confermare che il servizio sia stato creato e avviato.

Se il repository ufficiale è disponibile nel tuo scenario, il flusso tipico è questo:

sudo apt install -y curl gnupg ca-certificates
curl -fsSL https://raw.githubusercontent.com/ajenti/ajenti/master/scripts/install.sh | sudo bash

Questo approccio è comodo, ma va trattato con prudenza: uno script remoto è una dipendenza esterna. Se vuoi ridurre il rischio operativo, scaricalo prima, leggilo e poi eseguilo dopo una revisione minima.

curl -fsSL https://raw.githubusercontent.com/ajenti/ajenti/master/scripts/install.sh -o /tmp/ajenti-install.sh
sed -n '1,220p' /tmp/ajenti-install.sh
sudo bash /tmp/ajenti-install.sh

Se il repository o lo script non sono più disponibili, non inventare un fallback casuale: fermati qui e chiudi il gap con il pacchetto corretto per la tua release o con un contenitore isolato. In un ambiente serio, la disponibilità del canale di installazione è parte del controllo di change, non un dettaglio.

Verifica del servizio systemd e porta di ascolto

Dopo l’installazione, la prima cosa da controllare è lo stato del servizio. Se il daemon non parte, non passare subito al browser: leggi il journal e trova l’errore prima di cambiare configurazioni a caso.

sudo systemctl status ajenti --no-pager
sudo journalctl -u ajenti -b --no-pager | tail -n 100

Lo stato desiderato è active (running). Se vedi failed, le cause più comuni sono: dipendenze mancanti, porta già occupata, errore di permessi su directory del servizio, incompatibilità di runtime o configurazione corrotta.

Per capire dove ascolta davvero il servizio, usa:

sudo ss -lntp | grep -i ajenti
sudo ss -lntp | grep -E ':8000|:8001|:443'

Ajenti, a seconda della versione e del packaging, può esporre l’interfaccia su una porta dedicata in HTTP o HTTPS. Non assumere che sia sempre la stessa: la verifica con ss evita errori banali quando il servizio è attivo ma non raggiungibile dal browser.

Accesso iniziale dal browser e prima autenticazione

Quando il servizio è in ascolto, apri l’URL corrispondente alla porta rilevata. Se sei in locale o su rete privata, l’accesso diretto va bene per il test iniziale. In produzione, invece, limita subito l’esposizione con firewall o reverse proxy autenticato.

Esempio di accesso locale, se Ajenti ascolta sulla 8000:

http://IP_DEL_SERVER:8000

Se la pagina non risponde, distinguere il layer è fondamentale: DNS, reachability, porta, servizio o applicazione. Un controllo rapido da shell ti evita di perdere tempo sul browser.

curl -I http://127.0.0.1:8000
curl -I http://IP_DEL_SERVER:8000

Se il primo comando funziona e il secondo no, il problema è quasi sempre di firewall, bind su localhost o routing. Se nessuno dei due risponde, il servizio non è partito correttamente o sta ascoltando su un’altra porta.

Firewall: aprire solo il necessario

Ajenti non va esposto a caso su Internet. La regola sensata è consentire l’accesso solo da IP amministrativi o da una VPN. Se usi UFW, apri la porta effettiva del pannello e non altro.

sudo ufw status verbose
sudo ufw allow 8000/tcp

Meglio ancora, se hai un reverse proxy, lascia Ajenti in ascolto solo su localhost e pubblicalo tramite Nginx o Apache con TLS e restrizioni di accesso. È una scelta più pulita sul piano del perimetro e riduce la superficie d’attacco.

Se la macchina è già protetta da security group o ACL di rete, documenta il punto esatto in cui avviene il filtraggio. Un pannello accessibile solo “perché tanto è su una porta non standard” è un errore operativo, non una protezione.

Configurazione minima utile dopo il primo avvio

Una volta entrato nel pannello, non fermarti alla schermata di login. La configurazione minima sensata comprende account amministrativi, timezone corretto, controllo dei plugin e revisione dei servizi esposti dal pannello stesso.

Se Ajenti permette la gestione degli utenti locali, usa credenziali dedicate all’amministrazione e non riutilizzare account condivisi. Se l’ambiente ha già un sistema di autenticazione centralizzato, verifica se il pannello può agganciarsi a quel backend oppure se conviene limitarlo dietro VPN e accesso nominativo al nodo.

Controlla anche il file di configurazione del servizio. Il path può variare in base al pacchetto, quindi conviene scoprirlo dal systemd unit o dalla documentazione installata:

sudo systemctl cat ajenti
sudo find /etc -maxdepth 3 -iname '*ajenti*'
sudo find /opt -maxdepth 3 -iname '*ajenti*'

Questo è il modo corretto di lavorare quando non vuoi assumere percorsi fissi che magari cambiano tra release o packaging diversi.

Esempio di hardening base

Se il pannello deve restare online, applica almeno un hardening minimo: accesso ristretto, TLS, logging, aggiornamenti e controllo della porta. Non serve complicare tutto, ma serve evitare che un tool amministrativo diventi un punto d’ingresso inutile.

Con Nginx come reverse proxy, il concetto è semplice: Ajenti resta interno, Nginx termina TLS e applica limiti di accesso. Un esempio concettuale di blocco server potrebbe essere questo:

server {
    listen 443 ssl;
    server_name pannello.example.com;

    ssl_certificate     /etc/letsencrypt/live/pannello.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pannello.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Se usi questo schema, il blast radius resta contenuto: un problema nel pannello non impatta direttamente l’esposizione pubblica, e il rollback è semplice perché basta disabilitare il vhost o ripristinare la config precedente.

Problemi tipici e come chiuderli senza perdere tempo

Il caso più comune è il servizio attivo ma la pagina non raggiungibile. In ordine di probabilità: porta sbagliata, firewall, bind locale, proxy mal configurato. Per falsificarli rapidamente, usa sempre una verifica locale e una remota.

sudo ss -lntp | grep -i ajenti
curl -I http://127.0.0.1:PORTA
curl -I http://IP_DEL_SERVER:PORTA

Se invece il servizio va in crash all’avvio, il journal è la fonte primaria. Un errore di import Python, una dipendenza mancante o una directory non scrivibile emergono quasi sempre lì. Non passare a reinstallazioni cieche finché non hai letto almeno le ultime righe del log.

sudo journalctl -u ajenti -b --no-pager | tail -n 50

Se il problema è il browser che mostra una pagina vuota, verifica anche la console del browser e il traffico HTTP. A volte il backend risponde ma una risorsa statica o una chiamata API fallisce per mixed content, CSP o certificato non valido.

Rollback e ripristino se qualcosa va storto

Quando tocchi un pannello di management, il rollback deve essere semplice. Prima di installare, salva eventuali file già presenti in /etc e annota la configurazione di firewall e reverse proxy. Se devi tornare indietro, l’obiettivo non è “pulire tutto”, ma ripristinare lo stato precedente senza perdere accesso al server.

sudo systemctl stop ajenti
sudo systemctl disable ajenti
sudo apt remove --purge ajenti

Se hai aggiunto un vhost in Nginx o una regola firewall, rimuovi solo quelle modifiche e verifica che il resto del server resti raggiungibile. In caso di dubbio, mantieni aperta una sessione SSH attiva prima di chiudere il change.

Quando Ajenti ha senso e quando no

Ajenti ha senso su server singoli, ambienti piccoli o laboratori in cui vuoi una UI rapida per controlli operativi di base. Non è il candidato giusto se ti serve gestione centralizzata estesa, audit profondo o integrazione stretta con flussi di automazione moderni.

Se il tuo obiettivo è amministrare pochi host con un’interfaccia semplice, va bene. Se invece devi governare più nodi, policy rigorose, ruoli granulari e tracciamento completo, conviene valutare strumenti più orientati all’enterprise o lasciare il pannello solo come supporto locale e non come punto di controllo principale.

Checklist finale operativa

Prima di considerare chiusa l’installazione, conferma questi punti:

• systemctl status ajenti mostra active (running);
• curl -I sulla porta del pannello risponde dal localhost;
• l’accesso remoto funziona solo dagli IP previsti;
• il reverse proxy, se presente, termina TLS correttamente;
• hai una nota di rollback con i file toccati.

Assunzione operativa: il pacchetto e lo script di installazione sono disponibili per la tua specifica release; se non lo sono, il passaggio corretto è chiudere il gap con la fonte ufficiale o con un deployment alternativo verificato, non forzare repository non allineati alla versione di Ubuntu.