NetBox: DCIM e IPAM para Gestão de Infraestrutura PME

Introdução: DCIM e IPAM

DCIM (Data Center Infrastructure Management) é a disciplina que gere o equipamento físico de um datacenter ou sala de servidores: servidores, switches, routers, racks, fontes de alimentação, cabos e coolers. O objectivo é saber o que existe, onde está, como está ligado e quem é o responsável.

IPAM (IP Address Management) é a gestão centralizada de espaços de endereçamento IP: subnets, VLANs, atribuições de IPs a interfaces, blocos reservados e segmentação por VRF. Sem IPAM, as PMEs acabam com conflitos de IP, subnets sobrepostas e sem registo de quem usa cada endereço.

O NetBox é uma aplicação web open-source (licença Apache 2.0) que combina DCIM e IPAM numa única plataforma. Foi desenvolvido originalmente na DigitalOcean em 2016 e é agora mantido pela NetBox Labs. A versão actual (4.x, 2026) inclui gestão de circuitos, fontes de energia, consolas, segredos encriptados e um sistema de webhooks nativo.

ℹ Porquê NetBox para uma PME?

Numa PME com 2 ou 3 sites, 50 dispositivos e algumas dezenas de subnets, uma folha de Excel chega a ser suficiente — até deixar de ser. O NetBox resolve três problemas concretos: (1) centraliza o inventário de hardware e rede num modelo hierárquico, (2) elimina conflitos de IP com atribuição controlada via API, e (3) integra com Ansible, Terraform e scripts internos para automatizar provisionamento.

Alternativas: phpIPAM (apenas IPAM, sem DCIM), RackTables (projecto estagnado), Device42 (comercial, caro para PMEs) e NetBox Cloud (versão SaaS paga da NetBox Labs). Para quem prefere self-hosted, o NetBox community edition é gratuito e sem limites.

Instalar com Docker

O método recomendado para produção é o netbox-docker, o repositório oficial da comunidade. Corre PostgreSQL, Redis, NetBox (Django/uWSGI) e o netbox-worker (Celery) em contentores orquestrados pelo Docker Compose.

Requisitos

Os requisitos mínimos para uma instalação PME (até 5000 dispositivos) são modestos: 2 GB de RAM, 10 GB de disco, Docker 24+ e Docker Compose v2. O NetBox corre em qualquer distribuição Linux com Docker — Debian, Ubuntu, AlmaLinux ou Alpine.

Passo a passo

Clonar o repositório e ajustar a configuração base:

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
cp env/production.env .env
docker compose pull
docker compose up -d

O ficheiro .env define variáveis como ALLOWED_HOSTS, SECRET_KEY e DB_PASSWORD. Gerar uma secret key forte:

python3 -c "import secrets; print(secrets.token_urlsafe(50))"

Criar o utilizador administrador inicial:

docker compose exec netbox python manage.py createsuperuser

Após o arranque, a interface web fica disponível em http://servidor:8000. O primeiro login usa as credenciais do superuser criado acima. Para produção, colocar um reverse proxy (Nginx, Caddy ou Traefik) à frente com TLS.

⚠ Atenção: porta 8000 sem TLS

O contentor netbox expõe a porta 8000 sem encriptação. Nunca expor esta porta directamente à internet. Usar sempre um reverse proxy com certificado TLS (Let’s Encrypt) e restringir o acesso com firewall ou VPN.

Inventário e IPs

O NetBox organiza a infraestrutura numa hierarquia clara. Compreender esta hierarquia é essencial antes de começar a registar dispositivos.

Hierarquia de objectos

O fluxo de cima para baixo é: Region (região geográfica) → Site (local físico) → Location (sala/armário dentro do site) → Rack (armário de 19″) → Device (servidor, switch, router) → Interface (porta de rede) → IP Address (endereço atribuído à interface).

Paralelamente, o IPAM gere: VRF (Virtual Routing and Forwarding) → Prefix (subnet em notação CIDR, ex: 10.0.0.0/24) → IP Address (endereço individual). Os Prefixes podem ser agrupados em VLANs e VLAN Groups, e organizados por Tenant (inquilino).

Registar o primeiro site e dispositivo

Na interface web, navegar para Organization → Sites → Add. Definir nome, slug e opcionalmente a região. Depois, em DCIM → Devices → Add, seleccionar o site, o role (servidor, switch, router) e o device type (fabricante + modelo). O device type pode ser importado do repositório devicetype-library que contém milhares de modelos pré-definidos (Dell, HP, Cisco, Juniper, etc.).

Gestão de prefixos e IPs

Em IPAM → Prefixes → Add, registar a subnet (ex: 192.168.10.0/24), associar a um VRF (se aplicável) e definir o status (Active, Reserved, Deprecated). Para atribuir um IP a uma interface, ir a IPAM → IP Addresses → Add, inserir o endereço e seleccionar a interface do dispositivo. O NetBox valida automaticamente se o IP está dentro de um prefixo conhecido e se já está atribuído a outra interface.

✓ Boa prática: Tenants e Tags

Usar Tenants para separar recursos por cliente ou departamento interno. Usar Tags para marcação cruzada (ex: “producao”, “staging”, “critico”). Isto permite filtragens rápidas e relatórios segmentados sem duplicar dados.

Custom fields e flexibilidade

