NetBox: relatório analítico e guia de

especialização
Resumo executivo
NetBox é uma plataforma “network source of truth” (fonte autoritativa) para modelar, documentar e
automatizar redes modernas, combinando disciplinas clássicas como DCIM e IPAM com APIs (REST e
GraphQL), extensibilidade (plugins) e mecanismos de automação orientados a eventos (event rules,
webhooks, scripts). A filosofia de design enfatiza refletir o mundo real (por exemplo, IPs vinculados a
interfaces, não ao “dispositivo” abstrato), representar o estado desejado (ideal state) e manter o núcleo
simples, delegando outras funções (monitoramento, DNS, RADIUS etc.) para ferramentas externas
integradas. 1

Do ponto de vista arquitetural, o NetBox (Community) é uma aplicação Django/Python executada como
serviço WSGI atrás de um servidor HTTP (nginx/Apache) e um servidor WSGI (gunicorn/uWSGI),
persistindo dados em PostgreSQL e usando Redis/django-rq para cache e filas de tarefas (jobs,
webhooks, sincronizações etc.). Isso cria uma separação clara entre: camada web (HTTP/WSGI), camada
transacional (PostgreSQL) e camada assíncrona (Redis + workers). 2

Na camada de integração, a REST API é o ponto central para CRUD e automação; a documentação
interativa, gerada via OpenAPI, fica disponível no próprio NetBox em /api/schema/swagger-ui/ , e
a API pode ser explorada via interface navegável em /api/ . A autenticação evoluiu com tokens v2
(padrão “Bearer”) e melhorias de segurança; há também endpoint específico para provisionamento
inicial de token e endpoint para validação de credenciais. 3

Para virar especialista, o domínio prático passa por: (a) modelagem correta do seu ambiente (DCIM/
IPAM/serviços/circuitos/VPN/wireless/virtualização), (b) governança operacional (permissões baseadas
em objetos, change logging, retenções e backups), (c) performance e escalabilidade (tuning WSGI/
workers/limites de paginação/filtragem eficiente), e (d) automação avançada (config rendering,
synchronized data, scripts, webhooks/event rules, Ansible/SDKs/plugins). 4

Visão geral e arquitetura

Origem e governança do projeto. O NetBox foi criado em 2015 por Jeremy Stretch 5 enquanto
trabalhava como engenheiro de redes na DigitalOcean 6 , com foco em automatizar provisionamento
de rede; em 2016 o projeto foi aberto como open source e, atualmente, o projeto open source é
mantido por NetBox Labs 7 e mantenedores voluntários. 8

Papel (o que é e o que não é). A documentação posiciona o NetBox como repositório do estado
pretendido (desired state), desencorajando importação automatizada do estado operacional “ao vivo”
sem validação humana — justamente para preservar integridade da fonte de verdade. Também
delimita escopo: NetBox não é ferramenta de monitoramento, servidor DNS, servidor RADIUS, sistema
de configuração (config management) nem gestão predial (facilities management), mas é altamente
eficaz em alimentar ferramentas externas com dados confiáveis. 8

1
Stack do NetBox Community (auto-hospedado). O NetBox é construído sobre Django (Python), utiliza
PostgreSQL (v14+) como banco, e roda como serviço WSGI atrás de um servidor HTTP (nginx/Apache) e
um servidor WSGI (gunicorn/uWSGI). Redis (v4+) com django-rq é usado para cache e enfileiramento/
execução assíncrona de tarefas. 2

Distribuições/edições (visão operacional). Além do Community, há ofertas “Cloud” (SaaS gerenciado)

e “Enterprise” (distribuição self-hosted com experiência simplificada de instalação/upgrade e recursos
corporativos). O NetBox Enterprise, conforme documentação, utiliza um cluster Kubernetes embutido
(k0s) e inclui console administrativo (KOTS), opções de componentes embutidos ou externos
(PostgreSQL, Redis, storage S3-compatível), gestão de plugins e mecanismos de backup/restore
(detalhes variam por versão/guia). 9

Arquitetura do NetBox Enterprise (alto nível). Em ambientes Kubernetes/Helm, a documentação

descreve um operador (“nbe-operator”) que reconcilia o estado desejado de um recurso customizado
NetBoxEnterprise em recursos Kubernetes em ordem canônica (DB/cache/secrets/config/
deployments/jobs/services/ingress etc.), com mecanismos de “suspend” para troubleshooting. 10

Diagrama de arquitetura (referência prática)

flowchart LR
U[Usuários & ferramentas] -->|HTTPS| H[Servidor HTTP<br/>(nginx/Apache)]
H -->|WSGI| W[WSGI server<br/>(gunicorn/uWSGI)]
W --> A[Aplicação NetBox<br/>(Django/Python)]
A -->|SQL| P[(PostgreSQL)]
A -->|cache/queues| R[(Redis)]
R --> Q[Workers RQ<br/>(rqworker)]
Q -->|tarefas assíncronas| T[Jobs: webhooks, scripts, sync datasources,
etc.]

A separação entre requisições síncronas (HTTP/WSGI) e execução assíncrona (Redis + rqworker) é

explicitada tanto no stack geral quanto nas rotinas de webhooks e jobs. 11

Principais funcionalidades e módulos

A documentação lista um conjunto amplo de capacidades “core”, cobrindo inventário físico,
endereçamento, circuitos, overlays, VPN, wireless, governança e automação/eventos. 12

