NGINX-UI - un'interfaccia Web per NGINX

Introduzione

Negli articoli passati abbiamo visto come installare NGINX e come configurarlo come Reverse Proxy, ma utilizzare NGINX senza un'interfaccia grafica non è certo una passeggiata.

Per fortuna gli utenti GitHub 0xJacky, Hintay ed Akino hanno creato un'interfaccia web molto bene integrata con NGINX, che può risparmiarci il supplizio di utilizzarlo da riga di comando.

Il progetto si chiama NGINX-UI, non è quindi una soluzione proprietaria, ed offre un'interfaccia web con tutte le sciccherie del caso.

Inoltre, NGINX-UI ci permette di avere una funzionalità normalmente disponibile solo su NGINX PLUS, la versione a pagamento di NGINX: la sincronizzazione della configurazione tra più istanze di NGINX.
Ci tengo a specificare che non si tratta della stessa sincronizzazione presente in NGINX PLUS, ma una versione più leggera e "alla mano".

In questa guida vedremo insieme come installare ed utilizzare NGINX-UI.

Prerequisiti

Per seguire i passaggi di questa guida, è necessario avere già uno o più nodi di NGINX installati e funzionanti.

Installazione

(testato su Ubuntu Server 24.04)

Eseguiamo lo script di installazione di NGINX-UI scaricandolo da github

sudo bash -c "$(curl -L https://raw.githubusercontent.com/0xJacky/nginx-ui/main/install.sh)" @ install

