Chi gestisce un’infrastruttura di rete lo sa bene: switch, router e firewall cambiano configurazione più spesso di quanto si pensi, e quasi sempre ce ne si accorge solo quando qualcosa smette di funzionare.
Avere un backup aggiornato delle configurazioni, sapere chi ha modificato cosa e verificare che ogni apparato rispetti le policy aziendali non è più un lusso, ma un requisito, soprattutto in contesti soggetti a normative come NIS2 o ISO 27001.
Netpicker è una piattaforma pensata proprio per questo. Esegue il backup automatico delle configurazioni degli apparati di rete di molti vendor diversi, ne conserva lo storico in un repository Git e permette di confrontare le versioni.
Consente inoltre di definire regole di compliance da verificare su tutti i dispositivi e di automatizzare le attività ripetitive.
Il tutto si gestisce da un’interfaccia web semplice e si distribuisce come stack Docker, quindi si può installare in pochi minuti su un normale server Linux.
In questo articolo vediamo passo passo come installare Netpicker su Ubuntu Server 26.04 LTS: dalla preparazione del sistema e del firewall all’installazione di Docker Engine e Docker Compose, fino al download del progetto, alla sua configurazione di base e al primo avvio dei container.
Vedremo anche come verificare che tutto funzioni e come risolvere un paio di problemi comuni che si possono incontrare durante l’installazione.
PREREQUISITI
Serve una VM Ubuntu Server 26.04 LTS (amd64) con accesso a Internet e un utente con privilegi sudo.
Netpicker non pubblica requisiti hardware ufficiali; i valori sotto sono indicativi per lo stack completo (circa 15 container).
| Risorsa | Minimo (lab) | Consigliato (produzione) |
|---|---|---|
| vCPU | 2 | 4 |
| RAM | 4 GB | 8 GB |
| Disco | 20 GB | 100 GB |
Porte usate dallo stack:
| Porta | Protocollo | Servizio |
|---|---|---|
| 80 | TCP | Interfaccia web (frontend) |
| 8000 | TCP | API REST |
| 5514 | UDP | Syslog dagli apparati |
| 6601 / 6514 | TCP | Syslog TCP / TLS |
| 9418 | TCP | Git daemon (non esposto di default, opzionale) |
Il server deve poter raggiungere gli apparati in SSH/Telnet e per l’installazione, github.com, download.docker.com e Docker Hub.
PREPARAZIONE DEL SISTEMA
Aggiorna il sistema, imposta hostname e fuso orario e apri solo le porte necessarie.
Aggiorna i pacchetti e installa gli strumenti di base:
|
0 1 |
sudo apt update && sudo apt full-upgrade -y sudo apt install -y git curl ca-certificates |
Imposta hostname e fuso orario (adatta i valori):
|
0 1 |
sudo hostnamectl set-hostname netpicker sudo timedatectl set-timezone Europe/Rome |
Configura UFW, consentendo SSH prima di attivarlo:
|
0 1 2 3 |
sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 5514/udp sudo ufw enable |
ATTENZIONE: Docker pubblica le porte scrivendo direttamente in iptables, quindi le porte mappate dai container (es. 8000) restano raggiungibili anche se UFW non le consente. Se vuoi limitarle, filtra a monte (firewall perimetrale) o usa la catena DOCKER-USER.
Riavvia se è stato aggiornato il kernel: sudo reboot.
INSTALLAZIONE DI DOCKER ENGINE E DOCKER COMPOSE
Usa il repository ufficiale Docker, che supporta Ubuntu 26.04 “Resolute”; evita il pacchetto docker.io di Ubuntu e lo snap.
Rimuovi eventuali pacchetti Docker non ufficiali:
|
0 |
for pkg in docker.io docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt remove -y $pkg; done |
Aggiungi chiave GPG e repository:
|
0 1 2 3 4 5 6 7 8 9 10 11 |
sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc sudo tee /etc/apt/sources.list.d/docker.sources <<EOF Types: deb URIs: https://download.docker.com/linux/ubuntu Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") Components: stable Architectures: $(dpkg --print-architecture) Signed-By: /etc/apt/keyrings/docker.asc EOF |
Quindi aggiornare con il comando:
|
0 |
sudo apt update |
Installa Docker Engine e il plugin Compose:
|
0 |
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin |
Abilita il servizio e aggiungi il tuo utente al gruppo docker (poi esci e rientra in SSH):
|
0 1 |
sudo systemctl enable --now docker sudo usermod -aG docker $USER |
Verificare Docker con i seguenti comandi:
|
0 1 2 |
docker version docker compose version docker run --rm hello-world |
DOWNLOAD E CONFIGURAZIONE DI NETPICKER
Netpicker si distribuisce come repository GitHub con docker-compose.yml e script di gestione (up.sh, down.sh, update.sh, backup.sh, restore.sh).
Clona il repository in /opt:
|
0 1 2 |
sudo mkdir -p /opt/netpicker && sudo chown $USER:$USER /opt/netpicker git clone https://github.com/netpicker/netpicker /opt/netpicker cd /opt/netpicker |
Verifica il GID del gruppo docker. Il servizio api monta /var/run/docker.sock e nel compose usa il GID 999:
|
0 |
getent group docker |
Dovremmo visualizzare un output simile al seguente:
|
0 |
docker:x:983:rchiatto |
Se il GID non è 999, oppure vuoi personalizzare qualcosa, crea un file override (non viene toccato da git pull durante gli aggiornamenti):
|
0 1 |
cp docker-compose.override.yml.sample docker-compose.override.yml nano docker-compose.override.yml |
Esempio da aggiungere sotto services: (sostituisci 988 con il tuo GID; la mappatura 9418 serve solo se vuoi clonare dall’esterno il repository Git dei backup):
|
0 1 2 3 4 5 |
cat > docker-compose.override.yml <<'EOF' services: api: group_add: - "983" EOF |
Il file sample contiene anche, commentate, variabili utili come INIT_PASSWORD (password iniziale dell’admin) e CELERY_CONCURRENCY: decommentale solo se ti servono.
AVVIO DEI CONTAINER E VERIFICA
Avvia lo stack dalla cartella del progetto; il primo avvio scarica le immagini e richiede alcuni minuti.
Avvia Netpicker (lo script esegue docker compose down e poi docker compose up -d):
|
0 1 |
cd /opt/netpicker bash up.sh |
Controlla lo stato: tutti i servizi devono risultare running o healthy, mentre db_migration termina con exited (0) ed è normale.
|
0 |
docker compose ps |
Verifica l’API e il frontend:
|
0 |
curl -s http://localhost:8000/api/v1/status |
Dovremmo visualizzare il seguente output:
|
0 |
{"Meta":{"host":"localhost:8000","user-agent":"curl/8.18.0","accept":"*/*","x-request-id":"ce7d36ad27a54819a63714b3ae4e4cfa"},"api_base":"http://localhost:8000/","tz":"UTC","scheduler_timezone":"UTC","minio-running":"1"}root@vm-srv-test:/opt/netpicker# |
Quindi:
|
0 |
curl -I http://localhost |
Dovremmo visualizzare il seguente output:
|
0 1 2 3 4 5 6 7 8 9 10 11 |
HTTP/1.1 200 OK Server: nginx/1.27.4 Date: Fri, 06 Nov 2026 21:23:49 GMT Content-Type: text/html Content-Length: 8309 Last-Modified: Thu, 08 Oct 2026 09:44:05 GMT Connection: keep-alive ETag: "6ac765e5-2075" Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0 Pragma: no-cache Expires: 0 Accept-Ranges: bytes |
Se un servizio non parte, leggi i log:
|
0 |
docker compose logs -f api |
Dopo un riavvio del server verifica con docker compose ps che lo stack sia ripartito; se non lo è, rilancia bash up.sh.
PRIMO ACCESSO E CONFIGURAZIONE INIZIALE
Apri http://<IP-del-server>/ dal browser e
Accedi con le credenziali predefinite, poi cambia subito la password.
Utente: [email protected]
Password: 12345678
Accettare l‘EULA quindi cliccare Continue
Se è andato tutto a buon fine dovremmo visualizzare la Dashboard di Netpicker
PASSI CONSIGLIATI DOPO IL PRIMO LOGIN
- Cambia la password dell’amministratore dal profilo utente.
- Crea un vault con le credenziali SSH degli apparati: ogni device deve avere un vault associato per potersi collegare.
- Aggiungi i dispositivi (singolarmente o da CSV) indicando IP e piattaforma; il valore della piattaforma deve corrispondere al device_type di Netmiko (es. cisco_ios, fortinet), altrimenti il backup fallisce.
- Lancia un primo backup e verifica lo storico delle configurazioni e i diff.
- Facoltativo: configura gli apparati per inviare syslog al server sulla porta UDP 5514, e l’autenticazione LDAP/SAML/OAuth seguendo la documentazione di autenticazione (https://github.com/netpicker/netpicker blob/main/docs/authentication/README.md).
Per l’uso in produzione pubblica l’interfaccia in HTTPS: il repository include nginx-ssl.conf e la cartella certs come base, oppure metti Netpicker dietro un reverse proxy esistente.
MANUTENZIONE: AGGIORNAMENTO, BACKUP E TROUBLESHOOTING
Tutte le operazioni si eseguono da /opt/netpicker con gli script inclusi nel repository; fai sempre un backup prima di aggiornare.
Backup. backup.sh ferma lo stack e salva tutti i volumi netpicker_* in netpicker_backup.tar nella cartella corrente (file di proprietà di root). Lo stack non riparte da solo:
|
0 1 2 |
bash backup.sh sudo mv netpicker_backup.tar /backup/netpicker_$(date +%F).tar bash up.sh |
Per il ripristino usa restore.sh con lo stesso archivio.
Aggiornamento. update.sh esegue docker compose down, salva una copia di docker-compose.yml, fa git pull, scarica le nuove immagini e riavvia lo stack:
|
0 1 |
bash update.sh docker image prune -f |
PROBLEMI COMUNI
- permission denied su /var/run/docker.sock nei log di api | GID del gruppo docker diverso da 999 | Imposta il GID corretto in group_add nell’override (sezione 3)
- Errori di scrittura su policy, secret o git | Permessi errati sui volumi | bash fix-volume-permissions.sh (riporta i volumi all’UID/GID 911)
- Interfaccia web non raggiungibile subito dopo l’avvio | Container ancora in avvio | Attendi qualche minuto e controlla docker compose ps
- Backup del device fallito | Piattaforma errata o vault mancante | Usa il device_type Netmiko corretto e associa un vault
- Clone del repository Git dei backup non funziona | Porta 9418 non esposta | Aggiungi la mappatura 9418:9418 al servizio gitd
FUNZIONALITA’ – PRO E CONTRO
Funzionalità principali
- Backup delle configurazioni: salva in automatico le configurazioni degli apparati e ne tiene lo storico in un repository Git, con confronto tra versioni (diff) e ricerca nelle configurazioni.
- Supporto multi-vendor: dichiara compatibilità con oltre 150-180 vendor (Cisco, Fortinet, HP/Aruba, Juniper, MikroTik e altri).
- Compliance e testing: le regole si scrivono in Python/pytest e danno esito pass/fail per ogni dispositivo. Servono a verificare hardening, policy e drift della configurazione.
- Automazione: job semplici o in Python, remediation delle non conformità, ripristino della configurazione da file e upgrade dell’OS (quest’ultimo è un add-on).
- Sicurezza: scansione delle vulnerabilità (CVE) degli apparati con il modulo CVEasy.
- Assistente AI: genera regole, job e analisi delle configurazioni a partire da prompt in linguaggio naturale.
- Integrazioni: API REST completa e plugin per NetBox, Nautobot, Infrahub e Slurp’it.
- Deployment: container Docker on-premise. Kubernetes e ambienti air-gapped sono previsti solo nella versione Enterprise.
Pro
- La versione gratuita è utile davvero: backup, diff e automazione senza limite di dispositivi.
- È self-hosted, quindi le configurazioni restano in casa. È un punto importante per NIS2 e ISO 27001.
- Lo storico su Git fornisce una traccia di audit e permette di vedere chi ha cambiato cosa.
- Le regole di compliance sono in Python: flessibili e versionabili.
- Si installa in pochi minuti con Docker Compose.
- Si integra con NetBox e Nautobot come source of truth.
Contro
- Nella versione gratuita la compliance, la remediation e la scansione CVE funzionano solo su 10 dispositivi, mentre sono proprio le funzioni più interessanti per chi deve dimostrare conformità.
- La versione gratuita ammette un solo utente: non va bene se ci lavora un team.
- RBAC, SSO e audit log sono disponibili solo nella versione Enterprise, che costa parecchio.
- La multi-tenancy per MSP è un add-on a pagamento: è un limite se vuoi gestire più clienti separati.
- Lo stack è pesante, con circa 15 container. Mancano requisiti hardware ufficiali e la documentazione è frammentata.
- Il syslog integrato è elencato tra le funzioni Enterprise, anche se il container syslog-ng è presente nello stack gratuito.
- Scrivere regole in pytest richiede un minimo di competenze di programmazione.
In sintesi, per un uso di laboratorio o per backup e versionamento delle configurazioni di una singola realtà la versione Foundation è ottima.
Per un MSP multi-cliente, o se ti serve la compliance su tutto il parco apparati, bisogna mettere in conto la licenza Professional più l’add-on multi-tenancy.
In alternativa conviene confrontarlo con soluzioni come Oxidized + Git (solo backup) o rConfig.
0 Commenti