2
Mapa comparativo: módulos, foco e objetos centrais

Superfícies de
Foco
Domínio Exemplos de objetos (modelos) automação
operacional
“nativas”

REST/
GraphQL;
Presença física, [Link] , [Link] ,
webhooks/
racks, [Link] , [Link] ,
event rules;
DCIM dispositivos, [Link] , [Link]/
scripts/jobs;
cabeamento, PowerFeed , [Link]/
SVG
energia ModuleType
(elevations/
trace)

API + “next
Prefixos, IPs, available”;
[Link] , [Link] ,
VRFs, VLANs, filtros;
IPAM [Link] , [Link] , [Link] ,
ASNs, serviços templates/
[Link]
L7 dados de
contexto

API;
integração
Clusters e VMs [Link] ,
Virtualização com IPAM;
junto do físico [Link]
scripts;
integrações

Provedores, API; link com

[Link] ,
circuitos, DCIM via
[Link] ,
Circuits terminação A/ terminação/
[Link] ,
Z, “black-box cabo; eventos/
[Link]
networks” webhooks

Túneis (GRE/ API; eventos/

[Link] ,
IPsec etc.), webhooks;
[Link] ,
VPN políticas IKE/ modelagem
[Link] , [Link] ,
IPsec, L2VPN overlay/
vpn.L2VPN
overlays underlay

API; eventos;
WLANs e [Link] ,
Wireless associação
enlaces PTP [Link]
com VLAN

API +
Config
OpenAPI;
rendering, [Link]/DataFile ,
Provisionamento/ synchronized
dados extras (templates, scripts, webhooks,
Extensões data;
sincronizados, config contexts)
webhooks;
scripts, plugins
jobs; plugins

A lista de apps/modelos e sua classificação (primary/organizational/nested/component/connection)

está consolidada no índice oficial de modelos. 13

3
DCIM (infra física, conexões e energia)

Facilities (hierarquia física). O módulo de Facilities estrutura desde regiões e grupos de sites até sites,
locations e racks, permitindo hierarquias recursivas (ex.: continente → país → estado → cidade) e
separação entre agrupamento geográfico (Regions) e funcional (Site Groups). 14

Racks e elevações. O modelo Rack representa racks 2-post/4-post e exige associação a um site (e
opcionalmente a uma location). A documentação também destaca elevações de rack com renderização
SVG, inclusive com endpoints dedicados para elevação/visualização em API (histórico e melhorias
aparecem em release notes). 15

Devices, device types e cabeamento. Device types definem atributos físicos e os componentes
(console/power/interfaces etc.), e o NetBox modela cabos como conexões entre terminais compatíveis,
aplicando validações para impedir conexões incoerentes. Há suporte à modelagem modular (módulos/
line cards) e a renomeação automática de componentes “templated” conforme o slot/baia onde um
módulo é instalado. 16

Energia (power panels/feeds). O recurso de Power Tracking permite modelar painéis de energia e
feeds (circuitos), além de conexões com portas de energia; também suporta topologias de energia
primária vs redundante. 17

IPAM (endereçamento, segmentação e “next available”)

O IPAM é descrito como um núcleo do NetBox, com paridade IPv4/IPv6, VRFs, hierarquia automática e
recursos associados. 18

Provisionamento automático (“next available”). A documentação de release notes registra endpoint

específico para obter/criar o próximo IP disponível dentro de um prefixo ( /api/ipam/prefixes/
<pk>/available-ips/ ), com GET (lista de IPs disponíveis) e POST (cria e retorna o próximo). O
“automatic provisioning of next available prefix/IP” também aparece como capability-chave do produto.
19

Objetos IPAM relevantes para especialização. Prefixos ( [Link] ) e faixas ( [Link] )

são objetos próprios, com VRF opcional; a evolução do modelo (ex.: mark_populated em IPRange)
aparece em release notes e impacta regras de alocação. 20

Virtualização

O NetBox modela clusters e máquinas virtuais ao lado do inventário físico; VMs se comportam de forma
semelhante a devices em termos de interfaces e atribuições de IP/VLAN, mas sem atributos físicos e
sem cabeamento físico. 21

Circuits

O NetBox é apresentado como adequado para gestão de provedores (transit/peering), circuitos e

“provider networks” (representação de redes do provedor como “black box”), incluindo a possibilidade
de conectar circuitos a interfaces de dispositivos via cabos. O modelo de terminação de circuito prevê
até duas terminações (A/Z) e pode se conectar a site, interface (via cabo) ou provider network. 22

4
VPN e overlays

O módulo VPN cobre túneis privados (GRE, IP-in-IP, IPSec), topologias peer-to-peer e hub-and-spoke,
além de políticas IKE/IPSec. Há também suporte a L2VPN/overlays (VXLAN/EVPN etc.) conectando
VLANs/interfaces ao overlay para rastrear relações overlay ↔ underlay. 23

Wireless

Wireless LANs (SSIDs e parâmetros de autenticação), grupos hierárquicos e wireless links ponto-a-ponto
são suportados; wireless links exigem exatamente duas interfaces wireless (lado A e B) e possuem
status operacional. 24

Provisionamento, governança e extensibilidade

Config rendering e context data. O NetBox pode renderizar configurações via templates Jinja2 e
dados de contexto (config contexts), com o objeto-alvo exposto como device / virtualmachine .
Config contexts podem ser combinados/“sobrepostos” por peso e critérios (site/region/role/tenant/tag
etc.), viabilizando governança de parâmetros (ex.: syslog servers por região e exceções por role). 25