O NetBox permite criar custom fields em qualquer objecto (texto, inteiro, booleano, data, lista, URL). Exemplos úteis para PMEs: “data de compra”, “número de série fiscal”, “localização física” (texto livre para sites sem rack), “contrato de manutenção” (URL para o portal do fornecedor). Os custom fields são pesquisáveis e filtráveis.

API REST e Automação

O NetBox tem uma API REST completa, documentada em OpenAPI/Swagger, acessível em /api/docs/. Tudo o que se faz na interface web pode ser feito via API. Isto é o que torna o NetBox numa fonte de verdade (source of truth) para automação.

Autenticação por token

Em Admin → API Tokens → Add, criar um token. O token é uma string de 40 caracteres alfanuméricos. Pode ser restringido a permissões de leitura/escrita e a IPs específicos. Usar o token no header Authorization: Token ….

# Listar todos os sites
curl -H "Authorization: Token $TOKEN" \
     -H "Accept: application/json" \
     https://netbox.exemplo.pt/api/dcim/sites/

# Criar um novo prefixo
curl -X POST -H "Authorization: Token $TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"prefix":"10.50.0.0/24","status":"active","description":"VLAN 50 - Servidores"}' \
     https://netbox.exemplo.pt/api/ipam/prefixes/

pynetbox (Python)

A biblioteca pynetbox é o cliente Python oficial para a API do NetBox. Instalar com pip install pynetbox.

import pynetbox

nb = pynetbox.api(
    "https://netbox.exemplo.pt",
    token="0123456789abcdef0123456789abcdef01234567"
)

# Listar dispositivos do site "Lisboa"
lisboa = nb.dcim.sites.get(name="Lisboa")
devices = nb.dcim.devices.filter(site_id=lisboa.id)
for d in devices:
    print(f"{d.name} | {d.device_type.model} | {d.status.label}")

# Atribuir IP a uma interface
interface = nb.dcim.interfaces.get(name="eth0", device="srv-01")
nb.ipam.ip_addresses.create(
    address="10.50.0.10/24",
    assigned_object_type="dcim.interface",
    assigned_object_id=interface.id,
    status="active"
)

Ansible e Webhooks

A collection netbox.netbox para Ansible permite usar o NetBox como inventário dinâmico e sincronizar estados. Exemplo de inventory.yml:

plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.exemplo.pt
token: 0123456789abcdef0123456789abcdef01234567
validate_certs: true
group_by:
  - device_roles
  - sites
query_filters:
  - has_primary_ip: true

Os webhooks nativos permitem que o NetBox notifique sistemas externos quando um objecto é criado, actualizado ou eliminado. Por exemplo, ao criar um novo dispositivo, o webhook pode enviar um POST para o Slack, Jenkins ou um script de provisionamento automático. Configurar em Admin → Webhooks → Add.

💡 Dica: Export templates com Jinja2

O NetBox suporta export templates em Jinja2 que geram ficheiros de configuração a partir dos dados registados. Isto permite, por exemplo, gerar automaticamente a configuração de DHCP, DNS ou BGP a partir do inventário — sem scripts externos. Os templates ficam em Admin → Export Templates e podem ser descarregados via API.

Erros Comuns

A tabela seguinte resume os erros mais frequentes em instalações PME do NetBox, com causa e solução para cada caso.

Erro / Sintoma Causa Solução
500 Internal Server Error ao aceder SECRET_KEY não definida ou ALLOWED_HOSTS não inclui o domínio Definir SECRET_KEY no .env e adicionar o domínio a ALLOWED_HOSTS
Migrações não correm na primeira inicialização Contentor PostgreSQL ainda não está pronto quando o NetBox arranca Reiniciar o contentor netbox: docker compose restart netbox — o entrypoint corre migrações automaticamente
403 Forbidden na API Token inválido, expirado ou sem permissões de escrita Recriar o token em Admin → API Tokens e verificar as permissões (Read/Write). Confirmar o header Authorization: Token …
IP não pode ser atribuído a interface O IP não pertence a nenhum prefixo registado no NetBox Criar primeiro o prefixo (ex: 10.50.0.0/24) em IPAM → Prefixes e depois atribuir o IP dentro desse prefixo
Dispositivos não aparecem no inventário Ansible Device sem primary_ip4 definida ou sem platform configurada Atribuir um IP primário ao dispositivo e definir a platform (ex: Linux, Cisco IOS). O filtro has_primary_ip: true exclui dispositivos sem IP primário
docker compose up falha com erro de Redis Versão incompatível da imagem Redis ou porta já em uso Verificar portas em uso com ss -tlnp | grep 6379. Se necessário, mapear para outra porta no docker-compose.override.yml
Interface web lenta ou time-out Base de dados sem índices ou com milhares de objectos sem paginação Correr docker compose exec db psql -U netbox -c "VACUUM ANALYZE;". Para ambientes grandes, activar cache Redis e aumentar CACHE_TIMEOUT
Webhook não dispara netbox-worker (Celery) não está a correr ou URL destino incorrecta Verificar se o contentor netbox-worker está up: docker compose ps. Confirmar a URL do webhook e testar com curl manual

A maioria destes erros ocorre na fase de instalação inicial ou nas primeiras integrações com automação. Uma vez estável, o NetBox exige pouca manutenção — actualizar a imagem Docker a cada novo release (mensal) e fazer backup regular da base de dados PostgreSQL.