Guía de despliegue

NetBox en un VPS: IPAM e inventario de red autoalojados

Desplegar en un VPS Cloud →

NetBox en un VPS: IPAM e inventario de red autoalojados

La hoja de cálculo de direcciones IP siempre tiene una línea errónea: una dirección asignada dos veces, un servidor retirado pero nunca borrado, una VLAN que ya nadie sabe explicar. NetBox sustituye ese archivo por una fuente de verdad: cada prefijo, cada dirección, cada rack y cada cable es un objeto vinculado a los demás, consultable en el navegador y gestionable por API. Esta guía lo instala en un VPS con Docker Compose, lo cierra a los visitantes anónimos, lo publica en HTTPS detrás de nginx y lo conecta a sus scripts y a Ansible.

6 min de lectura3 pasos
Contenido· Qué hace NetBox1/11
  1. 01Qué hace NetBox
  2. 02Lo que NetBox le aporta
  3. 03Hoja de cálculo o NetBox en su VPS
  4. 04Antes de empezar
  5. 05Instalar NetBox con Docker Compose
  6. 06No cambie nunca los dos secretos después
  7. 07Publicar NetBox en HTTPS detrás de nginx
  8. 08Primeros pasos: sitio, prefijos y direcciones
  9. 09Automatizar con la API y Ansible
  10. 10Respaldar y actualizar
  11. 11NetBox en un clic en ServOrbit

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 compartidaNetBox en su VPS
Dirección asignada dos vecesNada lo impideSeñalada al introducirla
Espacio libre de una redRecontado a manoCalculado para cada prefijo
Vínculo dirección, equipo, rackColumnas copiadasObjetos vinculados
Historial de cambiosVersiones del archivoRegistro objeto por objeto
Lectura por sus scriptsExportación CSVAPI 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

  1. Preparar la carpeta y el archivo .env

    Este archivo contiene los secretos de la instancia. SECRET_KEY y API_TOKEN_PEPPER_1 deben 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 .env
  2. Escribir 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: {}
  3. 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 responder 200, 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.

Compartir este artículoservorbit.com/ma-es/blog/autoalojar-netbox-vps-ipam-inventario-red