Webhooks + event rules + execução assíncrona. Webhooks são emitidos sob controle de Event Rules;
payload pode ser customizado via Jinja2 com contexto rico (evento, timestamp, object_type, username,
request_id, data e snapshots). A entrega é enfileirada no Redis e processada pelo rqworker ,
permitindo que a requisição do usuário finalize sem esperar o HTTP outbound do webhook. 26

Auditoria e histórico. Change logging registra criação/alteração/exclusão com snapshots JSON e

request ID correlacionável, além de endpoint read-only para object-changes . Journaling adiciona
notas persistentes (humanas) por objeto. Há parâmetros de retenção (ex.: CHANGELOG_RETENTION )
com alertas de crescimento de banco se retenção for indefinida. 27

Plugins e extensão do modelo/das APIs. Plugins são apps Django instaladas ao lado do NetBox,
podendo adicionar modelos, views, conteúdo de UI, endpoints REST/GraphQL e middleware; porém, a
própria documentação alerta que a API de plugins é “limitada por escopo” e que elementos internos
não documentados podem mudar sem aviso, exigindo disciplina para evitar breaking changes. 28

API REST: autenticação, endpoints, padrões e exemplos

Fundamentos e documentação interativa (OpenAPI)

A REST API viabiliza CRUD sobre a maioria dos modelos e é descrita como principal meio de integração/
automação. A documentação interativa (OpenAPI) é disponibilizada no próprio NetBox em /api/
schema/swagger-ui/ , e a navegação “browsable API” pode ser explorada em /api/ . 29

Além disso, a documentação de performance apresenta recursos importantes para consumidores da

API: modo “brief”, seleção de campos via fields , paginação com limit , e limites máximos via
MAX_PAGE_SIZE . 30

5
Autenticação por tokens (v1 e v2) e controles de segurança

Tokens como identidade do cliente. Tokens mapeiam clientes a contas de usuário e permissões.
Tokens não podem ser recuperados em plaintext após criação, exigindo armazenamento seguro
imediato. 31

v2 tokens (recomendado) vs v1 tokens (legado). A documentação descreve que, a partir do NetBox

v4.5, existem tokens v1 e v2; usuários são incentivados a usar v2, e o suporte a v1 será removido em
release futura. Tokens v2 usam cabeçalho Authorization: Bearer nbt_<key>.<token> ,
enquanto v1 usa Authorization: Token <token> . A release 4.5 enfatiza melhorias de segurança
(hash/HMAC com “cryptographic pepper”). 32

Restrições e hardening. Tokens podem ser “write enabled” ou restritos a leitura e podem ser limitados
por IPs/Prefixos permitidos. Em mecanismos que “isenta” view permissions
( EXEMPT_VIEW_PERMISSIONS ), leituras podem ser liberadas sem token, mas isso é uma decisão
explícita de segurança. 33

Provisionamento inicial de token via API. Há endpoint específico /api/users/tokens/

provision/ para criar token via username/senha quando necessário (cenários de bootstrap). 31

Validação de credenciais. Release notes do v4.5 introduzem /api/authentication-check/ para

testar credenciais da REST API. 34

Estrutura de endpoints por app (visão prática)

A organização por “apps” é refletida tanto na API quanto em SDKs: DCIM, IPAM, circuits, virtualization,
tenancy, extras, users, wireless, core e vpn (entre outros). Em pyNetBox, por exemplo, isso aparece
como [Link] , [Link] , [Link] , [Link] , [Link] , [Link] ,
[Link] , [Link] , [Link] , [Link] . 35

Exemplos de endpoints frequentemente usados (não-exaustivo):

• Sites (DCIM): /api/dcim/sites/ 36

• Dispositivos (DCIM): /api/dcim/devices/ 37

• Prefixos/IPs (IPAM): /api/ipam/prefixes/ , /api/ipam/ip-addresses/ , e “next

available”: /api/ipam/prefixes/<pk>/available-ips/ 38

• Mudanças/auditoria: /api/extras/object-changes/ 39

• Upload de scripts: /api/extras/scripts/upload/ 40

Quando houver dúvida de campos obrigatórios/serializers e filtros válidos, a fonte mais confiável é a
documentação OpenAPI no /api/schema/swagger-ui/ da instância em execução. 41

Padrões de requisição/resposta e correlação

CRUD e bulk operations. A documentação descreve criação via POST no endpoint “list”, bulk delete
via DELETE no endpoint “list” com lista de IDs, e alerta que bulk delete é “all-or-none”. 31

Changelog messages por API. Objetos suportam campo changelog_message para registrar
justificativa/histórico em change logging durante create/update/delete. 42

6
Headers úteis. O header X-Request-ID pode ser usado para correlacionar requisições com change
records, e API-Version reporta a versão de API (alinhada à versão do NetBox). 42

Exemplos de chamadas e payloads (curl)

Listar sites com token v2 (Bearer):

curl -H "Authorization: Bearer nbt_<key>.<token>" \

-H "Accept: application/json; indent=4" \
[Link]

32

Criar um site com mensagem de changelog:

curl -s -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
[Link] \
--data '{
"name": "Site A",
"slug": "site-a",
"changelog_message": "Adding a site for ticket #4137"
}'

31

Bulk delete (ex.: deletar sites por ID):

