Ce que fait NetBox
NetBox documente un réseau et l'infrastructure qui le porte. Côté IPAM, il gère les préfixes hiérarchiques, les plages et les adresses IP, les VLAN et les VRF, et calcule l'espace libre de chaque réseau. Côté DCIM, il décrit les sites, les baies et leur élévation, les équipements, leurs interfaces, les câbles et l'alimentation. Les deux se rejoignent : une adresse IP appartient à l'interface d'un équipement, installé dans une baie d'un site.
Le projet est publié sous licence Apache-2.0. La pile Docker officielle, netbox-docker, s'appuie sur PostgreSQL et sur Valkey (ou Redis) pour le cache et la file des tâches de fond. Sur un VPS, l'application et son processus de tâches occupent moins de 1 Go de mémoire au repos.
Ce que NetBox vous donne
- Une source de vérité unique — l'état attendu du réseau, au lieu de dix fichiers qui se contredisent.
- Un IPAM qui calcule — espace libre par préfixe, prochaine adresse disponible, détection des doublons.
- Le plan de vos baies — chaque équipement à sa place, avec ses ports et ses câbles.
- Une API pour chaque objet — REST et GraphQL, documentation OpenAPI servie par l'instance.
- Un journal des modifications — qui a changé quoi, quand, avec l'état avant et après.
- De l'automatisation — webhooks, scripts personnalisés, inventaire dynamique Ansible.
Tableur ou NetBox sur votre VPS
Faites défiler le tableau
| Tableur partagé | NetBox sur votre VPS | |
|---|---|---|
| Adresse attribuée deux fois | Rien ne l'empêche | Signalée à la saisie |
| Espace libre d'un réseau | À recompter à la main | Calculé pour chaque préfixe |
| Lien adresse, équipement, baie | Colonnes recopiées | Objets reliés entre eux |
| Historique des modifications | Versions du fichier | Journal objet par objet |
| Lecture par vos scripts | Export CSV | API REST et GraphQL |
Avant de commencer
Prévoyez un VPS Ubuntu 24.04 avec 2 Go de RAM au minimum, 4 Go pour une équipe, 2 vCPU et 20 Go de disque, avec Docker et le plugin Compose installés. Il vous faut aussi un nom d'hôte qui pointe vers le VPS, par exemple netbox.example.com : NetBox n'accepte les formulaires, connexion comprise, que depuis l'origine déclarée dans CSRF_TRUSTED_ORIGINS, et il sera servi en HTTPS.
Installer NetBox avec Docker Compose
Préparer le dossier et le fichier .env
Le fichier porte les secrets de l'instance.
SECRET_KEYetAPI_TOKEN_PEPPER_1doivent faire au moins 50 caractères : le premier signe les sessions, le second sert au hachage des jetons d'API.mkdir -p /opt/netbox && cd /opt/netbox cat > .env <<EOF DB_PASSWORD=$(openssl rand -hex 16) REDIS_PASSWORD=$(openssl rand -hex 16) SECRET_KEY=$(openssl rand -hex 32) API_TOKEN_PEPPER_1=$(openssl rand -hex 32) SUPERUSER_PASSWORD=$(openssl rand -hex 16) DOMAIN=netbox.example.com EOF chmod 600 .envÉcrire le fichier docker-compose.yml
Quatre services : PostgreSQL, Valkey protégé par mot de passe, NetBox et son processus de tâches de fond. Le port n'est publié que sur la boucle locale : seul nginx sera exposé à Internet.
x-netbox: &netbox image: netboxcommunity/netbox:v4.7.5-5.1.2 restart: unless-stopped user: "netbox:root" environment: &netbox-env DB_HOST: postgres DB_NAME: netbox DB_USER: netbox DB_PASSWORD: "${DB_PASSWORD}" REDIS_HOST: redis REDIS_PASSWORD: "${REDIS_PASSWORD}" REDIS_CACHE_HOST: redis REDIS_CACHE_PASSWORD: "${REDIS_PASSWORD}" REDIS_CACHE_DATABASE: "1" SECRET_KEY: "${SECRET_KEY}" API_TOKEN_PEPPER_1: "${API_TOKEN_PEPPER_1}" SKIP_SUPERUSER: "false" SUPERUSER_NAME: admin SUPERUSER_PASSWORD: "${SUPERUSER_PASSWORD}" LOGIN_REQUIRED: "true" CSRF_TRUSTED_ORIGINS: "https://${DOMAIN}" volumes: - netbox-media:/opt/netbox/netbox/media services: postgres: image: postgres:18.7-alpine restart: unless-stopped environment: POSTGRES_DB: netbox POSTGRES_USER: netbox POSTGRES_PASSWORD: "${DB_PASSWORD}" volumes: - netbox-postgres:/var/lib/postgresql redis: image: valkey/valkey:9.1.3-alpine restart: unless-stopped command: ["valkey-server", "--appendonly", "yes", "--requirepass", "${REDIS_PASSWORD}"] volumes: - netbox-redis:/data netbox: <<: *netbox depends_on: [postgres, redis] ports: - "127.0.0.1:8080:8080" netbox-worker: <<: *netbox depends_on: [netbox] command: ["/opt/netbox/venv/bin/python", "/opt/netbox/netbox/manage.py", "rqworker"] volumes: netbox-postgres: {} netbox-redis: {} netbox-media: {}Démarrer et vérifier
Le premier démarrage applique toutes les migrations de la base et crée le compte
admin: comptez cinq à dix minutes sur un petit VPS. La page de connexion doit répondre200, et la dernière commande affiche le mot de passe administrateur.docker compose up -d docker compose logs -f netbox # attendre « Initialisation is done » curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/login/ grep SUPERUSER_PASSWORD .env
Ne changez jamais les deux secrets après coup
Une nouvelle SECRET_KEY déconnecte tout le monde ; un nouveau API_TOKEN_PEPPER_1 rend invalides tous les jetons d'API déjà émis, et vos scripts tombent en même temps. Sauvegardez le fichier .env avec la base. De même, SUPERUSER_PASSWORD ne sert qu'au premier démarrage : changez ensuite le mot de passe depuis votre profil.
Publier NetBox en HTTPS derrière nginx
NetBox écoute en HTTP sur 127.0.0.1:8080 ; nginx termine le TLS et lui transmet les requêtes. Gardez X-Forwarded-Proto pour que l'application sache qu'elle est servie en HTTPS, et un client_max_body_size suffisant pour les pièces jointes et les imports.
server {
listen 443 ssl;
server_name netbox.example.com;
ssl_certificate /etc/letsencrypt/live/netbox.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/netbox.example.com/privkey.pem;
client_max_body_size 25m;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Si l'origine ne correspond pas à CSRF_TRUSTED_ORIGINS, la connexion échoue avec une erreur 403 « CSRF verification failed » : vérifiez le schéma https:// et le nom exact.
Premiers pas : site, préfixes et adresses
Connectez-vous sur https://netbox.example.com/login/ avec admin. Commencez par créer un site, puis les préfixes que vous utilisez (IPAM, Préfixes) : NetBox les range automatiquement en hiérarchie et affiche le taux d'occupation de chacun. Ajoutez ensuite les équipements (Appareils), leurs interfaces et leurs adresses IP.
Pour reprendre un tableur existant, chaque liste propose un import CSV ou YAML : collez les lignes, NetBox valide chaque champ et refuse l'import entier si une ligne est fausse, ce qui évite les reprises à moitié faites.
Automatiser avec l'API et Ansible
Créez un jeton depuis votre profil, menu Jetons d'API. Il s'utilise dans l'en-tête Authorization: Bearer, et la documentation interactive est servie sur /api/schema/swagger-ui/.
export NETBOX_TOKEN='nbt_xxxxxxxx.yyyyyyyyyyyyyyyy'
curl -s -H "Authorization: Bearer $NETBOX_TOKEN" -H "Accept: application/json" \
"https://netbox.example.com/api/ipam/prefixes/?status=active"
# La prochaine adresse libre d'un préfixe (id 1), réservée en une requête
curl -s -X POST -H "Authorization: Bearer $NETBOX_TOKEN" -H "Content-Type: application/json" \
-d '{"description": "web-01"}' \
"https://netbox.example.com/api/ipam/prefixes/1/available-ips/"Côté Ansible, la collection netbox.netbox fournit un inventaire dynamique : vos hôtes et leurs groupes viennent de NetBox, plus d'un fichier tenu à la main. Le jeton se passe dans la variable d'environnement NETBOX_TOKEN.
# netbox_inventory.yml — ansible-galaxy collection install netbox.netbox
plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
validate_certs: true
group_by: [sites, device_roles]Sauvegarder et mettre à jour
Deux choses à sauvegarder : la base PostgreSQL et le volume des fichiers joints, sans oublier le fichier .env.
cd /opt/netbox
docker compose exec -T postgres pg_dump -U netbox netbox | gzip > netbox-$(date +%F).sql.gz
docker run --rm -v netbox_netbox-media:/media -v "$PWD":/backup alpine \
tar czf /backup/netbox-media-$(date +%F).tar.gz -C /media .Pour mettre à jour, changez le tag de l'image dans docker-compose.yml, puis lancez docker compose pull et docker compose up -d : les migrations sont appliquées au démarrage. Lisez les notes de version avant de changer de version majeure, et faites une sauvegarde juste avant.
NetBox en un clic sur ServOrbit
Le Marketplace ServOrbit installe exactement cette pile : image officielle netbox-docker, PostgreSQL, Valkey et processus de tâches, port publié sur 127.0.0.1 uniquement, secrets générés, compte admin créé, connexion exigée et HTTPS configuré sur votre domaine ou sur le sous-domaine gratuit du VPS. Le mot de passe administrateur s'affiche dans votre espace client.
servorbit.com/ma-fr/blog/self-host-netbox-vps