Una volta terminato lo script di installazione, accedere tramite browser alla Web UI di NGINX-UI, di default sulla porta 9000 (http://indirizzo.IP.di.NGINX:9000)

Seguire lo wizard di configurazione creando un account con email, username e password ma lasciando vuoto il campo database.

Effettuate il login con le credenziali appena indicate e verrete accolti dalla dashboard principale, che vi permetterà di tenere sott'occhio le risorse del nodo NGINX.

Una breve panoramica

Andiamo ora a vedere le funzionalità più importanti dell'interfaccia web di NGINX-UI.

Sites list

Utilizzando la barra a sinistra, navigando in Manage Sites → Sites List è possibile consultare la lista dei sites presenti in /sites-available

Provando a modificare un site, avremo davanti una schermata come quella in foto

In questo esempio ho attivato la Advanced Mode, che permette di modificare il site scrivendo manualmente il contenuto del file, ma è possibile usare la Basic Mode per chi preferisce un wizard di configurazione.

il flag Enabled/Disabled rimuove o crea il symlink in /sites-enabled, in modo da permetterci di creare la configurazione ma lasciarla diattivata.

Sotto a Synchronization, è possibile spuntare le varie istanze di NGINX censite (come farlo è spiegato nell'ultimo capitolo di questo articolo) per sincronizzare questo file anche su quei nodi.

Manage Configs

Premendo su Manage Configs sulla barra a sinistra, ci troveremo davanti una lista molto simile a quella di Sites List, popolata invece dai file di configurazione di NGINX.

Da questa schermata è per esempio possibile modificare il file nginx.conf

Anche per i file di configurazione è disponibile un'interfaccia di modifica, con la possibilità di sincronizzare le modifiche con le altre istanze di NGINX.

Certificates

Andando su Certificates → Certificates List è possibile aggiungere i propri certificati per utilizzarli poi nei sites, e vedere quelli già censiti con la relativa scadenza.

Per aggiungere il vostro certificato, premete su Import e date un nome al vostro certificato (vi permetterà di riconoscerlo all'interno dell'interfaccia web)

Nella sezione Sync to selezionate le istanze di NGINX su cui volete propagare questo certificato, poi incollate in Certificate Content e Certificate Key Content i contenuti dei due files del vostro certificato, infine salvate.

Configurazione iniziale

Correggere il puntamento al file error.log

Di default, NGINX-UI (perlomeno la versione 2.0.0 disponibile in questo momento) ha un puntamento errato al file error.log di NGINX. Per correggerlo, modificare l'impostazione nel file di configurazione di NGINX-UI.

nano /usr/local/etc/nginx-ui/app.ini

Modificare il parametro ErrorLogPath indicando il percorso di default del file di log degli errori di NGINX

ErrorLogPath    = /var/log/nginx/error.log

Chiudere il file salvando, poi riavviare NGINX-UI

sudo systemctl restart nginx-ui

Come creare una regola di Reverse Proxy

Andare in Manage Sites → Add Site

in Configuration Name indichiamo un nome che ci aiuti a riconoscere questa regola nella lista

Sotto a Directives, impostare le due direttive listen indicando le porte su cui il reverse proxy dovrà rimanere in ascolto.

in server_name indicare la radice del sito per cui NGINX deve rimanere in ascolto.

Creare una nuova location, per esempio con path /

Il contenuto della location dipende da cosa dovete fare. Per creare una regola semplicissima di reverse proxy in http bastano tre righe:

• proxy_pass http://indirizzo.ip.del.backend:porta; per dire ad NGINX quale sia il server di backend per cui deve fare da tramite
• include /etc/nginx/conf.d/reverse_proxy.conf; per includere le tre direttive proxy_set_header che abbiamo creato nei passaggi precedenti
• proxy_set_header Host "FQDN del servizo"; per riscrivere l'intestazione "Host" della richiesta. Questo, se impostato diversamente dal server_name, cambia l'URL che viene visualizzato sul browser del client

In questo esempio, se ad NGINX arriva una richiesta sulla porta 80 che cerca "test.firenetwork.it", la richiesta viene girata a 192.168.0.1

Come creare una regola di Reverse Proxy con terminazione SSL

NGINX può fare anche da terminatore SSL, cioè può rimanere in ascolto sulla porta 443, con certificato, ed inoltrare la richiesta in HTTP al server di backend.

Questa funzionalità è molto utile se si stanno usando servizi di backend che non supportano HTTPS o che ne hanno una implementazione molto complessa.

Inoltre facendo svolgere ad NGINX il compito di criptare il traffico con HTTPS, si può avere un unico punto dove caricare e tenere aggiornato il certificato.

Per creare una regola di Reverse Proxy con SSL Termination, procedere come segue.

• Indicare una Configuration Name che ci aiuti in seguito a riconoscere facilmente la regola
• Cancellare le direttive root e index

• Aggiungere una direttiva return con valore 404

Aggiungere una direttiva di tipo multi-line directive col seguente contenuto

if ($host = test.firenetwork.it) {
  return 301 https://$host$request_uri;
}

Questa direttiva ci permette di dire al browser, che cerca di accedere in http, che il sito è disponibile in https. Provvederà poi lui a ricontattarci in https.

• Premere su Next per procedere alla configurazione di SSL
• Spuntare "Enable TLS" e dare OK al messaggio di conferma

• Nella sezione custom indicare le seguenti direttive

map $http_upgrade $connection_upgrade {
  default upgrade;
  '' "";
}

questo map ci permette di tenere in vita le sessioni websocket che altrimenti verrebbero chiuse al primo reindirizzamento.

• in upstream premere su create ed indicare un nome da utilizzare in seguito.

• Compilare l'upstream come segue

cambiare il valore di server indicando IP e porta del server di backend in http

• nella sezione Server assicurarsi di aver selezionato Server 2 (Server 1 è il server HTTP che abbiamo configurato prima)
• Premere su Change certificate e selezionare il certificato da associare al servizio (deve prima essere stato aggiunto da Certificates → Certificates List → Import)
• Nelle direttive, compilare i campi presenti nello screenshot e cancellare quelli superflui

• Infine creare una nuova location sulla root dell'indirizzo ("/") col seguente contenuto

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
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;
proxy_pass http://test-default;

Concludere l'operazione di aggiunta ed il site sarà già attivo su questa istanza di NGINX.

Per propagare il site su altri eventuali nodi di NGINX, spuntarli alla voce Synchronization e salvare.

Installare NGINX-UI su più istanze di NGINX e metterle in sincronizzazione

Seguire i passaggi indicati alla sezione Installazione di NGINX-UI su tutte le macchine, e designarne una come nodo principale.

Nei nodi secondari:

• Nel menu a sinistra, premere su Preferences
• Spostarsi sulla tab Node
• Copiarsi il Node Secret associato a questo nodo
  • Se non è valorizzato, ricaricare la pagina con F5
• Indicare in Node Name un nome che identifichi questa istanza di NGINX

Nel nodo principale:

• Nel menu a sinistra, premere su Preferences
• Spostarsi sulla tab Node
• Impostare il Node name
• Nel menu a sinistra, premere su Environments
• Premere su Add in alto a destra e censire tutti i nodi secondari, uno alla volta, coi seguenti parametri:
  • Name: il Node Name indicato nei passaggi precedenti
    - URL: http://indirizzo.istanza.di.NGINX:9000
    - NodeSecret: il Node Secret di quell'istanza, copiato precedentemente
    - Enabled: attivare la spunta per abilitare la gestione di questa istanza
• Una volta che sono stati aggiunti tutti i nodi, ricaricare la pagina e controllare che lo Status sia Online su tutte le righe

Ora creiamo una Site Category a cui associare i nostri sites, per permetterci di sincronizzarli su tutte le istanze di NGINX:

• Accedere al nodo principale
• Nel menu a sinistra, premere su Manage Sites, poi su Site Categories
• Aggiungere una categoria premendo Add in alto a destra, compilandola come segue:
  • Name: default
    - Spuntare tutti i Sync Nodes proposti

Propagare le modifiche fatte in precedenza sulle altre istanze

Se avete seguito tutti i passaggi indicati finora in questa guida, ci sono alcune personalizzazioni che abbiamo fatto sull'istanza principale di NGINX ma che non abbiamo ancora propagato alle istanze secondarie.

Per farlo:

• in Manage Sites → Sites List modificare il site nginx_status, spuntare tutti i nodi NGINX e premere su Save
• in Manage Configs modificare il file nginx.conf, spuntare tutti i nodi NGINX e premere su Save
• sempre in Manage Configs modificare la cartella conf.d, poi modificare il file reverse_proxy.conf al suo interno, spuntare tutti i nodi NGINX e premere su Save