curl -s -X DELETE \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
[Link] \
--data '[{"id": 10}, {"id": 11}, {"id": 12}]'

31

Provisionar token via username/senha (bootstrap):

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
[Link] \
--data '{"username":"<user>","password":"<pass>"}'

31

7
Upload de arquivo (image attachment) via form-data (exige endpoint e campos apropriados):

curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
-F "object_type=[Link]" \
-F "object_id=2" \
-F "name=[Link]" \
-F "image=@local_file.png" \
[Link]

43

Boas práticas para consumidores da API (performance e segurança)

Reduzir payload e tempo de consulta. A documentação recomenda ?brief=True para listas

simples e fields= para seleção de campos, além de paginação cuidadosa (e limite imposto por
MAX_PAGE_SIZE , default 1000). 30

Erros de filtragem e “full table scan”. O NetBox não valida filtros em GET ; filtros incorretos podem
retornar tabelas inteiras silenciosamente (efeito: lentidão inesperada). pyNetBox oferece validação
( strict_filters ) usando a especificação OpenAPI. 44

Modelos de dados e relacionamentos

Como pensar o modelo do NetBox

A documentação define “modelo” como objeto discreto (ex.: device, IP address), implementado como
classe Django com tabela própria em PostgreSQL, e usa content types para referenciar modelos na
forma app_label.model (ex.: [Link] ). A combinação de content type e primary key
forma um identificador global (ex.: [Link] ). 45

O índice de modelos também apresenta uma “features matrix”, na qual capacidades (change logging,
event rules, tags, jobs, journaling etc.) são habilitadas por mixins e, desde v4.4, plugins podem registrar
features próprias. 46

Macroclassificações úteis para especialistas

• Primary models: usados para modelar a infraestrutura (ex.: [Link] ,

[Link] , [Link] , [Link] , [Link] ). 45

• Organizational models: classificações (roles, manufacturers, RIRs, VLAN groups etc.). 45

• Nested group models: hierarquias recursivas (Region, SiteGroup, Location, TenantGroup etc.).
47

• Component models: componentes de devices/VMs (interfaces, ports, bays etc.). 48

• Connection models: terminação/ligação entre domínios (CircuitTermination,

TunnelTermination). 49

8
Diagrama ER (mermaid) de relacionamentos centrais

Observação: o modelo completo do NetBox é amplo; abaixo está um recorte “core” para
raciocínio arquitetural e automação. O site não fornece um ERD único consolidando
todos os modelos; este diagrama é uma síntese baseada nas descrições e índices oficiais.
50

