NetBox

NetBox provides specialized base form classes for plugin development to ensure consistency with the core UI and data models. Depending on your use case, you should choose one of the following:

• NetBoxModelForm: Used for creating or editing individual objects. Supports tags and custom fields.
• NetBoxModelImportForm: Used for bulk importing objects from CSV, JSON, or YAML data.
• NetBoxModelBulkEditForm: Used for editing multiple objects simultaneously. Fields are generally required=False.
• NetBoxModelFilterSetForm: Used to render filtering forms within list views.

Additionally, NetBox provides model-specific subclasses for these classes based on the model type (PrimaryModel, OrganizationalModel, or NestedGroupModel).

NetBox provides a global search engine that indexes relevant fields across the data model. Results are returned based on field precedence, and the index is updated in real-time when objects are created or modified.

Key search behaviors:

• Lookup Types: Users can specify lookup types such as exact match or partial match.
• Partial Matches: When a partial match occurs, the matching portion of the field value is highlighted in the results to show relevance.
• Custom Fields: Administrators can include custom fields in search results by configuring a search weight for them.
• Plugins: NetBox plugins can register custom models to appear in global search results.

Important Limitation: NetBox does not index static choice fields. This includes custom fields of type Selection or Multiple selection.

NetBox Event Rules allow you to automatically trigger specific actions in response to internal system events. When an event occurs that matches your rule's constraints, NetBox can automatically:

• Execute a Custom Script: Run predefined Python scripts.
• Send a Webhook: Dispatch data to external systems via HTTP.
• Generate User Notifications: Alert users within the NetBox UI.

To create a functional rule, you must associate it with at least one NetBox object type (e.g., Device, IP Address) and at least one event type (e.g., create, update, or delete).

NetBox provides a read-only GraphQL API powered by Strawberry Django to complement the REST API. All queries are sent to the /graphql endpoint.

For every object type, NetBox provides two query fields:

• $OBJECT: Returns a single object. Requires a unique ID, e.g., device(id: 123).
• $OBJECT_list: Returns a list of objects, which can be filtered using the filters argument.

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
http://netbox/graphql/ \
--data '{"query": "query {circuit_list(filters:{status: STATUS_ACTIVE}) {cid provider {name}}}"}'

Most static resources for the NetBox UI are located in netbox/project-static/. The directory structure is as follows:

NetBox is built on the Django framework and provides several mechanisms to extend its functionality and tailor the data model to specific organizational needs:

• Data Model Customization: Use Custom fields to add metadata to existing objects.
• Logic & Validation: Implement Custom model validation and Event rules to enforce data integrity and trigger actions.
• Extending Functionality: Develop Plugins to add new features or Custom scripts (written in Python) to automate tasks.
• Data Integration: Use the REST & GraphQL APIs to integrate NetBox with other tools or automation workflows.
• Data Export: Use Export templates to define how data is extracted from the system.

A NetBox plugin is a self-contained Django app installed alongside NetBox to extend its functionality. Plugins can be enabled and configured independently within a single NetBox instance.

Common use cases include:

• Creating Django models to store custom data.
• Providing custom web UI pages (views).
• Injecting template content and navigation links.
• Extending REST and GraphQL APIs.
• Loading additional Django apps.
• Adding custom request/response middleware.

Warning: Only use officially supported components and the underlying Django framework. Any part of the NetBox codebase not documented in the official plugin API is considered internal and subject to change without notice.

A Module Type represents a specific make and model of hardware component that can be installed into a device's module bay. It is used to model field-replaceable components like line cards in a chassis-based switch or router.

Each Module Type can act as a template for several component types, including:

• Interfaces
• Console ports
• Console server ports
• Power ports
• Power Outlets
• Front pass-through ports
• Rear pass-through ports
• Module bays

Note: You cannot add device bays to modules.

Power Outlets represent the physical outlets on a Power Distribution Unit (PDU) or other power-supplying devices. They are used to model how power is distributed to dependent devices.

Key capabilities include:

• Mapping outlets to specific Power Ports to model power redistribution (e.g., a PDU outlet drawing from a specific upstream port).
• Associating outlets with a Feed Leg to model three-phase power distribution (e.g., assigning outlets to Leg A, B, or C).
• Using the Mark Connected flag to simulate a cable connection for the outlet.

Automation Tip: Power outlets are automatically instantiated from Power Outlet Templates assigned to a Device Type whenever a new device is created.

NetBox provides two ways to model logical groupings within physical hardware:

1. Virtual Chassis: Used to model multiple physical devices that share a single management plane (e.g., stackable switches). One device acts as the chassis master, and the other devices are members. All components of the member devices are visible on the master device.
2. Virtual Device Contexts (VDC): Used to model logical partitions within a single device. Each VDC operates autonomously but shares resources. Interfaces can be assigned to one or more VDCs.