Qué hace NetBox
NetBox documenta una red y la infraestructura que la sostiene. En el lado IPAM gestiona prefijos jerárquicos, rangos y direcciones IP, VLAN y VRF, y calcula el espacio libre de cada red. En el lado DCIM describe sitios, racks y su elevación, equipos, sus interfaces, cables y alimentación. Ambos se unen: una dirección IP pertenece a la interfaz de un equipo, instalado en un rack de un sitio.
El proyecto se publica bajo licencia Apache-2.0. La pila Docker oficial, netbox-docker, se apoya en PostgreSQL y en Valkey (o Redis) para la caché y la cola de tareas en segundo plano. En un VPS, la aplicación y su proceso de tareas usan menos de 1 GB de memoria en reposo.
Lo que NetBox le aporta
- Una única fuente de verdad — el estado previsto de la red, en lugar de diez archivos que se contradicen.
- Un IPAM que calcula — espacio libre por prefijo, siguiente dirección disponible, detección de duplicados.
- El plano de sus racks — cada equipo en su sitio, con sus puertos y sus cables.
- Una API para cada objeto — REST y GraphQL, con documentación OpenAPI servida por la instancia.
- Un registro de cambios — quién cambió qué y cuándo, con el estado anterior y posterior.
- Automatización — webhooks, scripts personalizados, inventario dinámico de Ansible.
Hoja de cálculo o NetBox en su VPS
Desplace la tabla
| Hoja de cálculo compartida | NetBox en su VPS | |
|---|---|---|
| Dirección asignada dos veces | Nada lo impide | Señalada al introducirla |
| Espacio libre de una red | Recontado a mano | Calculado para cada prefijo |
| Vínculo dirección, equipo, rack | Columnas copiadas | Objetos vinculados |
| Historial de cambios | Versiones del archivo | Registro objeto por objeto |
| Lectura por sus scripts | Exportación CSV | API REST y GraphQL |
Antes de empezar
Prevea un VPS Ubuntu 24.04 con al menos 2 GB de RAM, 4 GB para un equipo, 2 vCPU y 20 GB de disco, con Docker y el plugin Compose instalados. También necesita un nombre de host que apunte al VPS, por ejemplo netbox.example.com: NetBox solo acepta formularios, incluido el de inicio de sesión, desde el origen declarado en CSRF_TRUSTED_ORIGINS, y se servirá en HTTPS.
Instalar NetBox con Docker Compose
Preparar la carpeta y el archivo .env
Este archivo contiene los secretos de la instancia.
SECRET_KEYyAPI_TOKEN_PEPPER_1deben tener al menos 50 caracteres: el primero firma las sesiones, el segundo sirve para el hash de los tokens de 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 .envEscribir el archivo docker-compose.yml
Cuatro servicios: PostgreSQL, Valkey protegido por contraseña, NetBox y su proceso de tareas en segundo plano. El puerto solo se publica en la interfaz local: solo nginx quedará expuesto a 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: {}Arrancar y comprobar
El primer arranque aplica todas las migraciones de la base y crea la cuenta
admin: cuente de cinco a diez minutos en un VPS pequeño. La página de inicio de sesión debe responder200, y el último comando muestra la contraseña de administrador.docker compose up -d docker compose logs -f netbox # esperar a "Initialisation is done" curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/login/ grep SUPERUSER_PASSWORD .env
No cambie nunca los dos secretos después
Una nueva SECRET_KEY cierra la sesión de todo el mundo; un nuevo API_TOKEN_PEPPER_1 invalida todos los tokens de API ya emitidos, y sus scripts fallan a la vez. Respalde el archivo .env junto con la base. Del mismo modo, SUPERUSER_PASSWORD solo se usa en el primer arranque: después, cambie la contraseña desde su perfil.
Publicar NetBox en HTTPS detrás de nginx
NetBox escucha en HTTP en 127.0.0.1:8080; nginx termina el TLS y le reenvía las peticiones. Conserve X-Forwarded-Proto para que la aplicación sepa que se sirve en HTTPS, y un client_max_body_size suficiente para adjuntos e importaciones.
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 el origen no coincide con CSRF_TRUSTED_ORIGINS, el inicio de sesión falla con un error 403 "CSRF verification failed": compruebe el esquema https:// y el nombre exacto.
Primeros pasos: sitio, prefijos y direcciones
Inicie sesión en https://netbox.example.com/login/ con admin. Empiece creando un sitio y después los prefijos que utiliza (IPAM, Prefijos): NetBox los ordena automáticamente en jerarquía y muestra la ocupación de cada uno. Añada luego sus equipos (Dispositivos), sus interfaces y sus direcciones IP.
Para recuperar una hoja de cálculo existente, cada lista ofrece importación CSV o YAML: pegue las filas, NetBox valida cada campo y rechaza toda la importación si una línea es incorrecta, lo que evita migraciones a medias.
Automatizar con la API y Ansible
Cree un token desde su perfil, menú Tokens de API. Se usa en la cabecera Authorization: Bearer, y la documentación interactiva se sirve en /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"
# Reservar en una petición la siguiente dirección libre de un prefijo (id 1)
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/"En Ansible, la colección netbox.netbox ofrece un inventario dinámico: sus hosts y sus grupos vienen de NetBox, sin archivo mantenido a mano. El token se pasa en la variable de entorno 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]Respaldar y actualizar
Dos elementos que respaldar: la base PostgreSQL y el volumen de adjuntos, sin olvidar el archivo .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 .Para actualizar, cambie la etiqueta de la imagen en docker-compose.yml y ejecute docker compose pull y docker compose up -d: las migraciones se aplican al arrancar. Lea las notas de la versión antes de cambiar de versión mayor y haga una copia justo antes.
NetBox en un clic en ServOrbit
El Marketplace de ServOrbit instala exactamente esta pila: imagen oficial netbox-docker, PostgreSQL, Valkey y el proceso de tareas, puerto publicado solo en 127.0.0.1, secretos generados, cuenta admin creada, inicio de sesión obligatorio y HTTPS configurado en su dominio o en el subdominio gratuito del VPS. La contraseña de administrador aparece en su área de cliente.
servorbit.com/ma-es/blog/autoalojar-netbox-vps-ipam-inventario-red