erDiagram
REGION ||--o{ SITE : contains
SITEGROUP ||--o{ SITE : groups
SITE ||--o{ LOCATION : contains
LOCATION ||--o{ RACK : contains
RACK ||--o{ DEVICE : houses

MANUFACTURER ||--o{ DEVICETYPE : makes

DEVICETYPE ||--o{ DEVICE : instantiates
DEVICE ||--o{ INTERFACE : has
DEVICE ||--o{ CABLE : terminates
INTERFACE ||--o{ IPADDRESS : assigned
PREFIX ||--o{ IPADDRESS : contains
VRF ||--o{ PREFIX : contains
VRF ||--o{ IPADDRESS : scopes

CLUSTERTYPE ||--o{ CLUSTER : types

CLUSTER ||--o{ VIRTUALMACHINE : runs
VIRTUALMACHINE ||--o{ VMINTERFACE : has
VMINTERFACE ||--o{ IPADDRESS : assigned

PROVIDER ||--o{ CIRCUIT : supplies

CIRCUIT ||--o{ CIRCUITTERMINATION : has
CIRCUITTERMINATION }o--|| SITE : terminates_at
CIRCUITTERMINATION }o--|| INTERFACE : connects_via_cable

TUNNELGROUP ||--o{ TUNNEL : groups

TUNNEL ||--o{ TUNNELTERMINATION : terminates
TUNNELTERMINATION }o--|| INTERFACE : endpoint
TUNNELTERMINATION }o--|| VMINTERFACE : endpoint

WIRELESSLANGROUP ||--o{ WIRELESSLAN : groups

WIRELESSLAN }o--|| VLAN : optionally_bound
WIRELESSLINK }o--|| WIRELESSINTERFACE : sideA
WIRELESSLINK }o--|| WIRELESSINTERFACE : sideB

TENANT ||--o{ SITE : owns

TENANT ||--o{ DEVICE : owns
TENANT ||--o{ PREFIX : owns
TENANT ||--o{ IPADDRESS : owns
TENANT ||--o{ CIRCUIT : owns
TENANT ||--o{ VIRTUALMACHINE : owns

9
Os relacionamentos apresentados refletem: hierarquia física (facilities), modelagem de VMs/clusters,
terminação de circuitos e conexões, VPN tunelada com múltiplos endpoints, wireless LANs/links e
atribuição de “tenancy” a múltiplos objetos. 51

Melhores práticas de instalação, backup, upgrade, segurança e

desempenho

Instalação (Community)

Plataforma e dependências. O guia de instalação foi testado em Ubuntu 24.04 e lista versões
suportadas: Python 3.12–3.14, PostgreSQL 14+, Redis 4.0+. Em outras distros, comandos e
dependências podem variar. 52

PostgreSQL. NetBox requer PostgreSQL 14+ e não suporta MySQL nem outros RDBMS. O guia inclui
criação de DB/usuário e recomenda senha forte e encoding UTF8 (evitando SQL_ASCII ). 53

Redis. Redis é usado para cache e filas (queuing) e o guia sugere validação simples ( redis-cli ping
→ PONG ). 54

Servidor WSGI/HTTP. O HTTP server (nginx/Apache) faz o front-end e repassa para o WSGI server
(gunicorn/uWSGI). A documentação alerta que algumas partes (como elevações de rack) dependem de
objetos embutidos e que o reverse proxy não deve sobrescrever X-Frame-Options . 55

Backup e restauração

Backup de banco (Community): o guia “Replicating NetBox” recomenda práticas do PostgreSQL e

exemplifica uso de pg_dump para export e psql para restore; sugere excluir dados volumosos de
changelog ( core_objectchange ) quando o objetivo for replicação para desenvolvimento. 56

Itens além do banco: no processo de upgrade, a documentação lembra de replicar mídia (uploads),
scripts e reports, e isso também se aplica a backups: além do dump do banco, garanta cópia
consistente de MEDIA_ROOT , scripts e reports conforme configuração. 57

Retenção (impacto em backup e tamanho): CHANGELOG_RETENTION e JOB_RETENTION são 90

dias por padrão; retenção indefinida exige limpeza periódica para evitar crescimento sem limite do
banco. 58

Upgrade

O procedimento recomendado enfatiza: revisar release notes, fazer backup antes de iniciar, observar
regra de upgrade de major versions (somente a partir do minor mais recente da major anterior),
atualizar dependências, instalar nova versão (mantendo método original), rodar [Link] (rebuild
venv, dependências, migrations, build docs, collectstatic etc.) e reiniciar serviços ( netbox e netbox-
rq ). 59

Segurança

Hardening de contas e sessões. Há configuração padrão de validadores de senha (mínimo 12

caracteres e exigência alfanumérica/complexidade), com recomendação de não desabilitar. 60

10
CORS/CSRF e superfícies web. Parâmetros como CORS_ORIGIN_ALLOW_ALL , whitelists e CSRF_*
são expostos, reforçando que o NetBox opera como aplicação web completa e deve ser alinhado ao seu
modelo de ameaça. 60

Permissões baseadas em objetos (OBP). O framework de permissões permite ações por subconjunto
arbitrário de objetos usando constraints em JSON (Django query filters), inclusive OR via lista e token
$user . Isso é central para separar “quem pode ver/modificar o quê” em instalações multi-times/multi-
tenancy. 61

Webhooks e risco de template injection. A documentação traz um aviso explícito: webhooks

permitem código submetido pelo usuário (Jinja2) para URL/headers/body, o que pode ser risco;
portanto, permissões para criar/modificar webhooks devem ser restritas a usuários confiáveis. 62

DEBUG em produção. O parâmetro DEBUG é apenas para desenvolvimento/troubleshooting; a

documentação alerta para nunca habilitar em produção por risco de exposição de dados e penalidade
de performance. 63

Desempenho e escalabilidade

O “Performance Handbook” é a referência central e recomenda:

• WSGI workers: 2 * CPUs + 1 ; limitar lifetime e definir timeout (sugestão: 120s); usar Unix
socket quando HTTP frontend e WSGI estão no mesmo host. 64
• Limites e paginação: ajustar MAX_PAGE_SIZE ; usar brief e fields ; empregar paginação
corretamente (default PAGINATE_COUNT 50; máximo limitado por MAX_PAGE_SIZE ). 30

• GraphQL: pedir apenas campos necessários, evitar queries complexas e usar filtros/paginação.
65

• Workers assíncronos: separar filas e dedicar worker para fila high quando necessário;
QUEUE_MAPPINGS permite mapear tipos de tarefa (webhook/report/script) para filas
específicas. 30

Automação e integração avançadas

Webhooks e automação orientada a eventos

Payload e customização. Webhooks suportam templating Jinja2 em URL/headers/body, com contexto

contendo event , timestamp , object_type ( app_label.model ), username , request_id ,
data (representação detalhada similar à REST API) e snapshots pré/pós-alteração. A documentação
também fornece exemplo de corpo JSON e descreve que, sem body template, a payload padrão inclui o
contexto completo. 66

Processamento assíncrono e observabilidade. Webhooks são enfileirados no Redis e processados

pelo rqworker ; a fila e falhas podem ser inspecionadas em “System > Background Tasks”, e falhas
podem ser re-enfileiradas manualmente. 67

Mudanças em versões recentes. Em v4.5, release notes indicam que webhooks não incluem mais a
chave model no payload (usar object_type ), e que /api/extras/object-types/ foi removido
em favor de /api/core/object-types/ . Isso é relevante para integrações que faziam parsing do
payload/metadata. 68

11
Custom scripts (Jobs) como motor de automação interna

Scripts são Python “fora do core” executáveis via UI, capazes de manipular dados, validar integridade e
até importar de fontes externas. Há aviso explícito: scripts têm acesso irrestrito ao banco e só devem
ser instalados/rodados de fontes confiáveis, com permissões bem controladas. 69

Recursos importantes para especialistas:

• Estrutura: herdar [Link] , implementar run(data, commit) ; suporte a

variáveis (ObjectVar etc.), logging (debug/info/success/warning/failure) e testes test_ . 40

• Agendamento: scheduling_enabled controla execução futura/recorrente; jobs têm status

(pending/scheduled/running/completed/failed/errored) e armazenam “data/log output”. 70

• Upload por API: /api/extras/scripts/upload/ via multipart/form-data , com

permissões específicas ( extras.add_scriptmodule , core.add_managedfile ). 69

Synchronized data (DataSource/DataFile) para “infra as code” de templates e

contextos

Alguns recursos (configuration templates, config context data, export templates) suportam
sincronização automática de dados a partir de fontes remotas (ex.: repositório git, bucket S3, diretório
local), materializando arquivos como “data files” no banco e impedindo modificação local (apenas
delete). Há permissão específica ( core.sync_datasource ) e campo sync_interval para
sincronização periódica (agendada via RQ worker). 71

Integração com Ansible (NetBox Ansible Collection)

A documentação do “NetBox Ansible Collection – Quick Start” descreve duas abordagens típicas:

• Inventário dinâmico via plugin [Link].nb_inventory , com agrupamento por

device_roles e sites e uso de ansible-inventory --graph/--list . 72

• Definição do estado pretendido (“intended state”) em NetBox usando módulos que criam/
atualizam/removem objetos (ex.: criar aggregate prefix). 73

A doc explicita requisitos: rodar uma das duas versões mais recentes do NetBox, usar token write-
enabled para módulos (ou read-only para plugins de lookup/inventory), e dependências (Python/Ansible
+ pynetbox). 74

Integração via SDKs (pyNetBox) e práticas de consumo

O guia do pyNetBox mostra como criar conexão, espelha a estrutura de apps/endpoints e exemplifica
.all() , .filter() , .get() e .create() . Também destaca que .all() / .filter()
retornam geradores (iteráveis consumíveis uma vez) e que objetos possuem atributos acessíveis e
serialização. 75

Em “advanced usage”, o pyNetBox oferece:

• Threading para buscar múltiplas páginas em paralelo (útil em grandes datasets), com
recomendação de não zerar MAX_PAGE_SIZE . 76
• Strict filters para validar filtros contra OpenAPI e evitar retornos inesperados (tabelas inteiras).
77

12
Plugins: instalação, ciclo de vida e limites

Instalação (Community). O processo padrão: instalar pacote Python dentro do venv do NetBox,
habilitar em PLUGINS , configurar em PLUGINS_CONFIG , rodar migrate , executar
collectstatic e reiniciar WSGI + RQ workers. 78

Desenvolvimento e limites. O guia de desenvolvimento reforça: usar apenas APIs suportadas/

documentadas pelo NetBox e Django; estruturas internas podem mudar sem aviso. Plugins podem
estender REST/GraphQL e adicionar middleware, mas é preciso projetar com compatibilidade/upgrade
em mente. 79

Terraform e outras integrações

O site menciona Terraform em conteúdos de blog e referência comunitária a “terraform-provider-

netbox”, mas não apresenta, no domínio [Link], uma documentação técnica consolidada
de provider, schemas e recursos Terraform (ex.: blocos provider , resource , data e atributos
suportados). Portanto, detalhes de implementação de Terraform ficam não especificados nesta
pesquisa restrita ao domínio. 80

Troubleshooting comum, logs, checklist diário e snippets úteis

Problemas comuns e abordagem

Não conecta no HTTP/HTTPS / erro 502 (bad gateway). O guia do servidor HTTP recomenda verificar:
nginx/Apache em execução e porta correta; firewall; e, para 502, conferir se gunicorn está ativo
( systemctl status netbox ), se reverse proxy aponta para a porta do gunicorn (default 8001) e se
SELinux não bloqueia a conexão (ex.: setsebool -P httpd_can_network_connect 1 ). 81

Webhooks não disparam/sem saída. A doc de webhooks recomenda usar o webhook_receiver

local para inspecionar headers/body e, se nada aparece, checar se rqworker está rodando e se
eventos estão entrando na fila. Também orienta onde ver resultados/falhas (Background Tasks) e como
re-enfileirar. 82

API responde 403 “Authentication credentials were not provided.” A doc explica que token pode ser
exigido exceto em views isentas por EXEMPT_VIEW_PERMISSIONS ; também descreve formato correto
do header para tokens v1/v2 e sugere uso de endpoint de autenticação-check (v4.5) para testar
credenciais. 83

Filtros errados retornam “tudo” e travam cliente. A doc do pyNetBox alerta que NetBox não valida
filtros e pode retornar tabela inteira silenciosamente; para mitigar, usar validação via OpenAPI
( strict_filters ) e práticas de performance ( brief , fields , paginação). 84

Degradação por retenção indefinida. Configurações de retenção ( CHANGELOG_RETENTION ,

JOB_RETENTION ) têm advertência: se definidas como 0 (indefinido), recomenda-se limpeza periódica
para evitar crescimento do banco além da capacidade. 85

Logs e observabilidade

Logging (console/arquivo). Por padrão, mensagens INFO+ vão ao console; com DEBUG=False e e-
mail configurado, ERROR/CRITICAL podem ser enviados aos administradores ( ADMINS ). A

13
documentação mostra como configurar LOGGING para arquivo (ex.: /var/log/[Link] ) e lista
namespaces de loggers (ex.: [Link].* , netbox.event_rules , [Link].* ,
[Link].* ). 86

Error reporting (Sentry). Existe integração nativa com Sentry habilitável via SENTRY_ENABLED e
SENTRY_DSN . Em instalação do NetBox, o uso do sentry-sdk é descrito como opcional (mudança
em relação a versões anteriores). 87

Métricas Prometheus. O NetBox expõe métricas em /metrics quando METRICS_ENABLED está

ativo; não vem habilitado por padrão. 88

Checklist de administração diária (operacional)

Abaixo um checklist orientado a sinais (saúde, fila, auditoria, capacidade), alinhado aos pontos cobertos
explicitamente na documentação.

Frequência O que checar Por quê / referência

502 e falhas de tarefas normalmente decorrem de

Serviços netbox (WSGI) e WSGI/worker inativos; docs indicam checagem via
Diário
netbox-rq ativos systemctl status e reinício após upgrades/
plugins. 89

Webhooks e jobs são assíncronos; falhas são

Background Tasks (jobs,
Diário visíveis e re-enfileiráveis em Background Tasks.
webhooks falhos)
82

Changelog (mudanças Change logging é mecanismo de auditoria; X-

Diário recentes) e correlação por Request-ID correlaciona alterações e API expõe
request_id /api/extras/object-changes/ . 39

Backups testados (dump/ Documentação mostra pg_dump / psql ;

Semanal
restore) + mídia/scripts upgrades lembram de mídia e scripts/reports. 90

Revisar permissões e OBP é central e usa JSON constraints; erros aqui

Semanal
constraints críticas viram incidentes de acesso/segurança. 91

Revisar tuning:
Performance handbook orienta parâmetros e
Mensal MAX_PAGE_SIZE , workers,
separação de workers/filas. 30
timeouts, fila high

A cada Revisar release notes + Upgrade guide exige leitura de release notes e
release caminho de upgrade ressalta restrições em major versions. 92

Comandos e snippets úteis (curados da documentação)

PostgreSQL (criação e validação):

psql -V
sudo -u postgres psql
# dentro do psql:
# CREATE DATABASE netbox;

14
 # CREATE USER netbox WITH PASSWORD '<SENHA_FORTE>';
# ALTER DATABASE netbox OWNER TO netbox;

93

Backup/restore do banco:

pg_dump --username netbox --password --host localhost netbox > [Link]

psql -c 'drop database netbox'
psql -c 'create database netbox'
psql netbox < [Link]

94

Redis (health check simples):

redis-cli ping
# esperado: PONG

95

Upgrade (Community):

sudo ./[Link]
sudo systemctl restart netbox netbox-rq

96

Worker dedicado para fila high (exemplo):

./[Link] rqworker high

64

Webhooks: receptor local para depuração:

python netbox/[Link] webhook_receiver

# ouvindo em [Link]

97

15
Limitações conhecidas e versões

Limitações funcionais (core)

A própria documentação explicita limites de escopo (não faz monitoramento, DNS, RADIUS, config
management, facilities management), reforçando o papel do NetBox como fonte de verdade e
plataforma de integração. 1

A API GraphQL é explicitamente read-only (complementar à REST) e pode ser desabilitada via
GRAPHQL_ENABLED . 98

Limitações e riscos de extensibilidade

O guia de plugins alerta que o “plugins API” é limitado ao que está documentado; uso de componentes
internos fora da documentação pode quebrar em releases futuras sem aviso. 28

Mudanças relevantes recentes (impacto em integrações)

• v4.5 introduz tokens v2 e reforça migração, com depreciação futura de v1; adiciona endpoint /
api/authentication-check/ . 99

• v4.5 também altera payload de webhooks (removendo model e preferindo object_type ) e

modifica endpoints de object types. 68
• Release notes registram casos de “não usar” patches específicos quando há regressões
importantes (ex.: nota de que v4.1.9 quebra change logging e recomenda usar v4.1.10). 100

Roadmap e cadência de releases (o que o site especifica)

A página de release notes define categorias (major/minor/patch) e informa cadência: minors em abril,
agosto e dezembro; patches “as needed”, tipicamente a cada 1–2 semanas. Isso funciona como
“roadmap temporal” oficial de distribuição. 101

Quanto a roadmap de features específico (lista futura priorizada), não há no domínio [Link]
uma página única de roadmap detalhado para NetBox Community; o que há são releases notes e
posts de anúncios/betas (ex.: beta 4.5) que indicam direção e destaques, mas sem garantir backlog
completo. Nesse sentido, “roadmap” formal e granular fica não especificado sob a restrição de
domínio, e deve ser inferido apenas via release notes/anúncios. 102

Plano de estudo e treinamento prático

O objetivo aqui é construir, em etapas, a proficiência de “usuário avançado” → “operador/
administrador” → “arquiteto de automação e extensões”. As estimativas abaixo assumem dedicação de
8–12h/semana; com dedicação integral, os marcos podem ser comprimidos.

16
Milestone de fundamentos e modelagem

Duração estimada: 1–2 semanas

Entregáveis:

• Instância funcional (Community auto-hospedado ou Cloud/Enterprise, conforme necessidade). A

doc de instalação Community é testada em Ubuntu 24.04 e lista componentes e versões
suportadas. 103
• Modelagem inicial DCIM: Regions/SiteGroups/Sites/Locations/Racks/DeviceTypes/Devices e
cabeamento básico. 104
• Convenções internas: naming, slugs, status, tags e tenants (quando aplicável). 105

Milestone de IPAM e serviços

Duração estimada: 1–2 semanas

Entregáveis:

• VRFs, Prefixes, VLANs e IP ranges (incluindo decisões sobre mark_populated quando fizer
sentido). 106
• Pipeline de alocação “next available” via API para IPs (e, quando aplicável, prefixes/ASNs), com
evidência de uso em automação. 107

Milestone de circuitos, VPN e wireless

Duração estimada: 1–2 semanas

Entregáveis:

• Inventário de provedores/circuitos e terminações A/Z conectadas a sites/interfaces;

padronização de atributos. 108
• Modelagem de túneis (incluindo políticas IKE/IPSec conforme padrões internos) e overlays
L2VPN com amarração a VLANs/interfaces. 109
• Wireless LANs e links PTP com estrutura de grupos e vínculo opcional a VLAN. 110

Milestone de API REST e governança de acesso

Duração estimada: 1–2 semanas

Entregáveis:

• Catálogo de endpoints críticos por domínio (DCIM/IPAM/Circuits/VPN/Wireless/Virtualization) e

coleções de exemplos (curl + pyNetBox). 111
• Estratégia de tokens v2 (IP allowlist, read-only vs write, rotação) e uso de endpoint de validação
de credenciais. 112
• Modelo de permissões baseado em objetos (constraints) para times/ambientes/tenants,
incluindo “custom actions” (run scripts, sync datasource etc.). 113

Milestone de automação avançada

Duração estimada: 2–3 semanas

Entregáveis:

• Webhooks + event rules com payload customizado (Jinja2) e receptor de teste

( webhook_receiver ) para validação. 114

17
 • Biblioteca de custom scripts (jobs) com logging, modo commit controlado, agendamento e
versionamento operacional. 115
• Synchronized data (DataSource/DataFile) para templates/contextos/export templates e
sincronização periódica ( sync_interval ). 116
• Integração com Ansible: inventário dinâmico e playbooks que escrevem estado pretendido em
NetBox. 73

Milestone de operação, desempenho e confiabilidade

Duração estimada: 1–2 semanas

Entregáveis:

• Playbook de hardening: CORS/CSRF, password policy, restrição de criação de webhooks/scripts,

DEBUG sempre off em produção, e logging para arquivo/Sentry quando desejado. 117
• Tuning de performance: workers WSGI, timeouts, MAX_PAGE_SIZE , brief/fields, separação de
filas e workers dedicados. 30
• Plano de backup/restore testado (banco + mídia/scripts), e política de retenção (changelog/jobs)
com rotinas de limpeza. 118

Milestone opcional: NetBox Enterprise, Discovery e Diode

Duração estimada: 1–2 semanas (dependendo do ambiente)

Entregáveis:

• Entendimento operacional do Enterprise (Kubernetes embutido, console admin, componentes

embutidos vs externos, requisitos de storage em multi-node). 119
• Para cenários com ingestão: compreender Diode como serviço de ingestão/reconciliação e
fluxos de changesets (quando disponível no seu tier). 120

Tempo total estimado para “nível especialista operacional + automação”: 8–12 semanas (com
prática real, integração com ferramentas internas e disciplina de governança). A documentação enfatiza
que o valor do NetBox emerge quando ele é o núcleo da automação e da integridade do estado
pretendido; portanto, o “capstone” recomendado é implementar 1–2 fluxos completos (ex.: evento →
webhook → automação externa → retorno de inventário/estado → auditoria via change log), com
observabilidade e controles de acesso. 121

1 2 8 11 12 105 121 [Link]

[Link]

3 29 31 32 33 36 41 42 43 83 111 112 [Link]

[Link]

4 61 91 113 [Link]
[Link]

5 35 75 [Link]
[Link]

6 101 Release Notes | NetBox Documentation

[Link]

7 26 62 66 67 82 97 114 [Link]
[Link]

18
 9 119 120 [Link]
[Link]

10 [Link]
[Link]

13 45 46 47 48 49 50 [Link]
[Link]

14 51 104 Facilities | NetBox Documentation

[Link]

15 [Link]
[Link]

16 [Link]
[Link]

17 Power Tracking | NetBox Documentation

[Link]

18 106 [Link]
[Link]

19 107 [Link]
[Link]

20 [Link]
[Link]

21 Virtualization | NetBox Documentation

[Link]

22 108 Circuits | NetBox Documentation

[Link]

23 109 Tunnels | NetBox Documentation

[Link]

24 110 Wireless | NetBox Documentation

[Link]

25 Configuration Rendering | NetBox Documentation

[Link]

27 39 Change Logging | NetBox Documentation

[Link]

28 79 [Link]
[Link]

30 55 64 65 [Link]
[Link]

34 [Link]
[Link]

37 38 [Link]
[Link]

40 69 70 115 [Link]
[Link]

19
44 76 77 84 [Link]
[Link]

52 103 [Link]
[Link]

53 93 [Link]
[Link]

54 95 [Link]
[Link]

56 90 94 118 Replicating NetBox | NetBox Documentation

[Link]

57 59 92 96 [Link]
[Link]

58 85 [Link]
[Link]

60 117 [Link]
[Link]

63 [Link]
[Link]

68 99 NetBox v4.5
[Link]

71 116 [Link]
[Link]

72 73 74 [Link]
[Link]

78 [Link]
[Link]

80 September Community Call

[Link]

81 89 [Link]
[Link]

86 [Link]
[Link]

87 Error Reporting - Sentry

[Link]

88 Prometheus Metrics | NetBox Documentation

[Link]

98 [Link]
[Link]

100 NetBox v4.1 | NetBox Documentation

[Link]

102 Announcing the NetBox 4.5 Beta

[Link]

20