From c582d7459f2bd5db72ba407b360bf381694b1767 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 10:06:26 -0400 Subject: [PATCH 01/28] Rearrange introductory content --- docs/index.md | 81 ++++++++++++++++++-------------------------- docs/introduction.md | 79 ++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 +- 3 files changed, 113 insertions(+), 49 deletions(-) create mode 100644 docs/introduction.md diff --git a/docs/index.md b/docs/index.md index 81c899387..a6bbcecff 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,63 +1,48 @@ ![NetBox](netbox_logo.svg "NetBox logo"){style="height: 100px; margin-bottom: 3em"} -# What is NetBox? +# The Premiere Network Source of Truth -NetBox is an infrastructure resource modeling (IRM) application designed to empower network automation. Initially conceived by the network engineering team at [DigitalOcean](https://www.digitalocean.com/), NetBox was developed specifically to address the needs of network and infrastructure engineers. NetBox is made available as open source under the Apache 2 license. It encompasses the following aspects of network management: +NetBox is the leading solution for modeling modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. -* **IP address management (IPAM)** - IP networks and addresses, VRFs, and VLANs -* **Equipment racks** - Organized by group and site -* **Devices** - Types of devices and where they are installed -* **Connections** - Network, console, and power connections among devices -* **Virtualization** - Virtual machines and clusters -* **Data circuits** - Long-haul communications circuits and providers +## Built for Networks -## What NetBox Is Not +Unlike general-purpose CMDBs, NetBox has curated a data model which caters specifically to the needs of network engineers and operators. It delivers a wide assortment of object types carefully crafted to best serve the needs of network engineers and operators. These cover all facets of network design, from IP address managements to cabling to overlays and more: -While NetBox strives to cover many areas of network management, the scope of its feature set is necessarily limited. This ensures that development focuses on core functionality and that scope creep is reasonably contained. To that end, it might help to provide some examples of functionality that NetBox **does not** provide: +* Hierarchical regions, site groups, sites, and locations +* Racks, devices, and device components +* Cables and wireless connections +* Power distribution +* Data circuits and providers +* Virtual machines and clusters +* IP prefixes, ranges, and addresses +* VRFs and route targets +* FHRP groups (VRRP, HSRP, etc.) +* AS numbers +* VLANs and scoped VLAN groups +* L2VPN overlays +* Organizational tenants and contacts -* Network monitoring -* DNS server -* RADIUS server -* Configuration management -* Facilities management +## Customizable & Extensible -That said, NetBox _can_ be used to great effect in populating external tools with the data they need to perform these functions. +In addition to its expansive and robust data model, NetBox offers myriad mechanisms through it can be customized and extended. -## Design Philosophy +* Custom fields +* Custom model validation +* Export templates +* Webhooks +* Plugins +* REST & GraphQL APIs -NetBox was designed with the following tenets foremost in mind. +## Always Open -### Replicate the Real World - -Careful consideration has been given to the data model to ensure that it can accurately reflect a real-world network. For instance, IP addresses are assigned not to devices, but to specific interfaces attached to a device, and an interface may have multiple IP addresses assigned to it. - -### Serve as a "Source of Truth" - -NetBox intends to represent the _desired_ state of a network versus its _operational_ state. As such, automated import of live network state is strongly discouraged. All data created in NetBox should first be vetted by a human to ensure its integrity. NetBox can then be used to populate monitoring and provisioning systems with a high degree of confidence. - -### Keep it Simple - -When given a choice between a relatively simple [80% solution](https://en.wikipedia.org/wiki/Pareto_principle) and a much more complex complete solution, the former will typically be favored. This ensures a lean codebase with a low learning curve. - -## Application Stack - -NetBox is built on the [Django](https://djangoproject.com/) Python framework and utilizes a [PostgreSQL](https://www.postgresql.org/) database. It runs as a WSGI service behind your choice of HTTP server. - -| Function | Component | -|--------------------|-------------------| -| HTTP service | nginx or Apache | -| WSGI service | gunicorn or uWSGI | -| Application | Django/Python | -| Database | PostgreSQL 10+ | -| Task queuing | Redis/django-rq | -| Live device access | NAPALM (optional) | - -## Supported Python Versions - -NetBox supports Python 3.8, 3.9, and 3.10 environments. +Because NetBox is an open source application licensed under [Apache 2](https://www.apache.org/licenses/LICENSE-2.0.html), its entire code base is completely accessible to the end user, and there's never a risk of vendor lock-out. Additionally, NetBox development is an entirely public, community-driven process to which everyone can provide input. ## Getting Started -Minor NetBox releases (e.g. v3.1) are published three times a year; in April, August, and December. These typically introduce major new features and may contain breaking API changes. Patch releases are published roughly every one to two weeks to resolve bugs and fulfill minor feature requests. These are backward-compatible with previous releases unless otherwise noted. The NetBox maintainers strongly recommend running the latest stable release whenever possible. +* Public Demo +* Installation Guide +* Docker install +* NetBox Cloud -Please see the [official installation guide](installation/index.md) for detailed instructions on obtaining and installing NetBox. +!!! tip "NetBox Development" + Interested in contributing to NetBox? Check out our [GitHub repository](https://github.com/netbox-community/netbox) to get started! diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 000000000..cffcb37dd --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,79 @@ +# Introduction to NetBox + +## Origin Story + +NetBox was originally developed by its lead maintainer, [Jeremy Stretch](https://github.com/jeremystretch), while he was working as a network engineer at [DigitalOcean](https://www.digitalocean.com/) in 2015 as part of an effort to automate their network provisioning. Recognizing the new tool's potential, DigitalOcean agreed to release it as an open source project in June 2016. + +Since then, thousands of organizations around the world have embraced NetBox as their central network source of truth to empower both network operators and automation. + +## Key Features + +NetBox was built specifically to serve the needs of network engineers and operators. Below is a very brief overview of the core features it provides. + +* IP address management (IPAM) with full IPv4/IPv6 parity +* Automatic provisioning of next available prefix/IP +* VRFs with import & export route targets +* VLANs with variably-scoped groups +* AS number (ASN) management +* Rack elevations with SVG rendering +* Device modeling using pre-defined types +* Network, power, and console cabling with SVG traces +* Power distribution modeling +* Data circuit and provider tracking +* Wireless LAN and point-to-point links +* L2 VPN overlays +* FHRP groups (VRRP, HSRP, etc.) +* Application service bindings +* Virtual machines & clusters +* Flexible hierarchy for sites and locations +* Tenant ownership assignment +* Device & VM configuration contexts for advanced configuration rendering +* Custom fields for data model extension +* Support for custom validation rules +* Custom reports & scripts executable directly within the UI +* Extensive plugin framework for adding custom functionality +* Single sign-on (SSO) authentication +* Robust object-based permissions +* Detailed, automatic change logging +* NAPALM integration + +## What NetBox Is Not + +While NetBox strives to cover many areas of network management, the scope of its feature set is necessarily limited. This ensures that development focuses on core functionality and that scope creep is reasonably contained. To that end, it might help to provide some examples of functionality that NetBox **does not** provide: + +* Network monitoring +* DNS server +* RADIUS server +* Configuration management +* Facilities management + +That said, NetBox _can_ be used to great effect in populating external tools with the data they need to perform these functions. + +## Design Philosophy + +NetBox was designed with the following tenets foremost in mind. + +### Replicate the Real World + +Careful consideration has been given to the data model to ensure that it can accurately reflect a real-world network. For instance, IP addresses are assigned not to devices, but to specific interfaces attached to a device, and an interface may have multiple IP addresses assigned to it. + +### Serve as a "Source of Truth" + +NetBox intends to represent the _desired_ state of a network versus its _operational_ state. As such, automated import of live network state is strongly discouraged. All data created in NetBox should first be vetted by a human to ensure its integrity. NetBox can then be used to populate monitoring and provisioning systems with a high degree of confidence. + +### Keep it Simple + +When given a choice between a relatively simple [80% solution](https://en.wikipedia.org/wiki/Pareto_principle) and a much more complex complete solution, the former will typically be favored. This ensures a lean codebase with a low learning curve. + +## Application Stack + +NetBox is built on the [Django](https://djangoproject.com/) Python framework and utilizes a [PostgreSQL](https://www.postgresql.org/) database. It runs as a WSGI service behind your choice of HTTP server. + +| Function | Component | +|--------------------|-------------------| +| HTTP service | nginx or Apache | +| WSGI service | gunicorn or uWSGI | +| Application | Django/Python | +| Database | PostgreSQL 10+ | +| Task queuing | Redis/django-rq | +| Live device access | NAPALM (optional) | diff --git a/mkdocs.yml b/mkdocs.yml index 34c65ed01..992859d66 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,7 +57,7 @@ markdown_extensions: - pymdownx.tabbed: alternate_style: true nav: - - Introduction: 'index.md' + - Introduction: 'introduction.md' - Installation: - Installing NetBox: 'installation/index.md' - 1. PostgreSQL: 'installation/1-postgresql.md' From 18acac18e0301ad0e3355f9742177062aad403c3 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 10:30:47 -0400 Subject: [PATCH 02/28] Move data model definitions to separate hierarchy --- docs/core-functionality/circuits.md | 10 -- docs/core-functionality/contacts.md | 5 - docs/core-functionality/device-types.md | 41 --------- docs/core-functionality/devices.md | 40 -------- docs/core-functionality/ipam.md | 33 ------- docs/core-functionality/modules.md | 4 - docs/core-functionality/power.md | 8 -- docs/core-functionality/services.md | 4 - docs/core-functionality/sites-and-racks.md | 12 --- docs/core-functionality/tenancy.md | 4 - docs/core-functionality/virtualization.md | 10 -- docs/core-functionality/vlans.md | 4 - docs/core-functionality/wireless.md | 8 -- docs/installation/migrating-to-systemd.md | 55 ----------- mkdocs.yml | 101 +++++++++++++++++---- 15 files changed, 85 insertions(+), 254 deletions(-) delete mode 100644 docs/core-functionality/circuits.md delete mode 100644 docs/core-functionality/contacts.md delete mode 100644 docs/core-functionality/device-types.md delete mode 100644 docs/core-functionality/devices.md delete mode 100644 docs/core-functionality/ipam.md delete mode 100644 docs/core-functionality/modules.md delete mode 100644 docs/core-functionality/power.md delete mode 100644 docs/core-functionality/services.md delete mode 100644 docs/core-functionality/sites-and-racks.md delete mode 100644 docs/core-functionality/tenancy.md delete mode 100644 docs/core-functionality/virtualization.md delete mode 100644 docs/core-functionality/vlans.md delete mode 100644 docs/core-functionality/wireless.md delete mode 100644 docs/installation/migrating-to-systemd.md diff --git a/docs/core-functionality/circuits.md b/docs/core-functionality/circuits.md deleted file mode 100644 index b1b02e300..000000000 --- a/docs/core-functionality/circuits.md +++ /dev/null @@ -1,10 +0,0 @@ -# Circuits - -{!models/circuits/provider.md!} -{!models/circuits/providernetwork.md!} - ---- - -{!models/circuits/circuit.md!} -{!models/circuits/circuittype.md!} -{!models/circuits/circuittermination.md!} diff --git a/docs/core-functionality/contacts.md b/docs/core-functionality/contacts.md deleted file mode 100644 index 76a005fc0..000000000 --- a/docs/core-functionality/contacts.md +++ /dev/null @@ -1,5 +0,0 @@ -# Contacts - -{!models/tenancy/contact.md!} -{!models/tenancy/contactgroup.md!} -{!models/tenancy/contactrole.md!} diff --git a/docs/core-functionality/device-types.md b/docs/core-functionality/device-types.md deleted file mode 100644 index ec5cbacdb..000000000 --- a/docs/core-functionality/device-types.md +++ /dev/null @@ -1,41 +0,0 @@ -# Device Types - -{!models/dcim/devicetype.md!} -{!models/dcim/manufacturer.md!} - ---- - -## Device Component Templates - -Each device type is assigned a number of component templates which define the physical components within a device. These are: - -* Console ports -* Console server ports -* Power ports -* Power outlets -* Network interfaces -* Front ports -* Rear ports -* Device bays (which house child devices) - -Whenever a new device is created, its components are automatically created per the templates assigned to its device type. For example, a Juniper EX4300-48T device type might have the following component templates defined: - -* One template for a console port ("Console") -* Two templates for power ports ("PSU0" and "PSU1") -* 48 templates for 1GE interfaces ("ge-0/0/0" through "ge-0/0/47") -* Four templates for 10GE interfaces ("xe-0/2/0" through "xe-0/2/3") - -Once component templates have been created, every new device that you create as an instance of this type will automatically be assigned each of the components listed above. - -!!! note - Assignment of components from templates occurs only at the time of device creation. If you modify the templates of a device type, it will not affect devices which have already been created. However, you always have the option of adding, modifying, or deleting components on existing devices. - -{!models/dcim/consoleporttemplate.md!} -{!models/dcim/consoleserverporttemplate.md!} -{!models/dcim/powerporttemplate.md!} -{!models/dcim/poweroutlettemplate.md!} -{!models/dcim/interfacetemplate.md!} -{!models/dcim/frontporttemplate.md!} -{!models/dcim/rearporttemplate.md!} -{!models/dcim/modulebaytemplate.md!} -{!models/dcim/devicebaytemplate.md!} diff --git a/docs/core-functionality/devices.md b/docs/core-functionality/devices.md deleted file mode 100644 index 35c978210..000000000 --- a/docs/core-functionality/devices.md +++ /dev/null @@ -1,40 +0,0 @@ -# Devices and Cabling - -{!models/dcim/device.md!} -{!models/dcim/devicerole.md!} -{!models/dcim/platform.md!} - ---- - -## Device Components - -Device components represent discrete objects within a device which are used to terminate cables, house child devices, or track resources. - -{!models/dcim/consoleport.md!} -{!models/dcim/consoleserverport.md!} -{!models/dcim/powerport.md!} -{!models/dcim/poweroutlet.md!} -{!models/dcim/interface.md!} -{!models/dcim/frontport.md!} -{!models/dcim/rearport.md!} -{!models/dcim/modulebay.md!} -{!models/dcim/devicebay.md!} -{!models/dcim/inventoryitem.md!} - ---- - -{!models/dcim/virtualchassis.md!} - ---- - -{!models/dcim/cable.md!} - -In the example below, three individual cables comprise a path between devices A and D: - -![Cable path](../media/models/dcim_cable_trace.png) - -Traced from Interface 1 on Device A, NetBox will show the following path: - -* Cable 1: Interface 1 to Front Port 1 -* Cable 2: Rear Port 1 to Rear Port 2 -* Cable 3: Front Port 2 to Interface 2 diff --git a/docs/core-functionality/ipam.md b/docs/core-functionality/ipam.md deleted file mode 100644 index c86819380..000000000 --- a/docs/core-functionality/ipam.md +++ /dev/null @@ -1,33 +0,0 @@ -# IP Address Management - -{!models/ipam/aggregate.md!} -{!models/ipam/rir.md!} - ---- - -{!models/ipam/prefix.md!} -{!models/ipam/role.md!} - ---- - -{!models/ipam/iprange.md!} -{!models/ipam/ipaddress.md!} - ---- - -{!models/ipam/vrf.md!} -{!models/ipam/routetarget.md!} - ---- - -{!models/ipam/fhrpgroup.md!} -{!models/ipam/fhrpgroupassignment.md!} - ---- - -{!models/ipam/asn.md!} - ---- - -{!models/ipam/l2vpn.md!} -{!models/ipam/l2vpntermination.md!} diff --git a/docs/core-functionality/modules.md b/docs/core-functionality/modules.md deleted file mode 100644 index 4d32fe18c..000000000 --- a/docs/core-functionality/modules.md +++ /dev/null @@ -1,4 +0,0 @@ -# Modules - -{!models/dcim/moduletype.md!} -{!models/dcim/module.md!} diff --git a/docs/core-functionality/power.md b/docs/core-functionality/power.md deleted file mode 100644 index 4d7d5f0ab..000000000 --- a/docs/core-functionality/power.md +++ /dev/null @@ -1,8 +0,0 @@ -# Power Tracking - -{!models/dcim/powerpanel.md!} -{!models/dcim/powerfeed.md!} - -# Example Power Topology - -![Power distribution model](../media/power_distribution.png) diff --git a/docs/core-functionality/services.md b/docs/core-functionality/services.md deleted file mode 100644 index 316c7fe00..000000000 --- a/docs/core-functionality/services.md +++ /dev/null @@ -1,4 +0,0 @@ -# Service Mapping - -{!models/ipam/servicetemplate.md!} -{!models/ipam/service.md!} diff --git a/docs/core-functionality/sites-and-racks.md b/docs/core-functionality/sites-and-racks.md deleted file mode 100644 index c78f2120a..000000000 --- a/docs/core-functionality/sites-and-racks.md +++ /dev/null @@ -1,12 +0,0 @@ -# Sites and Racks - -{!models/dcim/region.md!} -{!models/dcim/sitegroup.md!} -{!models/dcim/site.md!} -{!models/dcim/location.md!} - ---- - -{!models/dcim/rack.md!} -{!models/dcim/rackrole.md!} -{!models/dcim/rackreservation.md!} diff --git a/docs/core-functionality/tenancy.md b/docs/core-functionality/tenancy.md deleted file mode 100644 index fbe1ea8b9..000000000 --- a/docs/core-functionality/tenancy.md +++ /dev/null @@ -1,4 +0,0 @@ -# Tenancy Assignment - -{!models/tenancy/tenant.md!} -{!models/tenancy/tenantgroup.md!} diff --git a/docs/core-functionality/virtualization.md b/docs/core-functionality/virtualization.md deleted file mode 100644 index 220030ab2..000000000 --- a/docs/core-functionality/virtualization.md +++ /dev/null @@ -1,10 +0,0 @@ -# Virtualization - -{!models/virtualization/cluster.md!} -{!models/virtualization/clustertype.md!} -{!models/virtualization/clustergroup.md!} - ---- - -{!models/virtualization/virtualmachine.md!} -{!models/virtualization/vminterface.md!} diff --git a/docs/core-functionality/vlans.md b/docs/core-functionality/vlans.md deleted file mode 100644 index d69128765..000000000 --- a/docs/core-functionality/vlans.md +++ /dev/null @@ -1,4 +0,0 @@ -# VLAN Management - -{!models/ipam/vlan.md!} -{!models/ipam/vlangroup.md!} diff --git a/docs/core-functionality/wireless.md b/docs/core-functionality/wireless.md deleted file mode 100644 index 57133f756..000000000 --- a/docs/core-functionality/wireless.md +++ /dev/null @@ -1,8 +0,0 @@ -# Wireless Networks - -{!models/wireless/wirelesslan.md!} -{!models/wireless/wirelesslangroup.md!} - ---- - -{!models/wireless/wirelesslink.md!} diff --git a/docs/installation/migrating-to-systemd.md b/docs/installation/migrating-to-systemd.md deleted file mode 100644 index a71b748fd..000000000 --- a/docs/installation/migrating-to-systemd.md +++ /dev/null @@ -1,55 +0,0 @@ -# Migrating to systemd - -This document contains instructions for migrating from a legacy NetBox deployment using [supervisor](http://supervisord.org/) to a systemd-based approach. - -## Ubuntu - -### Uninstall supervisord - -```no-highlight -# apt-get remove -y supervisor -``` - -### Configure systemd - -!!! note - These instructions assume the presence of a Python virtual environment at `/opt/netbox/venv`. If you have not created this environment, please refer to the [installation instructions](3-netbox.md#set-up-python-environment) for direction. - -We'll use systemd to control the daemonization of NetBox services. First, copy `contrib/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory: - -```no-highlight -# cp contrib/*.service /etc/systemd/system/ -``` - -!!! note - You may need to modify the user that the systemd service runs as. Please verify the user for httpd on your specific release and edit both files to match your httpd service under user and group. The username could be "nobody", "nginx", "apache", "www-data", or something else. - -Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time: - -```no-highlight -# systemctl daemon-reload -# systemctl start netbox netbox-rq -# systemctl enable netbox netbox-rq -``` - -You can use the command `systemctl status netbox` to verify that the WSGI service is running: - -``` -# systemctl status netbox.service -● netbox.service - NetBox WSGI Service - Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled) - Active: active (running) since Sat 2020-10-24 19:23:40 UTC; 25s ago - Docs: https://docs.netbox.dev/ - Main PID: 11993 (gunicorn) - Tasks: 6 (limit: 2362) - CGroup: /system.slice/netbox.service - ├─11993 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... - ├─12015 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... - ├─12016 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... -... -``` - -At this point, you should be able to connect to the HTTP service at the server name or IP address you provided. If you are unable to connect, check that the nginx service is running and properly configured. If you receive a 502 (bad gateway) error, this indicates that gunicorn is misconfigured or not running. Issue the command `journalctl -xe` to see why the services were unable to start. - -!!! info - Please keep in mind that the configurations provided here are bare minimums required to get NetBox up and running. You may want to make adjustments to better suit your production environment. diff --git a/mkdocs.yml b/mkdocs.yml index 992859d66..6471783e0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,7 +58,7 @@ markdown_extensions: alternate_style: true nav: - Introduction: 'introduction.md' - - Installation: + - Installation & Upgrade: - Installing NetBox: 'installation/index.md' - 1. PostgreSQL: 'installation/1-postgresql.md' - 2. Redis: 'installation/2-redis.md' @@ -67,7 +67,6 @@ nav: - 5. HTTP Server: 'installation/5-http-server.md' - 6. LDAP (Optional): 'installation/6-ldap.md' - Upgrading NetBox: 'installation/upgrading.md' - - Migrating to systemd: 'installation/migrating-to-systemd.md' - Configuration: - Configuring NetBox: 'configuration/index.md' - Required Settings: 'configuration/required-settings.md' @@ -75,20 +74,6 @@ nav: - Dynamic Settings: 'configuration/dynamic-settings.md' - Error Reporting: 'configuration/error-reporting.md' - Remote Authentication: 'configuration/remote-authentication.md' - - Core Functionality: - - IP Address Management: 'core-functionality/ipam.md' - - VLAN Management: 'core-functionality/vlans.md' - - Sites and Racks: 'core-functionality/sites-and-racks.md' - - Devices and Cabling: 'core-functionality/devices.md' - - Device Types: 'core-functionality/device-types.md' - - Modules: 'core-functionality/modules.md' - - Virtualization: 'core-functionality/virtualization.md' - - Service Mapping: 'core-functionality/services.md' - - Circuits: 'core-functionality/circuits.md' - - Wireless: 'core-functionality/wireless.md' - - Power Tracking: 'core-functionality/power.md' - - Tenancy: 'core-functionality/tenancy.md' - - Contacts: 'core-functionality/contacts.md' - Customization: - Custom Fields: 'customization/custom-fields.md' - Custom Validation: 'customization/custom-validation.md' @@ -135,6 +120,90 @@ nav: - Authentication: 'rest-api/authentication.md' - GraphQL API: - Overview: 'graphql-api/overview.md' + - Data Model: + - Circuits: + - Circuit: 'models/circuits/circuit.md' + - Circuit Termination: 'models/circuits/circuittermination.md' + - Circuit Type: 'models/circuits/circuittype.md' + - Provider: 'models/circuits/provider.md' + - Provider Network: 'models/circuits/providernetwork.md' + - DCIM: + - Cable: 'models/dcim/cable.md' + - CablePath: 'models/dcim/cablepath.md' + - CableTermination: 'models/dcim/cabletermination.md' + - ConsolePort: 'models/dcim/consoleport.md' + - ConsolePortTemplate: 'models/dcim/consoleporttemplate.md' + - ConsoleServerPort: 'models/dcim/consoleserverport.md' + - ConsoleServerPortTemplate: 'models/dcim/consoleserverporttemplate.md' + - Device: 'models/dcim/device.md' + - DeviceBay: 'models/dcim/devicebay.md' + - DeviceBayTemplate: 'models/dcim/devicebaytemplate.md' + - DeviceRole: 'models/dcim/devicerole.md' + - DeviceType: 'models/dcim/devicetype.md' + - FrontPort: 'models/dcim/frontport.md' + - FrontPortTemplate: 'models/dcim/frontporttemplate.md' + - Interface: 'models/dcim/interface.md' + - InterfaceTemplate: 'models/dcim/interfacetemplate.md' + - InventoryItem: 'models/dcim/inventoryitem.md' + - InventoryItemRole: 'models/dcim/inventoryitemrole.md' + - InventoryItemTemplate: 'models/dcim/inventoryitemtemplate.md' + - Location: 'models/dcim/location.md' + - Manufacturer: 'models/dcim/manufacturer.md' + - Module: 'models/dcim/module.md' + - ModuleBay: 'models/dcim/modulebay.md' + - ModuleBayTemplate: 'models/dcim/modulebaytemplate.md' + - ModuleType: 'models/dcim/moduletype.md' + - Platform: 'models/dcim/platform.md' + - PowerFeed: 'models/dcim/powerfeed.md' + - PowerOutlet: 'models/dcim/poweroutlet.md' + - PowerOutletTemplate: 'models/dcim/poweroutlettemplate.md' + - PowerPanel: 'models/dcim/powerpanel.md' + - PowerPort: 'models/dcim/powerport.md' + - PowerPortTemplate: 'models/dcim/powerporttemplate.md' + - Rack: 'models/dcim/rack.md' + - RackReservation: 'models/dcim/rackreservation.md' + - RackRole: 'models/dcim/rackrole.md' + - RearPort: 'models/dcim/rearport.md' + - RearPortTemplate: 'models/dcim/rearporttemplate.md' + - Region: 'models/dcim/region.md' + - Site: 'models/dcim/site.md' + - SiteGroup: 'models/dcim/sitegroup.md' + - VirtualChassis: 'models/dcim/virtualchassis.md' + - IPAM: + - ASN: 'models/ipam/asn.md' + - Aggregate: 'models/ipam/aggregate.md' + - FHRPGroup: 'models/ipam/fhrpgroup.md' + - FHRPGroupAssignment: 'models/ipam/fhrpgroupassignment.md' + - IPAddress: 'models/ipam/ipaddress.md' + - IPRange: 'models/ipam/iprange.md' + - L2VPN: 'models/ipam/l2vpn.md' + - L2VPNTermination: 'models/ipam/l2vpntermination.md' + - Prefix: 'models/ipam/prefix.md' + - RIR: 'models/ipam/rir.md' + - Role: 'models/ipam/role.md' + - RouteTarget: 'models/ipam/routetarget.md' + - Service: 'models/ipam/service.md' + - ServiceTemplate: 'models/ipam/servicetemplate.md' + - VLAN: 'models/ipam/vlan.md' + - VLANGroup: 'models/ipam/vlangroup.md' + - VRF: 'models/ipam/vrf.md' + - Tenancy: + - Contact: 'models/tenancy/contact.md' + - ContactAssignment: 'models/tenancy/contactassignment.md' + - ContactGroup: 'models/tenancy/contactgroup.md' + - ContactRole: 'models/tenancy/contactrole.md' + - Tenant: 'models/tenancy/tenant.md' + - TenantGroup: 'models/tenancy/tenantgroup.md' + - Virtualization: + - Cluster: 'models/virtualization/cluster.md' + - ClusterGroup: 'models/virtualization/clustergroup.md' + - ClusterType: 'models/virtualization/clustertype.md' + - VMInterface: 'models/virtualization/vminterface.md' + - VirtualMachine: 'models/virtualization/virtualmachine.md' + - Wireless: + - WirelessLAN: 'models/wireless/wirelesslan.md' + - WirelessLANGroup: 'models/wireless/wirelesslangroup.md' + - WirelessLink: 'models/wireless/wirelesslink.md' - Reference: - Conditions: 'reference/conditions.md' - Markdown: 'reference/markdown.md' From b1ce8bd222a7b39bcacbe1d66ce5ab69f11dfe8e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 13:45:59 -0400 Subject: [PATCH 03/28] Started "getting started" guide --- docs/getting-started/planning.md | 87 +++++++++++++++++++++++++ docs/getting-started/populating-data.md | 42 ++++++++++++ mkdocs.yml | 3 + 3 files changed, 132 insertions(+) create mode 100644 docs/getting-started/planning.md create mode 100644 docs/getting-started/populating-data.md diff --git a/docs/getting-started/planning.md b/docs/getting-started/planning.md new file mode 100644 index 000000000..00640ca44 --- /dev/null +++ b/docs/getting-started/planning.md @@ -0,0 +1,87 @@ +# Planning Your Move + +This guide outlines the steps necessary for planning a successful migration to NetBox. Although it is written under the context of a completely new installation, the general approach outlined here works just as well for adding new data to existing NetBox deployments. + +## Identify Current Sources of Truth + +Before beginning to use NetBox for your own data, it's crucial to first understand where your existing sources of truth reside. A "source of truth" is really just any repository of data that is authoritative for a given domain. For example, you may have a spreadsheet which tracks all IP prefixes in use on your network. So long as everyone involved agrees that this spreadsheet is _authoritative_ for the entire network, it is your source of truth for IP prefixes. + +Anything can be a source of truth, provided it meets two conditions: + +1. It is agreed upon by all relevant parties that this source of data is correct. +2. The domain to which it applies is well-defined. + + + +Dedicate some time to take stock of your own sources of truth for your infrastructure. Upon attempting to catalog these, you're very likely to encounter some challenges, such as: + +* **Multiple conflicting sources** for a given domain. For example, there may be multiple versions of a spreadsheet circulating, each of which asserts a conflicting set of data. +* **Sources with no domain defined.** You may encounter that different teams within your organization use different tools for the same purpose, with no normal definition of when either should be used. +* **Inaccessible data formatting.** Some tools are better suited for programmatic usage than others. For example, spreadsheets are generally very easy to parse and export, however free-form notes on wiki or similar application are much more difficult to consume. +* **There is no source of truth.** Sometimes you'll find that a source of truth simply doesn't exist for a domain. For example, when assigning IP addresses, operators may be just using any (presumed) available IP from a subnet without ever recording its usage. + +See if you can identify each domain of infrastructure data for your organization, and the source of truth for each. Once you have these compiled, you'll need to determine what belongs in NetBox. + +## Determine What to Move + +The general rule when determining what data to put into NetBox is this: If there's a model for it, it belongs in NetBox. For instance, NetBox has purpose-built models for racks, devices, cables, IP prefixes, VLANs, and so on. These are very straightforward to use. However, you'll inevitably reach the limits of NetBox's data model and question what additional data might make sense to record in NetBox. For example, you might wonder whether NetBox should function as the source of truth for infrastructure DNS records or DHCP scopes. + +NetBox provides two core mechanisms for extending its data model. The first is custom fields: Most models in NetBox support the addition of custom fields to hold additional data for which a built-in field does not exist. For example, you might wish to add an "inventory ID" field to the device model. The second mechanism is plugins. Users can create their own plugins to introduce entirely new models, views, and API endpoints in NetBox. This can be incredibly powerful, as it enables rapid development and tight integration with core models. + +That said, it doesn't always make sense to migrate a domain of data to NetBox. For example, many organizations opt to use only the IPAM components or only the DCIM components of NetBox, and integrate with other sources of truth for different domains. This is an entirely valid approach (so long as everyone involved agrees which tool is authoritative for each domain). Ultimately, you'll need to weigh the value of having non-native data models in NetBox against the effort required to define and maintain those models. + +Consider also that NetBox is under constant development. Although the current release might not support a particular type of object, there may be plans to add support for it in a future release. (And if there aren't, consider submitting a feature request citing your use case.) + +## Validate Existing Data + +The last step before migrating data to NetBox is the most crucial: **validation**. The GIGO (garbage in, garbage out) principle is in full effect: Your source of truth is only as good as the data it holds. While NetBox has very powerful data validation tools (including support for custom validation rules), ultimately the onus falls to a human operator to assert what is correct and what is not. For example, NetBox can validate the connection of a cable between two interfaces, but it cannot say whether the cable _should_ be there. + +Here are some tips to help ensure you're only importing valid data into NetBox: + +* Ensure you're starting with complete, well-formatted data. JSON or CSV is highly recommended for the best portability. +* Consider defining custom validation rules in NetBox prior to import. (For example, to enforce device naming schemes.) +* Use custom scripts to automatically populate patterned data. (For example, to automatically create a set of standard VLANs for each site.) + +There are several methods available to import data into NetBox, which we'll cover in the next section. + +## Order of Operations + +When starting with a completely empty database, it might not be immediately clear where to begin. Many models in NetBox rely on the advance creation of other types. For example, you cannot create a device type until after you have created its manufacturer. + +Below is the (rough) recommended order in which NetBox objects should be created or imported. While it is not required to follow this exact order, doing so will help ensure the smoothest workflow. + + + +1. Tenant groups +2. Tenants +3. Regions and/or site groups +4. Sites +5. Locations +6. Rack roles +7. Racks +8. Platforms +9. Manufacturers +10. Device types +11. Module types +12. Device roles +13. Devices +14. Providers +15. Provider networks +16. Circuit types +17. Circuits +18. Wireless LAN groups +19. Wireless LANs & links +20. Route targets +21. VRFs +22. RIRs +23. Aggregates +24. IP/VLAN roles +25. Prefixes +26. IP ranges & addresses +27. VLAN groups +28. VLANs +29. Services +30. Clusters +31. Virtual machines +32. VM interfaces +33. L2 VPNs diff --git a/docs/getting-started/populating-data.md b/docs/getting-started/populating-data.md new file mode 100644 index 000000000..e182a9d52 --- /dev/null +++ b/docs/getting-started/populating-data.md @@ -0,0 +1,42 @@ +# Populating Data + +This section covers the mechanisms which are available to populate data in NetBox. + +## Manual Object Creation + +The simplest and most direct way of populating data in NetBox is to use the object creation forms in the user interface. + +!!! warning "Not Ideal for Large Imports" + While convenient and readily accessible to even novice users, creating objects one at a time by manually completing these forms obviously does not scale well. For large imports, you're generally best served by using one of the other methods discussed in this section. + +To create a new object in NetBox, find the object type in the navigation menu and click the green "Add" button. + +!!! info "Missing Button?" + If you don't see an "add" button for certain object types, it's likely that your account does not have sufficient permission to create these types. Ask your NetBox administrator to grant the required permissions. + + Also note that some object types, such as device components, cannot be created directly from the navigation menu. These must be created within the context of a parent object (such as a parent device). + + + +## Bulk Import (CSV/YAML) + +NetBox supports the bulk import of new objects using CSV-formatted data. This method can be ideal for importing spreadsheet data, which is very easy to convert to CSV data. CSV data can be imported either as raw text using the form field, or by uploading a properly formatted CSV file. + +When viewing the CSV import form for an object type, you'll notice that the headers for the required columns have been pre-populated. Each form has a table beneath it titled "CSV Field Options," which lists _all_ supported columns for your reference. (Generally, these map to the fields you see in the corresponding creation form for individual objects.) + + + +Note that some models (namely device types and module types) do not support CSV import. Instead, they accept YAML-formatted data to facilitate the import of both the parent object as well as child components. + +## Scripting + +Sometimes you'll find that data you need to populate in NetBox can be easily reduced to a pattern. For example, suppose you have one hundred branch sites and each site gets five VLANs, numbered 101 through 105. While it's certainly possible to explicitly define each of these 500 VLANs in a CSV file for import, it may be quicker to draft a simple custom script to automatically create these VLANs according to the pattern. This ensures a high degree of confidence in the validity of the data, since it's impossible for a script to "miss" a VLAN here or there. + +!!! tip "Reconstruct Existing Data with Scripts" + Sometimes, you might want to write a script to populate objects even if you have the necessary data ready for import. This is because using a script eliminates the need to manually verify existing data prior to import. + +## REST API + +You can also use the REST API to facilitate the population of data in NetBox. The REST API offers full programmatic control over the creation of objects, subject to the same validation rules enforced by the UI forms. Additionally, the REST API supports the bulk creation of multiple objects using a single request. + +For more information about this option, see the [REST API documentation](../rest-api/overview.md). diff --git a/mkdocs.yml b/mkdocs.yml index 6471783e0..2203b8934 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,6 +67,9 @@ nav: - 5. HTTP Server: 'installation/5-http-server.md' - 6. LDAP (Optional): 'installation/6-ldap.md' - Upgrading NetBox: 'installation/upgrading.md' + - Getting Started: + - Planning: 'getting-started/planning.md' + - Populating Data: 'getting-started/populating-data.md' - Configuration: - Configuring NetBox: 'configuration/index.md' - Required Settings: 'configuration/required-settings.md' From a6c431f3ba236760ab753f92b8b7aec16c07c568 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 15:10:50 -0400 Subject: [PATCH 04/28] Reorganize configuration docs --- docs/additional-features/napalm.md | 2 +- docs/administration/housekeeping.md | 4 +- docs/configuration/data-validation.md | 86 +++ docs/configuration/date-time.md | 20 + docs/configuration/default-values.md | 77 +++ docs/configuration/development.md | 21 + docs/configuration/dynamic-settings.md | 232 --------- docs/configuration/index.md | 44 +- docs/configuration/miscellaneous.md | 159 ++++++ docs/configuration/napalm.md | 51 ++ docs/configuration/optional-settings.md | 489 ------------------ docs/configuration/plugins.md | 35 ++ docs/configuration/remote-authentication.md | 32 +- ...red-settings.md => required-parameters.md} | 0 docs/configuration/security.md | 144 ++++++ docs/configuration/system.md | 178 +++++++ docs/customization/custom-validation.md | 2 +- docs/customization/export-templates.md | 2 +- docs/customization/reports.md | 2 +- docs/graphql-api/overview.md | 2 +- docs/installation/3-netbox.md | 6 +- docs/installation/6-ldap.md | 2 +- docs/plugins/development/models.md | 2 +- docs/release-notes/version-3.0.md | 2 +- docs/release-notes/version-3.1.md | 2 - docs/release-notes/version-3.2.md | 4 +- docs/rest-api/authentication.md | 2 +- docs/rest-api/overview.md | 4 +- mkdocs.yml | 15 +- 29 files changed, 851 insertions(+), 770 deletions(-) create mode 100644 docs/configuration/data-validation.md create mode 100644 docs/configuration/date-time.md create mode 100644 docs/configuration/default-values.md create mode 100644 docs/configuration/development.md delete mode 100644 docs/configuration/dynamic-settings.md create mode 100644 docs/configuration/miscellaneous.md create mode 100644 docs/configuration/napalm.md delete mode 100644 docs/configuration/optional-settings.md create mode 100644 docs/configuration/plugins.md rename docs/configuration/{required-settings.md => required-parameters.md} (100%) create mode 100644 docs/configuration/security.md create mode 100644 docs/configuration/system.md diff --git a/docs/additional-features/napalm.md b/docs/additional-features/napalm.md index 2387bc8b7..60d8014e2 100644 --- a/docs/additional-features/napalm.md +++ b/docs/additional-features/napalm.md @@ -29,7 +29,7 @@ GET /api/dcim/devices/1/napalm/?method=get_environment ## Authentication -By default, the [`NAPALM_USERNAME`](../configuration/dynamic-settings.md#napalm_username) and [`NAPALM_PASSWORD`](../configuration/dynamic-settings.md#napalm_password) configuration parameters are used for NAPALM authentication. They can be overridden for an individual API call by specifying the `X-NAPALM-Username` and `X-NAPALM-Password` headers. +By default, the [`NAPALM_USERNAME`](../configuration/napalm.md#napalm_username) and [`NAPALM_PASSWORD`](../configuration/napalm.md#napalm_password) configuration parameters are used for NAPALM authentication. They can be overridden for an individual API call by specifying the `X-NAPALM-Username` and `X-NAPALM-Password` headers. ``` $ curl "http://localhost/api/dcim/devices/1/napalm/?method=get_environment" \ diff --git a/docs/administration/housekeeping.md b/docs/administration/housekeeping.md index 1989e41c0..da1a5443b 100644 --- a/docs/administration/housekeeping.md +++ b/docs/administration/housekeeping.md @@ -3,8 +3,8 @@ NetBox includes a `housekeeping` management command that should be run nightly. This command handles: * Clearing expired authentication sessions from the database -* Deleting changelog records older than the configured [retention time](../configuration/dynamic-settings.md#changelog_retention) -* Deleting job result records older than the configured [retention time](../configuration/dynamic-settings.md#jobresult_retention) +* Deleting changelog records older than the configured [retention time](../configuration/miscellaneous.md#changelog_retention) +* Deleting job result records older than the configured [retention time](../configuration/miscellaneous.md#jobresult_retention) This command can be invoked directly, or by using the shell script provided at `/opt/netbox/contrib/netbox-housekeeping.sh`. This script can be linked from your cron scheduler's daily jobs directory (e.g. `/etc/cron.daily`) or referenced directly within the cron configuration file. diff --git a/docs/configuration/data-validation.md b/docs/configuration/data-validation.md new file mode 100644 index 000000000..e4eb4baff --- /dev/null +++ b/docs/configuration/data-validation.md @@ -0,0 +1,86 @@ +# Data & Validation Parameters + +## CUSTOM_VALIDATORS + +!!! tip "Dynamic Configuration Parameter" + +This is a mapping of models to [custom validators](../customization/custom-validation.md) that have been defined locally to enforce custom validation logic. An example is provided below: + +```python +CUSTOM_VALIDATORS = { + "dcim.site": [ + { + "name": { + "min_length": 5, + "max_length": 30 + } + }, + "my_plugin.validators.Validator1" + ], + "dim.device": [ + "my_plugin.validators.Validator1" + ] +} +``` + +--- + +## FIELD_CHOICES + +Some static choice fields on models can be configured with custom values. This is done by defining `FIELD_CHOICES` as a dictionary mapping model fields to their choices. Each choice in the list must have a database value and a human-friendly label, and may optionally specify a color. (A list of available colors is provided below.) + +The choices provided can either replace the stock choices provided by NetBox, or append to them. To _replace_ the available choices, specify the app, model, and field name separated by dots. For example, the site model would be referenced as `dcim.Site.status`. To _extend_ the available choices, append a plus sign to the end of this string (e.g. `dcim.Site.status+`). + +For example, the following configuration would replace the default site status choices with the options Foo, Bar, and Baz: + +```python +FIELD_CHOICES = { + 'dcim.Site.status': ( + ('foo', 'Foo', 'red'), + ('bar', 'Bar', 'green'), + ('baz', 'Baz', 'blue'), + ) +} +``` + +Appending a plus sign to the field identifier would instead _add_ these choices to the ones already offered: + +```python +FIELD_CHOICES = { + 'dcim.Site.status+': ( + ... + ) +} +``` + +The following model fields support configurable choices: + +* `circuits.Circuit.status` +* `dcim.Device.status` +* `dcim.Location.status` +* `dcim.PowerFeed.status` +* `dcim.Rack.status` +* `dcim.Site.status` +* `extras.JournalEntry.kind` +* `ipam.IPAddress.status` +* `ipam.IPRange.status` +* `ipam.Prefix.status` +* `ipam.VLAN.status` +* `virtualization.Cluster.status` +* `virtualization.VirtualMachine.status` + +The following colors are supported: + +* `blue` +* `indigo` +* `purple` +* `pink` +* `red` +* `orange` +* `yellow` +* `green` +* `teal` +* `cyan` +* `gray` +* `black` +* `white` diff --git a/docs/configuration/date-time.md b/docs/configuration/date-time.md new file mode 100644 index 000000000..ab8b5ad13 --- /dev/null +++ b/docs/configuration/date-time.md @@ -0,0 +1,20 @@ +# Date & Time Parameters + +## TIME_ZONE + +Default: UTC + +The time zone NetBox will use when dealing with dates and times. It is recommended to use UTC time unless you have a specific need to use a local time zone. Please see the [list of available time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + +## Date and Time Formatting + +You may define custom formatting for date and times. For detailed instructions on writing format strings, please see [the Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#date). Default formats are listed below. + +```python +DATE_FORMAT = 'N j, Y' # June 26, 2016 +SHORT_DATE_FORMAT = 'Y-m-d' # 2016-06-26 +TIME_FORMAT = 'g:i a' # 1:23 p.m. +SHORT_TIME_FORMAT = 'H:i:s' # 13:23:00 +DATETIME_FORMAT = 'N j, Y g:i a' # June 26, 2016 1:23 p.m. +SHORT_DATETIME_FORMAT = 'Y-m-d H:i' # 2016-06-26 13:23 +``` diff --git a/docs/configuration/default-values.md b/docs/configuration/default-values.md new file mode 100644 index 000000000..6d92858eb --- /dev/null +++ b/docs/configuration/default-values.md @@ -0,0 +1,77 @@ +# Default Value Parameters + +## DEFAULT_USER_PREFERENCES + +!!! tip "Dynamic Configuration Parameter" + +This is a dictionary defining the default preferences to be set for newly-created user accounts. For example, to set the default page size for all users to 100, define the following: + +```python +DEFAULT_USER_PREFERENCES = { + "pagination": { + "per_page": 100 + } +} +``` + +For a complete list of available preferences, log into NetBox and navigate to `/user/preferences/`. A period in a preference name indicates a level of nesting in the JSON data. The example above maps to `pagination.per_page`. + +--- + +## PAGINATE_COUNT + +!!! tip "Dynamic Configuration Parameter" + +Default: 50 + +The default maximum number of objects to display per page within each list of objects. + +--- + +## POWERFEED_DEFAULT_AMPERAGE + +!!! tip "Dynamic Configuration Parameter" + +Default: 15 + +The default value for the `amperage` field when creating new power feeds. + +--- + +## POWERFEED_DEFAULT_MAX_UTILIZATION + +!!! tip "Dynamic Configuration Parameter" + +Default: 80 + +The default value (percentage) for the `max_utilization` field when creating new power feeds. + +--- + +## POWERFEED_DEFAULT_VOLTAGE + +!!! tip "Dynamic Configuration Parameter" + +Default: 120 + +The default value for the `voltage` field when creating new power feeds. + +--- + +## RACK_ELEVATION_DEFAULT_UNIT_HEIGHT + +!!! tip "Dynamic Configuration Parameter" + +Default: 22 + +Default height (in pixels) of a unit within a rack elevation. For best results, this should be approximately one tenth of `RACK_ELEVATION_DEFAULT_UNIT_WIDTH`. + +--- + +## RACK_ELEVATION_DEFAULT_UNIT_WIDTH + +!!! tip "Dynamic Configuration Parameter" + +Default: 220 + +Default width (in pixels) of a unit within a rack elevation. diff --git a/docs/configuration/development.md b/docs/configuration/development.md new file mode 100644 index 000000000..3af56b0e3 --- /dev/null +++ b/docs/configuration/development.md @@ -0,0 +1,21 @@ +# Development Parameters + +## DEBUG + +Default: False + +This setting enables debugging. Debugging should be enabled only during development or troubleshooting. Note that only +clients which access NetBox from a recognized [internal IP address](#internal_ips) will see debugging tools in the user +interface. + +!!! warning + Never enable debugging on a production system, as it can expose sensitive data to unauthenticated users and impose a + substantial performance penalty. + +--- + +## DEVELOPER + +Default: False + +This parameter serves as a safeguard to prevent some potentially dangerous behavior, such as generating new database schema migrations. Set this to `True` **only** if you are actively developing the NetBox code base. diff --git a/docs/configuration/dynamic-settings.md b/docs/configuration/dynamic-settings.md deleted file mode 100644 index d376dc5c4..000000000 --- a/docs/configuration/dynamic-settings.md +++ /dev/null @@ -1,232 +0,0 @@ -# Dynamic Configuration Settings - -These configuration parameters are primarily controlled via NetBox's admin interface (under Admin > Extras > Configuration Revisions). These setting may also be overridden in `configuration.py`; this will prevent them from being modified via the UI. - ---- - -## ALLOWED_URL_SCHEMES - -Default: `('file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto', 'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp')` - -A list of permitted URL schemes referenced when rendering links within NetBox. Note that only the schemes specified in this list will be accepted: If adding your own, be sure to replicate all of the default values as well (excluding those schemes which are not desirable). - ---- - -## BANNER_TOP - -## BANNER_BOTTOM - -Setting these variables will display custom content in a banner at the top and/or bottom of the page, respectively. HTML is allowed. To replicate the content of the top banner in the bottom banner, set: - -```python -BANNER_TOP = 'Your banner text' -BANNER_BOTTOM = BANNER_TOP -``` - ---- - -## BANNER_LOGIN - -This defines custom content to be displayed on the login page above the login form. HTML is allowed. - ---- - -## CHANGELOG_RETENTION - -Default: 90 - -The number of days to retain logged changes (object creations, updates, and deletions). Set this to `0` to retain -changes in the database indefinitely. - -!!! warning - If enabling indefinite changelog retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity. - ---- - -## CUSTOM_VALIDATORS - -This is a mapping of models to [custom validators](../customization/custom-validation.md) that have been defined locally to enforce custom validation logic. An example is provided below: - -```python -CUSTOM_VALIDATORS = { - "dcim.site": [ - { - "name": { - "min_length": 5, - "max_length": 30 - } - }, - "my_plugin.validators.Validator1" - ], - "dim.device": [ - "my_plugin.validators.Validator1" - ] -} -``` - ---- - -## DEFAULT_USER_PREFERENCES - -This is a dictionary defining the default preferences to be set for newly-created user accounts. For example, to set the default page size for all users to 100, define the following: - -```python -DEFAULT_USER_PREFERENCES = { - "pagination": { - "per_page": 100 - } -} -``` - -For a complete list of available preferences, log into NetBox and navigate to `/user/preferences/`. A period in a preference name indicates a level of nesting in the JSON data. The example above maps to `pagination.per_page`. - ---- - -## ENFORCE_GLOBAL_UNIQUE - -Default: False - -By default, NetBox will permit users to create duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This behavior can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to True. - ---- - -## GRAPHQL_ENABLED - -Default: True - -Setting this to False will disable the GraphQL API. - ---- - -## JOBRESULT_RETENTION - -Default: 90 - -The number of days to retain job results (scripts and reports). Set this to `0` to retain -job results in the database indefinitely. - -!!! warning - If enabling indefinite job results retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity. - ---- - -## MAINTENANCE_MODE - -Default: False - -Setting this to True will display a "maintenance mode" banner at the top of every page. Additionally, NetBox will no longer update a user's "last active" time upon login. This is to allow new logins when the database is in a read-only state. Recording of login times will resume when maintenance mode is disabled. - ---- - -## MAPS_URL - -Default: `https://maps.google.com/?q=` (Google Maps) - -This specifies the URL to use when presenting a map of a physical location by street address or GPS coordinates. The URL must accept either a free-form street address or a comma-separated pair of numeric coordinates appended to it. - ---- - -## MAX_PAGE_SIZE - -Default: 1000 - -A web user or API consumer can request an arbitrary number of objects by appending the "limit" parameter to the URL (e.g. `?limit=1000`). This parameter defines the maximum acceptable limit. Setting this to `0` or `None` will allow a client to retrieve _all_ matching objects at once with no limit by specifying `?limit=0`. - ---- - -## NAPALM_USERNAME - -## NAPALM_PASSWORD - -NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional. - -!!! note - If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed. - ---- - -## NAPALM_ARGS - -A dictionary of optional arguments to pass to NAPALM when instantiating a network driver. See the NAPALM documentation for a [complete list of optional arguments](https://napalm.readthedocs.io/en/latest/support/#optional-arguments). An example: - -```python -NAPALM_ARGS = { - 'api_key': '472071a93b60a1bd1fafb401d9f8ef41', - 'port': 2222, -} -``` - -Some platforms (e.g. Cisco IOS) require an argument named `secret` to be passed in addition to the normal password. If desired, you can use the configured `NAPALM_PASSWORD` as the value for this argument: - -```python -NAPALM_USERNAME = 'username' -NAPALM_PASSWORD = 'MySecretPassword' -NAPALM_ARGS = { - 'secret': NAPALM_PASSWORD, - # Include any additional args here -} -``` - ---- - -## NAPALM_TIMEOUT - -Default: 30 seconds - -The amount of time (in seconds) to wait for NAPALM to connect to a device. - ---- - -## PAGINATE_COUNT - -Default: 50 - -The default maximum number of objects to display per page within each list of objects. - ---- - -## POWERFEED_DEFAULT_AMPERAGE - -Default: 15 - -The default value for the `amperage` field when creating new power feeds. - ---- - -## POWERFEED_DEFAULT_MAX_UTILIZATION - -Default: 80 - -The default value (percentage) for the `max_utilization` field when creating new power feeds. - ---- - -## POWERFEED_DEFAULT_VOLTAGE - -Default: 120 - -The default value for the `voltage` field when creating new power feeds. - ---- - -## PREFER_IPV4 - -Default: False - -When determining the primary IP address for a device, IPv6 is preferred over IPv4 by default. Set this to True to prefer IPv4 instead. - ---- - -## RACK_ELEVATION_DEFAULT_UNIT_HEIGHT - -Default: 22 - -Default height (in pixels) of a unit within a rack elevation. For best results, this should be approximately one tenth of `RACK_ELEVATION_DEFAULT_UNIT_WIDTH`. - ---- - -## RACK_ELEVATION_DEFAULT_UNIT_WIDTH - -Default: 220 - -Default width (in pixels) of a unit within a rack elevation. diff --git a/docs/configuration/index.md b/docs/configuration/index.md index a863ef3dc..42d254027 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -1,24 +1,50 @@ # NetBox Configuration -NetBox's local configuration is stored in `$INSTALL_ROOT/netbox/netbox/configuration.py` by default. An example configuration is provided as `configuration_example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file. While NetBox has many configuration settings, only a few of them must be defined at the time of installation: these are defined under "required settings" below. +## Configuration File + +NetBox's configuration file contains all the important parameters which control how NetBox functions: database settings, security controls, user preferences, and so on. While the default configuration suffices out of the box for most use cases, there are a few [required parameters](./required-parameters.md) which **must** be defined during installation. + +The configuration file is loaded from `$INSTALL_ROOT/netbox/netbox/configuration.py` by default. An example configuration is provided at `configuration_example.py`, which you may copy to use as your default config. Note that a configuration file must be defined; NetBox will not run without one. !!! info "Customizing the Configuration Module" A custom configuration module may be specified by setting the `NETBOX_CONFIGURATION` environment variable. This must be a dotted path to the desired Python module. For example, a file named `my_config.py` in the same directory as `settings.py` would be referenced as `netbox.my_config`. - For the sake of brevity, the NetBox documentation refers to the configuration file simply as `configuration.py`. + To keep things simple, the NetBox documentation refers to the configuration file simply as `configuration.py`. Some configuration parameters may alternatively be defined either in `configuration.py` or within the administrative section of the user interface. Settings which are "hard-coded" in the configuration file take precedence over those defined via the UI. -## Configuration Parameters +## Dynamic Configuration Parameters -* [Required settings](required-settings.md) -* [Optional settings](optional-settings.md) -* [Dynamic settings](dynamic-settings.md) -* [Remote authentication settings](remote-authentication.md) +Some configuration parameters are primarily controlled via NetBox's admin interface (under Admin > Extras > Configuration Revisions). These are noted where applicable in the documentation. These settings may also be overridden in `configuration.py` to prevent them from being modified via the UI. A complete list of supported parameters is provided below: -## Changing the Configuration +* [`ALLOWED_URL_SCHEMES`](./security.md#allowed_url_schemes) +* [`BANNER_BOTTOM`](./miscellaneous.md#banner_bottom) +* [`BANNER_LOGIN`](./miscellaneous.md#banner_login) +* [`BANNER_TOP`](./miscellaneous.md#banner_top) +* [`CHANGELOG_RETENTION`](./miscellaneous.md#changelog_retention) +* [`CUSTOM_VALIDATORS`](./data-validation.md#custom_validators) +* [`DEFAULT_USER_PREFERENCES`](./default-values.md#default_user_preferences) +* [`ENFORCE_GLOBAL_UNIQUE`](./miscellaneous.md#enforce_global_unique) +* [`GRAPHQL_ENABLED`](./miscellaneous.md#graphql_enabled) +* [`JOBRESULT_RETENTION`](./miscellaneous.md#jobresult_retention) +* [`MAINTENANCE_MODE`](./miscellaneous.md#maintenance_mode) +* [`MAPS_URL`](./miscellaneous.md#maps_url) +* [`MAX_PAGE_SIZE`](./miscellaneous.md#max_page_size) +* [`NAPALM_ARGS`](./napalm.md#napalm_args) +* [`NAPALM_PASSWORD`](./napalm.md#napalm_password) +* [`NAPALM_TIMEOUT`](./napalm.md#napalm_timeout) +* [`NAPALM_USERNAME`](./napalm.md#napalm_username) +* [`PAGINATE_COUNT`](./default-values.md#paginate_count) +* [`POWERFEED_DEFAULT_AMPERAGE`](./default-values.md#powerfeed_default_amperage) +* [`POWERFEED_DEFAULT_MAX_UTILIZATION`](./default-values.md#powerfeed_default_max_utilization) +* [`POWERFEED_DEFAULT_VOLTAGE`](./default-values.md#powerfeed_default_voltage) +* [`PREFER_IPV4`](./miscellaneous.md#prefer_ipv4) +* [`RACK_ELEVATION_DEFAULT_UNIT_HEIGHT`](./default-values.md#rack_elevation_default_unit_height) +* [`RACK_ELEVATION_DEFAULT_UNIT_WIDTH`](./default-values.md#rack_elevation_default_unit_width) -The configuration file may be modified at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before the changes will take effect: +## Modifying the Configuration + +The configuration file may be modified at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before these changes will take effect: ```no-highlight $ sudo systemctl restart netbox diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md new file mode 100644 index 000000000..2aa21b7e5 --- /dev/null +++ b/docs/configuration/miscellaneous.md @@ -0,0 +1,159 @@ +# Miscellaneous Parameters + +## ADMINS + +NetBox will email details about critical errors to the administrators listed here. This should be a list of (name, email) tuples. For example: + +```python +ADMINS = [ + ['Hank Hill', 'hhill@example.com'], + ['Dale Gribble', 'dgribble@example.com'], +] +``` + +--- + +## BANNER_BOTTOM + +!!! tip "Dynamic Configuration Parameter" + +Sets content for the bottom banner in the user interface. + +--- + +## BANNER_LOGIN + +!!! tip "Dynamic Configuration Parameter" + +This defines custom content to be displayed on the login page above the login form. HTML is allowed. + +--- + +## BANNER_TOP + +!!! tip "Dynamic Configuration Parameter" + +Sets content for the top banner in the user interface. + +!!! tip + If you'd like the top and bottom banners to match, set the following: + + ```python + BANNER_TOP = 'Your banner text' + BANNER_BOTTOM = BANNER_TOP + ``` + +--- + +## CHANGELOG_RETENTION + +!!! tip "Dynamic Configuration Parameter" + +Default: 90 + +The number of days to retain logged changes (object creations, updates, and deletions). Set this to `0` to retain +changes in the database indefinitely. + +!!! warning + If enabling indefinite changelog retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity. + +--- + +## ENFORCE_GLOBAL_UNIQUE + +!!! tip "Dynamic Configuration Parameter" + +Default: False + +By default, NetBox will permit users to create duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This behavior can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to True. + +--- + +## GRAPHQL_ENABLED + +!!! tip "Dynamic Configuration Parameter" + +Default: True + +Setting this to False will disable the GraphQL API. + +--- + +## JOBRESULT_RETENTION + +!!! tip "Dynamic Configuration Parameter" + +Default: 90 + +The number of days to retain job results (scripts and reports). Set this to `0` to retain +job results in the database indefinitely. + +!!! warning + If enabling indefinite job results retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity. + +--- + +## MAINTENANCE_MODE + +!!! tip "Dynamic Configuration Parameter" + +Default: False + +Setting this to True will display a "maintenance mode" banner at the top of every page. Additionally, NetBox will no longer update a user's "last active" time upon login. This is to allow new logins when the database is in a read-only state. Recording of login times will resume when maintenance mode is disabled. + +--- + +## MAPS_URL + +!!! tip "Dynamic Configuration Parameter" + +Default: `https://maps.google.com/?q=` (Google Maps) + +This specifies the URL to use when presenting a map of a physical location by street address or GPS coordinates. The URL must accept either a free-form street address or a comma-separated pair of numeric coordinates appended to it. + +--- + +## MAX_PAGE_SIZE + +!!! tip "Dynamic Configuration Parameter" + +Default: 1000 + +A web user or API consumer can request an arbitrary number of objects by appending the "limit" parameter to the URL (e.g. `?limit=1000`). This parameter defines the maximum acceptable limit. Setting this to `0` or `None` will allow a client to retrieve _all_ matching objects at once with no limit by specifying `?limit=0`. + +--- + +## METRICS_ENABLED + +Default: False + +Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../additional-features/prometheus-metrics.md) documentation for more details. + +--- + +## PREFER_IPV4 + +!!! tip "Dynamic Configuration Parameter" + +Default: False + +When determining the primary IP address for a device, IPv6 is preferred over IPv4 by default. Set this to True to prefer IPv4 instead. + +--- + +## RELEASE_CHECK_URL + +Default: None (disabled) + +This parameter defines the URL of the repository that will be checked for new NetBox releases. When a new release is detected, a message will be displayed to administrative users on the home page. This can be set to the official repository (`'https://api.github.com/repos/netbox-community/netbox/releases'`) or a custom fork. Set this to `None` to disable automatic update checks. + +!!! note + The URL provided **must** be compatible with the [GitHub REST API](https://docs.github.com/en/rest). + +--- + +## RQ_DEFAULT_TIMEOUT + +Default: `300` + +The maximum execution time of a background task (such as running a custom script), in seconds. diff --git a/docs/configuration/napalm.md b/docs/configuration/napalm.md new file mode 100644 index 000000000..925ec17e6 --- /dev/null +++ b/docs/configuration/napalm.md @@ -0,0 +1,51 @@ +# NAPALM Parameters + +## NAPALM_USERNAME + +## NAPALM_PASSWORD + +!!! tip "Dynamic Configuration Parameter" + +NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional. + +!!! note + If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed. + +--- + +## NAPALM_ARGS + +!!! tip "Dynamic Configuration Parameter" + +A dictionary of optional arguments to pass to NAPALM when instantiating a network driver. See the NAPALM documentation for a [complete list of optional arguments](https://napalm.readthedocs.io/en/latest/support/#optional-arguments). An example: + +```python +NAPALM_ARGS = { + 'api_key': '472071a93b60a1bd1fafb401d9f8ef41', + 'port': 2222, +} +``` + +Some platforms (e.g. Cisco IOS) require an argument named `secret` to be passed in addition to the normal password. If desired, you can use the configured `NAPALM_PASSWORD` as the value for this argument: + +```python +NAPALM_USERNAME = 'username' +NAPALM_PASSWORD = 'MySecretPassword' +NAPALM_ARGS = { + 'secret': NAPALM_PASSWORD, + # Include any additional args here +} +``` + +--- + +## NAPALM_TIMEOUT + +!!! tip "Dynamic Configuration Parameter" + +Default: 30 seconds + +The amount of time (in seconds) to wait for NAPALM to connect to a device. + +--- + diff --git a/docs/configuration/optional-settings.md b/docs/configuration/optional-settings.md deleted file mode 100644 index 8e5664a95..000000000 --- a/docs/configuration/optional-settings.md +++ /dev/null @@ -1,489 +0,0 @@ -# Optional Configuration Settings - -## ADMINS - -NetBox will email details about critical errors to the administrators listed here. This should be a list of (name, email) tuples. For example: - -```python -ADMINS = [ - ['Hank Hill', 'hhill@example.com'], - ['Dale Gribble', 'dgribble@example.com'], -] -``` - ---- - -## AUTH_PASSWORD_VALIDATORS - -This parameter acts as a pass-through for configuring Django's built-in password validators for local user accounts. If configured, these will be applied whenever a user's password is updated to ensure that it meets minimum criteria such as length or complexity. An example is provided below. For more detail on the available options, please see [the Django documentation](https://docs.djangoproject.com/en/stable/topics/auth/passwords/#password-validation). - -```python -AUTH_PASSWORD_VALIDATORS = [ - { - 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator', - 'OPTIONS': { - 'min_length': 10, - } - }, -] -``` - ---- - -## BASE_PATH - -Default: None - -The base URL path to use when accessing NetBox. Do not include the scheme or domain name. For example, if installed at https://example.com/netbox/, set: - -```python -BASE_PATH = 'netbox/' -``` - ---- - -## CORS_ORIGIN_ALLOW_ALL - -Default: False - -If True, cross-origin resource sharing (CORS) requests will be accepted from all origins. If False, a whitelist will be used (see below). - ---- - -## CORS_ORIGIN_WHITELIST - -## CORS_ORIGIN_REGEX_WHITELIST - -These settings specify a list of origins that are authorized to make cross-site API requests. Use -`CORS_ORIGIN_WHITELIST` to define a list of exact hostnames, or `CORS_ORIGIN_REGEX_WHITELIST` to define a set of regular -expressions. (These settings have no effect if `CORS_ORIGIN_ALLOW_ALL` is True.) For example: - -```python -CORS_ORIGIN_WHITELIST = [ - 'https://example.com', -] -``` - ---- - -## CSRF_COOKIE_NAME - -Default: `csrftoken` - -The name of the cookie to use for the cross-site request forgery (CSRF) authentication token. See the [Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#csrf-cookie-name) for more detail. - ---- - -## CSRF_TRUSTED_ORIGINS - -Default: `[]` - -Defines a list of trusted origins for unsafe (e.g. `POST`) requests. This is a pass-through to Django's [`CSRF_TRUSTED_ORIGINS`](https://docs.djangoproject.com/en/4.0/ref/settings/#std:setting-CSRF_TRUSTED_ORIGINS) setting. Note that each host listed must specify a scheme (e.g. `http://` or `https://). - -```python -CSRF_TRUSTED_ORIGINS = ( - 'http://netbox.local', - 'https://netbox.local', -) -``` - ---- - -## DEBUG - -Default: False - -This setting enables debugging. Debugging should be enabled only during development or troubleshooting. Note that only -clients which access NetBox from a recognized [internal IP address](#internal_ips) will see debugging tools in the user -interface. - -!!! warning - Never enable debugging on a production system, as it can expose sensitive data to unauthenticated users and impose a - substantial performance penalty. - ---- - -## DEVELOPER - -Default: False - -This parameter serves as a safeguard to prevent some potentially dangerous behavior, such as generating new database schema migrations. Set this to `True` **only** if you are actively developing the NetBox code base. - ---- - -## DOCS_ROOT - -Default: `$INSTALL_ROOT/docs/` - -The filesystem path to NetBox's documentation. This is used when presenting context-sensitive documentation in the web UI. By default, this will be the `docs/` directory within the root NetBox installation path. (Set this to `None` to disable the embedded documentation.) - ---- - -## EMAIL - -In order to send email, NetBox needs an email server configured. The following items can be defined within the `EMAIL` configuration parameter: - -* `SERVER` - Hostname or IP address of the email server (use `localhost` if running locally) -* `PORT` - TCP port to use for the connection (default: `25`) -* `USERNAME` - Username with which to authenticate -* `PASSSWORD` - Password with which to authenticate -* `USE_SSL` - Use SSL when connecting to the server (default: `False`) -* `USE_TLS` - Use TLS when connecting to the server (default: `False`) -* `SSL_CERTFILE` - Path to the PEM-formatted SSL certificate file (optional) -* `SSL_KEYFILE` - Path to the PEM-formatted SSL private key file (optional) -* `TIMEOUT` - Amount of time to wait for a connection, in seconds (default: `10`) -* `FROM_EMAIL` - Sender address for emails sent by NetBox - -!!! note - The `USE_SSL` and `USE_TLS` parameters are mutually exclusive. - -Email is sent from NetBox only for critical events or if configured for [logging](#logging). If you would like to test the email server configuration, Django provides a convenient [send_mail()](https://docs.djangoproject.com/en/stable/topics/email/#send-mail) function accessible within the NetBox shell: - -```no-highlight -# python ./manage.py nbshell ->>> from django.core.mail import send_mail ->>> send_mail( - 'Test Email Subject', - 'Test Email Body', - 'noreply-netbox@example.com', - ['users@example.com'], - fail_silently=False -) -``` - ---- - -## EXEMPT_VIEW_PERMISSIONS - -Default: Empty list - -A list of NetBox models to exempt from the enforcement of view permissions. Models listed here will be viewable by all users, both authenticated and anonymous. - -List models in the form `.`. For example: - -```python -EXEMPT_VIEW_PERMISSIONS = [ - 'dcim.site', - 'dcim.region', - 'ipam.prefix', -] -``` - -To exempt _all_ models from view permission enforcement, set the following. (Note that `EXEMPT_VIEW_PERMISSIONS` must be an iterable.) - -```python -EXEMPT_VIEW_PERMISSIONS = ['*'] -``` - -!!! note - Using a wildcard will not affect certain potentially sensitive models, such as user permissions. If there is a need to exempt these models, they must be specified individually. - ---- - -## FIELD_CHOICES - -Some static choice fields on models can be configured with custom values. This is done by defining `FIELD_CHOICES` as a dictionary mapping model fields to their choices. Each choice in the list must have a database value and a human-friendly label, and may optionally specify a color. (A list of available colors is provided below.) - -The choices provided can either replace the stock choices provided by NetBox, or append to them. To _replace_ the available choices, specify the app, model, and field name separated by dots. For example, the site model would be referenced as `dcim.Site.status`. To _extend_ the available choices, append a plus sign to the end of this string (e.g. `dcim.Site.status+`). - -For example, the following configuration would replace the default site status choices with the options Foo, Bar, and Baz: - -```python -FIELD_CHOICES = { - 'dcim.Site.status': ( - ('foo', 'Foo', 'red'), - ('bar', 'Bar', 'green'), - ('baz', 'Baz', 'blue'), - ) -} -``` - -Appending a plus sign to the field identifier would instead _add_ these choices to the ones already offered: - -```python -FIELD_CHOICES = { - 'dcim.Site.status+': ( - ... - ) -} -``` - -The following model fields support configurable choices: - -* `circuits.Circuit.status` -* `dcim.Device.status` -* `dcim.Location.status` -* `dcim.PowerFeed.status` -* `dcim.Rack.status` -* `dcim.Site.status` -* `extras.JournalEntry.kind` -* `ipam.IPAddress.status` -* `ipam.IPRange.status` -* `ipam.Prefix.status` -* `ipam.VLAN.status` -* `virtualization.Cluster.status` -* `virtualization.VirtualMachine.status` - -The following colors are supported: - -* `blue` -* `indigo` -* `purple` -* `pink` -* `red` -* `orange` -* `yellow` -* `green` -* `teal` -* `cyan` -* `gray` -* `black` -* `white` - ---- - -## HTTP_PROXIES - -Default: None - -A dictionary of HTTP proxies to use for outbound requests originating from NetBox (e.g. when sending webhook requests). Proxies should be specified by schema (HTTP and HTTPS) as per the [Python requests library documentation](https://2.python-requests.org/en/master/user/advanced/). For example: - -```python -HTTP_PROXIES = { - 'http': 'http://10.10.1.10:3128', - 'https': 'http://10.10.1.10:1080', -} -``` - ---- - -## JINJA2_FILTERS - -Default: `{}` - -A dictionary of custom jinja2 filters with the key being the filter name and the value being a callable. For more information see the [Jinja2 documentation](https://jinja.palletsprojects.com/en/3.1.x/api/#custom-filters). For example: - -```python -def uppercase(x): - return str(x).upper() - -JINJA2_FILTERS = { - 'uppercase': uppercase, -} -``` - ---- - -## INTERNAL_IPS - -Default: `('127.0.0.1', '::1')` - -A list of IP addresses recognized as internal to the system, used to control the display of debugging output. For -example, the debugging toolbar will be viewable only when a client is accessing NetBox from one of the listed IP -addresses (and [`DEBUG`](#debug) is true). - ---- - -## LOGGING - -By default, all messages of INFO severity or higher will be logged to the console. Additionally, if [`DEBUG`](#debug) is False and email access has been configured, ERROR and CRITICAL messages will be emailed to the users defined in [`ADMINS`](#admins). - -The Django framework on which NetBox runs allows for the customization of logging format and destination. Please consult the [Django logging documentation](https://docs.djangoproject.com/en/stable/topics/logging/) for more information on configuring this setting. Below is an example which will write all INFO and higher messages to a local file: - -```python -LOGGING = { - 'version': 1, - 'disable_existing_loggers': False, - 'handlers': { - 'file': { - 'level': 'INFO', - 'class': 'logging.FileHandler', - 'filename': '/var/log/netbox.log', - }, - }, - 'loggers': { - 'django': { - 'handlers': ['file'], - 'level': 'INFO', - }, - }, -} -``` - -### Available Loggers - -* `netbox..` - Generic form for model-specific log messages -* `netbox.auth.*` - Authentication events -* `netbox.api.views.*` - Views which handle business logic for the REST API -* `netbox.reports.*` - Report execution (`module.name`) -* `netbox.scripts.*` - Custom script execution (`module.name`) -* `netbox.views.*` - Views which handle business logic for the web UI - ---- - -## LOGIN_PERSISTENCE - -Default: False - -If true, the lifetime of a user's authentication session will be automatically reset upon each valid request. For example, if [`LOGIN_TIMEOUT`](#login_timeout) is configured to 14 days (the default), and a user whose session is due to expire in five days makes a NetBox request (with a valid session cookie), the session's lifetime will be reset to 14 days. - -Note that enabling this setting causes NetBox to update a user's session in the database (or file, as configured per [`SESSION_FILE_PATH`](#session_file_path)) with each request, which may introduce significant overhead in very active environments. It also permits an active user to remain authenticated to NetBox indefinitely. - ---- - -## LOGIN_REQUIRED - -Default: False - -Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users are permitted to access most data in NetBox but not make any changes. - ---- - -## LOGIN_TIMEOUT - -Default: 1209600 seconds (14 days) - -The lifetime (in seconds) of the authentication cookie issued to a NetBox user upon login. - ---- - -## MEDIA_ROOT - -Default: $INSTALL_ROOT/netbox/media/ - -The file path to the location where media files (such as image attachments) are stored. By default, this is the `netbox/media/` directory within the base NetBox installation path. - ---- - -## METRICS_ENABLED - -Default: False - -Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../additional-features/prometheus-metrics.md) documentation for more details. - ---- - -## PLUGINS - -Default: Empty - -A list of installed [NetBox plugins](../../plugins/) to enable. Plugins will not take effect unless they are listed here. - -!!! warning - Plugins extend NetBox by allowing external code to run with the same access and privileges as NetBox itself. Only install plugins from trusted sources. The NetBox maintainers make absolutely no guarantees about the integrity or security of your installation with plugins enabled. - ---- - -## PLUGINS_CONFIG - -Default: Empty - -This parameter holds configuration settings for individual NetBox plugins. It is defined as a dictionary, with each key using the name of an installed plugin. The specific parameters supported are unique to each plugin: Reference the plugin's documentation to determine the supported parameters. An example configuration is shown below: - -```python -PLUGINS_CONFIG = { - 'plugin1': { - 'foo': 123, - 'bar': True - }, - 'plugin2': { - 'foo': 456, - }, -} -``` - -Note that a plugin must be listed in `PLUGINS` for its configuration to take effect. - ---- - -## RELEASE_CHECK_URL - -Default: None (disabled) - -This parameter defines the URL of the repository that will be checked for new NetBox releases. When a new release is detected, a message will be displayed to administrative users on the home page. This can be set to the official repository (`'https://api.github.com/repos/netbox-community/netbox/releases'`) or a custom fork. Set this to `None` to disable automatic update checks. - -!!! note - The URL provided **must** be compatible with the [GitHub REST API](https://docs.github.com/en/rest). - ---- - -## REPORTS_ROOT - -Default: `$INSTALL_ROOT/netbox/reports/` - -The file path to the location where [custom reports](../customization/reports.md) will be kept. By default, this is the `netbox/reports/` directory within the base NetBox installation path. - ---- - -## RQ_DEFAULT_TIMEOUT - -Default: `300` - -The maximum execution time of a background task (such as running a custom script), in seconds. - ---- - -## SCRIPTS_ROOT - -Default: `$INSTALL_ROOT/netbox/scripts/` - -The file path to the location where [custom scripts](../customization/custom-scripts.md) will be kept. By default, this is the `netbox/scripts/` directory within the base NetBox installation path. - ---- - -## SESSION_COOKIE_NAME - -Default: `sessionid` - -The name used for the session cookie. See the [Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#session-cookie-name) for more detail. - ---- - -## SESSION_FILE_PATH - -Default: None - -HTTP session data is used to track authenticated users when they access NetBox. By default, NetBox stores session data in its PostgreSQL database. However, this inhibits authentication to a standby instance of NetBox without write access to the database. Alternatively, a local file path may be specified here and NetBox will store session data as files instead of using the database. Note that the NetBox system user must have read and write permissions to this path. - ---- - -## STORAGE_BACKEND - -Default: None (local storage) - -The backend storage engine for handling uploaded files (e.g. image attachments). NetBox supports integration with the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) package, which provides backends for several popular file storage services. If not configured, local filesystem storage will be used. - -The configuration parameters for the specified storage backend are defined under the `STORAGE_CONFIG` setting. - ---- - -## STORAGE_CONFIG - -Default: Empty - -A dictionary of configuration parameters for the storage backend configured as `STORAGE_BACKEND`. The specific parameters to be used here are specific to each backend; see the [`django-storages` documentation](https://django-storages.readthedocs.io/en/stable/) for more detail. - -If `STORAGE_BACKEND` is not defined, this setting will be ignored. - ---- - -## TIME_ZONE - -Default: UTC - -The time zone NetBox will use when dealing with dates and times. It is recommended to use UTC time unless you have a specific need to use a local time zone. Please see the [list of available time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - ---- - -## Date and Time Formatting - -You may define custom formatting for date and times. For detailed instructions on writing format strings, please see [the Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#date). Default formats are listed below. - -```python -DATE_FORMAT = 'N j, Y' # June 26, 2016 -SHORT_DATE_FORMAT = 'Y-m-d' # 2016-06-26 -TIME_FORMAT = 'g:i a' # 1:23 p.m. -SHORT_TIME_FORMAT = 'H:i:s' # 13:23:00 -DATETIME_FORMAT = 'N j, Y g:i a' # June 26, 2016 1:23 p.m. -SHORT_DATETIME_FORMAT = 'Y-m-d H:i' # 2016-06-26 13:23 -``` diff --git a/docs/configuration/plugins.md b/docs/configuration/plugins.md new file mode 100644 index 000000000..aea60f389 --- /dev/null +++ b/docs/configuration/plugins.md @@ -0,0 +1,35 @@ +# Plugin Parameters + +## PLUGINS + +Default: Empty + +A list of installed [NetBox plugins](../../plugins/) to enable. Plugins will not take effect unless they are listed here. + +!!! warning + Plugins extend NetBox by allowing external code to run with the same access and privileges as NetBox itself. Only install plugins from trusted sources. The NetBox maintainers make absolutely no guarantees about the integrity or security of your installation with plugins enabled. + +--- + +## PLUGINS_CONFIG + +Default: Empty + +This parameter holds configuration settings for individual NetBox plugins. It is defined as a dictionary, with each key using the name of an installed plugin. The specific parameters supported are unique to each plugin: Reference the plugin's documentation to determine the supported parameters. An example configuration is shown below: + +```python +PLUGINS_CONFIG = { + 'plugin1': { + 'foo': 123, + 'bar': True + }, + 'plugin2': { + 'foo': 456, + }, +} +``` + +Note that a plugin must be listed in `PLUGINS` for its configuration to take effect. + +--- + diff --git a/docs/configuration/remote-authentication.md b/docs/configuration/remote-authentication.md index 2c3a7002f..07adf5c6a 100644 --- a/docs/configuration/remote-authentication.md +++ b/docs/configuration/remote-authentication.md @@ -47,6 +47,22 @@ NetBox can be configured to support remote user authentication by inferring user --- +## REMOTE_AUTH_GROUP_HEADER + +Default: `'HTTP_REMOTE_USER_GROUP'` + +When remote user authentication is in use, this is the name of the HTTP header which informs NetBox of the currently authenticated user. For example, to use the request header `X-Remote-User-Groups` it needs to be set to `HTTP_X_REMOTE_USER_GROUPS`. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) + +--- + +## REMOTE_AUTH_GROUP_SEPARATOR + +Default: `|` (Pipe) + +The Seperator upon which `REMOTE_AUTH_GROUP_HEADER` gets split into individual Groups. This needs to be coordinated with your authentication Proxy. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) + +--- + ## REMOTE_AUTH_GROUP_SYNC_ENABLED Default: `False` @@ -63,14 +79,6 @@ When remote user authentication is in use, this is the name of the HTTP header w --- -## REMOTE_AUTH_GROUP_HEADER - -Default: `'HTTP_REMOTE_USER_GROUP'` - -When remote user authentication is in use, this is the name of the HTTP header which informs NetBox of the currently authenticated user. For example, to use the request header `X-Remote-User-Groups` it needs to be set to `HTTP_X_REMOTE_USER_GROUPS`. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) - ---- - ## REMOTE_AUTH_SUPERUSER_GROUPS Default: `[]` (Empty list) @@ -100,11 +108,3 @@ The list of groups that promote an remote User to Staff on Login. If group isn't Default: `[]` (Empty list) The list of users that get promoted to Staff on Login. If user isn't present in list on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) - ---- - -## REMOTE_AUTH_GROUP_SEPARATOR - -Default: `|` (Pipe) - -The Seperator upon which `REMOTE_AUTH_GROUP_HEADER` gets split into individual Groups. This needs to be coordinated with your authentication Proxy. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) diff --git a/docs/configuration/required-settings.md b/docs/configuration/required-parameters.md similarity index 100% rename from docs/configuration/required-settings.md rename to docs/configuration/required-parameters.md diff --git a/docs/configuration/security.md b/docs/configuration/security.md new file mode 100644 index 000000000..6aa363b1a --- /dev/null +++ b/docs/configuration/security.md @@ -0,0 +1,144 @@ +# Security & Authentication Parameters + +## ALLOWED_URL_SCHEMES + +!!! tip "Dynamic Configuration Parameter" + +Default: `('file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto', 'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp')` + +A list of permitted URL schemes referenced when rendering links within NetBox. Note that only the schemes specified in this list will be accepted: If adding your own, be sure to replicate all the default values as well (excluding those schemes which are not desirable). + +--- + +## AUTH_PASSWORD_VALIDATORS + +This parameter acts as a pass-through for configuring Django's built-in password validators for local user accounts. If configured, these will be applied whenever a user's password is updated to ensure that it meets minimum criteria such as length or complexity. An example is provided below. For more detail on the available options, please see [the Django documentation](https://docs.djangoproject.com/en/stable/topics/auth/passwords/#password-validation). + +```python +AUTH_PASSWORD_VALIDATORS = [ + { + 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator', + 'OPTIONS': { + 'min_length': 10, + } + }, +] +``` + +--- + +## CORS_ORIGIN_ALLOW_ALL + +Default: False + +If True, cross-origin resource sharing (CORS) requests will be accepted from all origins. If False, a whitelist will be used (see below). + +--- + +## CORS_ORIGIN_WHITELIST + +## CORS_ORIGIN_REGEX_WHITELIST + +These settings specify a list of origins that are authorized to make cross-site API requests. Use +`CORS_ORIGIN_WHITELIST` to define a list of exact hostnames, or `CORS_ORIGIN_REGEX_WHITELIST` to define a set of regular +expressions. (These settings have no effect if `CORS_ORIGIN_ALLOW_ALL` is True.) For example: + +```python +CORS_ORIGIN_WHITELIST = [ + 'https://example.com', +] +``` + +--- + +## CSRF_COOKIE_NAME + +Default: `csrftoken` + +The name of the cookie to use for the cross-site request forgery (CSRF) authentication token. See the [Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#csrf-cookie-name) for more detail. + +--- + +--- + +## CSRF_TRUSTED_ORIGINS + +Default: `[]` + +Defines a list of trusted origins for unsafe (e.g. `POST`) requests. This is a pass-through to Django's [`CSRF_TRUSTED_ORIGINS`](https://docs.djangoproject.com/en/4.0/ref/settings/#std:setting-CSRF_TRUSTED_ORIGINS) setting. Note that each host listed must specify a scheme (e.g. `http://` or `https://). + +```python +CSRF_TRUSTED_ORIGINS = ( + 'http://netbox.local', + 'https://netbox.local', +) +``` + +--- + +## EXEMPT_VIEW_PERMISSIONS + +Default: Empty list + +A list of NetBox models to exempt from the enforcement of view permissions. Models listed here will be viewable by all users, both authenticated and anonymous. + +List models in the form `.`. For example: + +```python +EXEMPT_VIEW_PERMISSIONS = [ + 'dcim.site', + 'dcim.region', + 'ipam.prefix', +] +``` + +To exempt _all_ models from view permission enforcement, set the following. (Note that `EXEMPT_VIEW_PERMISSIONS` must be an iterable.) + +```python +EXEMPT_VIEW_PERMISSIONS = ['*'] +``` + +!!! note + Using a wildcard will not affect certain potentially sensitive models, such as user permissions. If there is a need to exempt these models, they must be specified individually. + +--- + +## LOGIN_PERSISTENCE + +Default: False + +If true, the lifetime of a user's authentication session will be automatically reset upon each valid request. For example, if [`LOGIN_TIMEOUT`](#login_timeout) is configured to 14 days (the default), and a user whose session is due to expire in five days makes a NetBox request (with a valid session cookie), the session's lifetime will be reset to 14 days. + +Note that enabling this setting causes NetBox to update a user's session in the database (or file, as configured per [`SESSION_FILE_PATH`](#session_file_path)) with each request, which may introduce significant overhead in very active environments. It also permits an active user to remain authenticated to NetBox indefinitely. + +--- + +## LOGIN_REQUIRED + +Default: False + +Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users are permitted to access most data in NetBox but not make any changes. + +--- + +## LOGIN_TIMEOUT + +Default: 1209600 seconds (14 days) + +The lifetime (in seconds) of the authentication cookie issued to a NetBox user upon login. + +--- + +## SESSION_COOKIE_NAME + +Default: `sessionid` + +The name used for the session cookie. See the [Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#session-cookie-name) for more detail. + +--- + +## SESSION_FILE_PATH + +Default: None + +HTTP session data is used to track authenticated users when they access NetBox. By default, NetBox stores session data in its PostgreSQL database. However, this inhibits authentication to a standby instance of NetBox without write access to the database. Alternatively, a local file path may be specified here and NetBox will store session data as files instead of using the database. Note that the NetBox system user must have read and write permissions to this path. diff --git a/docs/configuration/system.md b/docs/configuration/system.md new file mode 100644 index 000000000..21607e566 --- /dev/null +++ b/docs/configuration/system.md @@ -0,0 +1,178 @@ +# System Parameters + +## BASE_PATH + +Default: None + +The base URL path to use when accessing NetBox. Do not include the scheme or domain name. For example, if installed at https://example.com/netbox/, set: + +```python +BASE_PATH = 'netbox/' +``` + +--- + +## DOCS_ROOT + +Default: `$INSTALL_ROOT/docs/` + +The filesystem path to NetBox's documentation. This is used when presenting context-sensitive documentation in the web UI. By default, this will be the `docs/` directory within the root NetBox installation path. (Set this to `None` to disable the embedded documentation.) + +--- + +## EMAIL + +In order to send email, NetBox needs an email server configured. The following items can be defined within the `EMAIL` configuration parameter: + +* `SERVER` - Hostname or IP address of the email server (use `localhost` if running locally) +* `PORT` - TCP port to use for the connection (default: `25`) +* `USERNAME` - Username with which to authenticate +* `PASSSWORD` - Password with which to authenticate +* `USE_SSL` - Use SSL when connecting to the server (default: `False`) +* `USE_TLS` - Use TLS when connecting to the server (default: `False`) +* `SSL_CERTFILE` - Path to the PEM-formatted SSL certificate file (optional) +* `SSL_KEYFILE` - Path to the PEM-formatted SSL private key file (optional) +* `TIMEOUT` - Amount of time to wait for a connection, in seconds (default: `10`) +* `FROM_EMAIL` - Sender address for emails sent by NetBox + +!!! note + The `USE_SSL` and `USE_TLS` parameters are mutually exclusive. + +Email is sent from NetBox only for critical events or if configured for [logging](#logging). If you would like to test the email server configuration, Django provides a convenient [send_mail()](https://docs.djangoproject.com/en/stable/topics/email/#send-mail) function accessible within the NetBox shell: + +```no-highlight +# python ./manage.py nbshell +>>> from django.core.mail import send_mail +>>> send_mail( + 'Test Email Subject', + 'Test Email Body', + 'noreply-netbox@example.com', + ['users@example.com'], + fail_silently=False +) +``` + +--- + +## HTTP_PROXIES + +Default: None + +A dictionary of HTTP proxies to use for outbound requests originating from NetBox (e.g. when sending webhook requests). Proxies should be specified by schema (HTTP and HTTPS) as per the [Python requests library documentation](https://2.python-requests.org/en/master/user/advanced/). For example: + +```python +HTTP_PROXIES = { + 'http': 'http://10.10.1.10:3128', + 'https': 'http://10.10.1.10:1080', +} +``` + +--- + +## INTERNAL_IPS + +Default: `('127.0.0.1', '::1')` + +A list of IP addresses recognized as internal to the system, used to control the display of debugging output. For +example, the debugging toolbar will be viewable only when a client is accessing NetBox from one of the listed IP +addresses (and [`DEBUG`](#debug) is true). + +--- + +## JINJA2_FILTERS + +Default: `{}` + +A dictionary of custom jinja2 filters with the key being the filter name and the value being a callable. For more information see the [Jinja2 documentation](https://jinja.palletsprojects.com/en/3.1.x/api/#custom-filters). For example: + +```python +def uppercase(x): + return str(x).upper() + +JINJA2_FILTERS = { + 'uppercase': uppercase, +} +``` + +--- + +## LOGGING + +By default, all messages of INFO severity or higher will be logged to the console. Additionally, if [`DEBUG`](#debug) is False and email access has been configured, ERROR and CRITICAL messages will be emailed to the users defined in [`ADMINS`](#admins). + +The Django framework on which NetBox runs allows for the customization of logging format and destination. Please consult the [Django logging documentation](https://docs.djangoproject.com/en/stable/topics/logging/) for more information on configuring this setting. Below is an example which will write all INFO and higher messages to a local file: + +```python +LOGGING = { + 'version': 1, + 'disable_existing_loggers': False, + 'handlers': { + 'file': { + 'level': 'INFO', + 'class': 'logging.FileHandler', + 'filename': '/var/log/netbox.log', + }, + }, + 'loggers': { + 'django': { + 'handlers': ['file'], + 'level': 'INFO', + }, + }, +} +``` + +### Available Loggers + +* `netbox..` - Generic form for model-specific log messages +* `netbox.auth.*` - Authentication events +* `netbox.api.views.*` - Views which handle business logic for the REST API +* `netbox.reports.*` - Report execution (`module.name`) +* `netbox.scripts.*` - Custom script execution (`module.name`) +* `netbox.views.*` - Views which handle business logic for the web UI + +--- + +## MEDIA_ROOT + +Default: $INSTALL_ROOT/netbox/media/ + +The file path to the location where media files (such as image attachments) are stored. By default, this is the `netbox/media/` directory within the base NetBox installation path. + +--- + +## REPORTS_ROOT + +Default: `$INSTALL_ROOT/netbox/reports/` + +The file path to the location where [custom reports](../customization/reports.md) will be kept. By default, this is the `netbox/reports/` directory within the base NetBox installation path. + +--- + +## SCRIPTS_ROOT + +Default: `$INSTALL_ROOT/netbox/scripts/` + +The file path to the location where [custom scripts](../customization/custom-scripts.md) will be kept. By default, this is the `netbox/scripts/` directory within the base NetBox installation path. + +--- + +## STORAGE_BACKEND + +Default: None (local storage) + +The backend storage engine for handling uploaded files (e.g. image attachments). NetBox supports integration with the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) package, which provides backends for several popular file storage services. If not configured, local filesystem storage will be used. + +The configuration parameters for the specified storage backend are defined under the `STORAGE_CONFIG` setting. + +--- + +## STORAGE_CONFIG + +Default: Empty + +A dictionary of configuration parameters for the storage backend configured as `STORAGE_BACKEND`. The specific parameters to be used here are specific to each backend; see the [`django-storages` documentation](https://django-storages.readthedocs.io/en/stable/) for more detail. + +If `STORAGE_BACKEND` is not defined, this setting will be ignored. + +--- diff --git a/docs/customization/custom-validation.md b/docs/customization/custom-validation.md index f88cd309b..30198117f 100644 --- a/docs/customization/custom-validation.md +++ b/docs/customization/custom-validation.md @@ -50,7 +50,7 @@ The `fail()` method may optionally specify a field with which to associate the s ## Assigning Custom Validators -Custom validators are associated with specific NetBox models under the [CUSTOM_VALIDATORS](../configuration/dynamic-settings.md#custom_validators) configuration parameter. There are three manners by which custom validation rules can be defined: +Custom validators are associated with specific NetBox models under the [CUSTOM_VALIDATORS](../configuration/data-validation.md#custom_validators) configuration parameter. There are three manners by which custom validation rules can be defined: 1. Plain JSON mapping (no custom logic) 2. Dotted path to a custom validator class diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index affd39aae..3c7ff7d20 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -2,7 +2,7 @@ ## REST API Integration -When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../configuration/optional-settings.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: +When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: ``` GET /api/dcim/sites/?export=MyTemplateName diff --git a/docs/customization/reports.md b/docs/customization/reports.md index ae4ceb9aa..150c32f40 100644 --- a/docs/customization/reports.md +++ b/docs/customization/reports.md @@ -12,7 +12,7 @@ A NetBox report is a mechanism for validating the integrity of data within NetBo ## Writing Reports -Reports must be saved as files in the [`REPORTS_ROOT`](../configuration/optional-settings.md#reports_root) path (which defaults to `netbox/reports/`). Each file created within this path is considered a separate module. Each module holds one or more reports (Python classes), each of which performs a certain function. The logic of each report is broken into discrete test methods, each of which applies a small portion of the logic comprising the overall test. +Reports must be saved as files in the [`REPORTS_ROOT`](../configuration/system.md#reports_root) path (which defaults to `netbox/reports/`). Each file created within this path is considered a separate module. Each module holds one or more reports (Python classes), each of which performs a certain function. The logic of each report is broken into discrete test methods, each of which applies a small portion of the logic comprising the overall test. !!! warning The reports path includes a file named `__init__.py`, which registers the path as a Python module. Do not delete this file. diff --git a/docs/graphql-api/overview.md b/docs/graphql-api/overview.md index 57dfb22bd..4fc6d2dd8 100644 --- a/docs/graphql-api/overview.md +++ b/docs/graphql-api/overview.md @@ -67,4 +67,4 @@ Authorization: Token $TOKEN ## Disabling the GraphQL API -If not needed, the GraphQL API can be disabled by setting the [`GRAPHQL_ENABLED`](../configuration/dynamic-settings.md#graphql_enabled) configuration parameter to False and restarting NetBox. +If not needed, the GraphQL API can be disabled by setting the [`GRAPHQL_ENABLED`](../configuration/miscellaneous.md#graphql_enabled) configuration parameter to False and restarting NetBox. diff --git a/docs/installation/3-netbox.md b/docs/installation/3-netbox.md index 50b350d3a..7c4a60500 100644 --- a/docs/installation/3-netbox.md +++ b/docs/installation/3-netbox.md @@ -142,7 +142,7 @@ ALLOWED_HOSTS = ['*'] ### DATABASE -This parameter holds the database configuration details. You must define the username and password used when you configured PostgreSQL. If the service is running on a remote host, update the `HOST` and `PORT` parameters accordingly. See the [configuration documentation](../configuration/required-settings.md#database) for more detail on individual parameters. +This parameter holds the database configuration details. You must define the username and password used when you configured PostgreSQL. If the service is running on a remote host, update the `HOST` and `PORT` parameters accordingly. See the [configuration documentation](../configuration/required-parameters.md#database) for more detail on individual parameters. ```python DATABASE = { @@ -157,7 +157,7 @@ DATABASE = { ### REDIS -Redis is a in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. See the [configuration documentation](../configuration/required-settings.md#redis) for more detail on individual parameters. +Redis is a in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. See the [configuration documentation](../configuration/required-parameters.md#redis) for more detail on individual parameters. Note that NetBox requires the specification of two separate Redis databases: `tasks` and `caching`. These may both be provided by the same Redis service, however each should have a unique numeric database ID. @@ -209,7 +209,7 @@ sudo sh -c "echo 'napalm' >> /opt/netbox/local_requirements.txt" ### Remote File Storage -By default, NetBox will use the local filesystem to store uploaded files. To use a remote filesystem, install the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) library and configure your [desired storage backend](../configuration/optional-settings.md#storage_backend) in `configuration.py`. +By default, NetBox will use the local filesystem to store uploaded files. To use a remote filesystem, install the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) library and configure your [desired storage backend](../configuration/system.md#storage_backend) in `configuration.py`. ```no-highlight sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt" diff --git a/docs/installation/6-ldap.md b/docs/installation/6-ldap.md index 281554f75..163ace70d 100644 --- a/docs/installation/6-ldap.md +++ b/docs/installation/6-ldap.md @@ -142,7 +142,7 @@ AUTH_LDAP_CACHE_TIMEOUT = 3600 `systemctl restart netbox` restarts the NetBox service, and initiates any changes made to `ldap_config.py`. If there are syntax errors present, the NetBox process will not spawn an instance, and errors should be logged to `/var/log/messages`. -For troubleshooting LDAP user/group queries, add or merge the following [logging](../configuration/optional-settings.md#logging) configuration to `configuration.py`: +For troubleshooting LDAP user/group queries, add or merge the following [logging](../configuration/system.md#logging) configuration to `configuration.py`: ```python LOGGING = { diff --git a/docs/plugins/development/models.md b/docs/plugins/development/models.md index 6d7075b80..c58621b81 100644 --- a/docs/plugins/development/models.md +++ b/docs/plugins/development/models.md @@ -156,7 +156,7 @@ class StatusChoices(ChoiceSet): key = 'MyModel.status' ``` -To extend or replace the default values for this choice set, a NetBox administrator can then reference it under the [`FIELD_CHOICES`](../../configuration/optional-settings.md#field_choices) configuration parameter. For example, the `status` field on `MyModel` in `my_plugin` would be referenced as: +To extend or replace the default values for this choice set, a NetBox administrator can then reference it under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. For example, the `status` field on `MyModel` in `my_plugin` would be referenced as: ```python FIELD_CHOICES = { diff --git a/docs/release-notes/version-3.0.md b/docs/release-notes/version-3.0.md index 7d6341f44..93ff33d95 100644 --- a/docs/release-notes/version-3.0.md +++ b/docs/release-notes/version-3.0.md @@ -367,7 +367,7 @@ More information about IP ranges is available [in the documentation](../models/i #### Custom Model Validation ([#5963](https://github.com/netbox-community/netbox/issues/5963)) -This release introduces the [`CUSTOM_VALIDATORS`](../configuration/dynamic-settings.md#custom_validators) configuration parameter, which allows administrators to map NetBox models to custom validator classes to enforce custom validation logic. For example, the following configuration requires every site to have a name of at least ten characters and a description: +This release introduces the [`CUSTOM_VALIDATORS`](../configuration/data-validation.md#custom_validators) configuration parameter, which allows administrators to map NetBox models to custom validator classes to enforce custom validation logic. For example, the following configuration requires every site to have a name of at least ten characters and a description: ```python from extras.validators import CustomValidator diff --git a/docs/release-notes/version-3.1.md b/docs/release-notes/version-3.1.md index 27ba4e69e..9dce1dfd4 100644 --- a/docs/release-notes/version-3.1.md +++ b/docs/release-notes/version-3.1.md @@ -313,8 +313,6 @@ Some parameters of NetBox's configuration are now accessible via the admin UI. T Dynamic configuration parameters may also still be defined within `configuration.py`, and the settings defined here take precedence over those defined via the user interface. -For a complete list of supported parameters, please see the [dynamic configuration documentation](../configuration/dynamic-settings.md). - #### First Hop Redundancy Protocol (FHRP) Groups ([#6235](https://github.com/netbox-community/netbox/issues/6235)) A new FHRP group model has been introduced to aid in modeling the configurations of protocols such as HSRP, VRRP, and GLBP. Each FHRP group may be assigned one or more virtual IP addresses, as well as an authentication type and key. Member device and VM interfaces may be associated with one or more FHRP groups, with each assignment receiving a numeric priority designation. diff --git a/docs/release-notes/version-3.2.md b/docs/release-notes/version-3.2.md index c36344912..10ccaeb4d 100644 --- a/docs/release-notes/version-3.2.md +++ b/docs/release-notes/version-3.2.md @@ -267,7 +267,7 @@ Custom field object assignment is fully supported in the REST API, and functions #### Custom Status Choices ([#8054](https://github.com/netbox-community/netbox/issues/8054)) -Custom choices can be now added to most object status fields in NetBox. This is done by defining the [`FIELD_CHOICES`](../configuration/optional-settings.md#field_choices) configuration parameter to map field identifiers to an iterable of custom choices an (optionally) colors. These choices are populated automatically when NetBox initializes. For example, the following configuration will add three custom choices for the site status field, each with a designated color: +Custom choices can be now added to most object status fields in NetBox. This is done by defining the [`FIELD_CHOICES`](../configuration/data-validation.md#field_choices) configuration parameter to map field identifiers to an iterable of custom choices an (optionally) colors. These choices are populated automatically when NetBox initializes. For example, the following configuration will add three custom choices for the site status field, each with a designated color: ```python FIELD_CHOICES = { @@ -291,7 +291,7 @@ FIELD_CHOICES = { #### Improved User Preferences ([#7759](https://github.com/netbox-community/netbox/issues/7759)) -A robust new mechanism for managing user preferences is included in this release. The user preferences form has been improved for better usability, and administrators can now define default preferences for all users with the [`DEFAULT_USER_PREFERENCES`](../configuration/dynamic-settings.md##default_user_preferences) configuration parameter. For example, this can be used to define the columns which appear by default in a table: +A robust new mechanism for managing user preferences is included in this release. The user preferences form has been improved for better usability, and administrators can now define default preferences for all users with the [`DEFAULT_USER_PREFERENCES`](../configuration/default-values.md#default_user_preferences) configuration parameter. For example, this can be used to define the columns which appear by default in a table: ```python DEFAULT_USER_PREFERENCES = { diff --git a/docs/rest-api/authentication.md b/docs/rest-api/authentication.md index 18b6bc4f8..411063338 100644 --- a/docs/rest-api/authentication.md +++ b/docs/rest-api/authentication.md @@ -20,7 +20,7 @@ https://netbox/api/dcim/sites/ } ``` -A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/optional-settings.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response: +A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/security.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response: ``` $ curl https://netbox/api/dcim/sites/ diff --git a/docs/rest-api/overview.md b/docs/rest-api/overview.md index 27a9b6a7e..5fc4f18bb 100644 --- a/docs/rest-api/overview.md +++ b/docs/rest-api/overview.md @@ -308,7 +308,7 @@ Vary: Accept } ``` -The default page is determined by the [`PAGINATE_COUNT`](../configuration/dynamic-settings.md#paginate_count) configuration parameter, which defaults to 50. However, this can be overridden per request by specifying the desired `offset` and `limit` query parameters. For example, if you wish to retrieve a hundred devices at a time, you would make a request for: +The default page is determined by the [`PAGINATE_COUNT`](../configuration/default-values.md#paginate_count) configuration parameter, which defaults to 50. However, this can be overridden per request by specifying the desired `offset` and `limit` query parameters. For example, if you wish to retrieve a hundred devices at a time, you would make a request for: ``` http://netbox/api/dcim/devices/?limit=100 @@ -325,7 +325,7 @@ The response will return devices 1 through 100. The URL provided in the `next` a } ``` -The maximum number of objects that can be returned is limited by the [`MAX_PAGE_SIZE`](../configuration/dynamic-settings.md#max_page_size) configuration parameter, which is 1000 by default. Setting this to `0` or `None` will remove the maximum limit. An API consumer can then pass `?limit=0` to retrieve _all_ matching objects with a single request. +The maximum number of objects that can be returned is limited by the [`MAX_PAGE_SIZE`](../configuration/miscellaneous.md#max_page_size) configuration parameter, which is 1000 by default. Setting this to `0` or `None` will remove the maximum limit. An API consumer can then pass `?limit=0` to retrieve _all_ matching objects with a single request. !!! warning Disabling the page size limit introduces a potential for very resource-intensive requests, since one API request can effectively retrieve an entire table from the database. diff --git a/mkdocs.yml b/mkdocs.yml index 2203b8934..3acb157aa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,11 +72,18 @@ nav: - Populating Data: 'getting-started/populating-data.md' - Configuration: - Configuring NetBox: 'configuration/index.md' - - Required Settings: 'configuration/required-settings.md' - - Optional Settings: 'configuration/optional-settings.md' - - Dynamic Settings: 'configuration/dynamic-settings.md' - - Error Reporting: 'configuration/error-reporting.md' + - Required Parameters: 'configuration/required-parameters.md' + - System: 'configuration/system.md' + - Security: 'configuration/security.md' - Remote Authentication: 'configuration/remote-authentication.md' + - Data & Validation: 'configuration/data-validation.md' + - Default Values: 'configuration/default-values.md' + - Error Reporting: 'configuration/error-reporting.md' + - Plugins: 'configuration/plugins.md' + - NAPALM: 'configuration/napalm.md' + - Date & Time: 'configuration/date-time.md' + - Miscellaneous: 'configuration/miscellaneous.md' + - Development: 'configuration/development.md' - Customization: - Custom Fields: 'customization/custom-fields.md' - Custom Validation: 'customization/custom-validation.md' From 1cd407548813bc959f4959f7009b3d800fe71311 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 16:23:45 -0400 Subject: [PATCH 05/28] Add mermaid flowcharts showing rough data model dependencies --- docs/getting-started/planning.md | 116 ++++++++++++++++++++++--------- mkdocs.yml | 6 +- 2 files changed, 87 insertions(+), 35 deletions(-) diff --git a/docs/getting-started/planning.md b/docs/getting-started/planning.md index 00640ca44..5c431a4d2 100644 --- a/docs/getting-started/planning.md +++ b/docs/getting-started/planning.md @@ -50,38 +50,86 @@ When starting with a completely empty database, it might not be immediately clea Below is the (rough) recommended order in which NetBox objects should be created or imported. While it is not required to follow this exact order, doing so will help ensure the smoothest workflow. - +1. Tenant groups and tenants +2. Regions, site groups, sites, and locations +3. Rack roles and racks +4. Manufacturers, device types, and module types +5. Platforms and device roles +6. Devices and modules +7. Providers and provider networks +8. Circuit types and circuits +9. Wireless LAN groups and wireless LANs +10. Route targets and VRFs +11. RIRs and aggregates +12. IP/VLAN roles +13. Prefixes, IP ranges, and IP addresses +14. VLAN groups and VLANs +15. Cluster types, cluster groups, and clusters +16. Virtual machines and VM interfaces -1. Tenant groups -2. Tenants -3. Regions and/or site groups -4. Sites -5. Locations -6. Rack roles -7. Racks -8. Platforms -9. Manufacturers -10. Device types -11. Module types -12. Device roles -13. Devices -14. Providers -15. Provider networks -16. Circuit types -17. Circuits -18. Wireless LAN groups -19. Wireless LANs & links -20. Route targets -21. VRFs -22. RIRs -23. Aggregates -24. IP/VLAN roles -25. Prefixes -26. IP ranges & addresses -27. VLAN groups -28. VLANs -29. Services -30. Clusters -31. Virtual machines -32. VM interfaces -33. L2 VPNs +This is not a comprehensive list, but should suffice for the initial data imports. Beyond these, it the order in which objects are added doesn't have much if any impact. + +The graphs below illustrate some of the core dependencies among different models in NetBox for your reference. + +!!! note "Self-Nesting Models" + Each model in the graphs below which show a looping arrow pointing back to itself can be nested in a recursive hierarchy. For example, you can have regions representing both countries and cities, with the latter nested underneath the former. + +### Tenancy + +```mermaid +flowchart TD + TenantGroup --> TenantGroup + TenantGroup --> Tenant + Tenant --> Site & Device & Prefix & VLAN & ... +``` + +### Sites, Racks, and Devices + +```mermaid +flowchart TD + Region --> Region + SiteGroup --> SiteGroup + DeviceRole & Platform --> Device + Region & SiteGroup --> Site + Site --> Location & Device + Location --> Location + Location --> Rack & Device + Rack --> Device + Manufacturer --> DeviceType & ModuleType + DeviceType --> Device + Device & ModuleType ---> Module + Device & Module --> Interface +``` + +### VRFs, Prefixes, IP Addresses, and VLANs + +```mermaid +flowchart TD + VLANGroup --> VLAN + Role --> VLAN & IPRange & Prefix + RIR --> Aggregate + RouteTarget --> VRF + Aggregate & VRF --> Prefix + VRF --> IPRange & IPAddress + Prefix --> VLAN & IPRange & IPAddress +``` + +### Circuits + +```mermaid +flowchart TD + Provider & CircuitType --> Circuit + Provider --> ProviderNetwork + Circuit --> CircuitTermination +``` + +### Clusters and Virtual Machines + +```mermaid +flowchart TD + ClusterGroup & ClusterType --> Cluster + Cluster --> VirtualMachine + Site --> Cluster & VirtualMachine + Device & Platform --> VirtualMachine + VirtualMachine --> VMInterface +``` diff --git a/mkdocs.yml b/mkdocs.yml index 3acb157aa..4c5279127 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,7 +53,11 @@ markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true nav: From 5da3cab4de0469c8e8f19726600286abc590c7c3 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 4 Aug 2022 14:11:52 -0400 Subject: [PATCH 06/28] Reorganize documentation --- docs/additional-features/webhooks.md | 57 ----------- docs/administration/permissions.md | 71 ++++++++++++- docs/configuration/miscellaneous.md | 2 +- docs/configuration/napalm.md | 2 +- docs/customization/custom-fields.md | 75 +++++++++++++- .../custom-links.md} | 0 docs/customization/export-templates.md | 39 +++++++- docs/development/models.md | 8 +- .../change-logging.md | 0 docs/features/circuits.md | 3 + docs/features/contacts.md | 3 + .../context-data.md} | 0 docs/features/customization.md | 3 + docs/features/devices-cabling.md | 3 + docs/features/facilities.md | 3 + docs/features/ipam.md | 3 + .../journaling.md | 0 docs/features/l2vpn-overlay.md | 3 + docs/features/permissions.md | 3 + docs/features/power-tracking.md | 3 + docs/features/services.md | 3 + docs/features/sso.md | 3 + .../extras/tag.md => features/tags.md} | 0 docs/features/tenancy.md | 3 + docs/features/vlan-management.md | 3 + .../webhook.md => features/webhooks.md} | 56 +++++++++++ docs/features/wireless.md | 3 + docs/getting-started/populating-data.md | 2 +- docs/installation/3-netbox.md | 2 +- .../graphql-api.md} | 0 .../napalm.md | 0 .../prometheus-metrics.md | 0 .../overview.md => integrations/rest-api.md} | 99 ++++++++++++++++++- docs/models/extras/customfield.md | 73 -------------- docs/models/extras/exporttemplate.md | 37 ------- docs/models/extras/imageattachment.md | 3 - docs/models/users/objectpermission.md | 69 ------------- docs/models/users/token.md | 19 ---- docs/{rest-api => reference}/filtering.md | 0 docs/release-notes/version-3.0.md | 2 +- docs/rest-api/authentication.md | 73 -------------- mkdocs.yml | 47 +++++---- 42 files changed, 412 insertions(+), 366 deletions(-) delete mode 100644 docs/additional-features/webhooks.md rename docs/{models/extras/customlink.md => customization/custom-links.md} (100%) rename docs/{additional-features => features}/change-logging.md (100%) create mode 100644 docs/features/circuits.md create mode 100644 docs/features/contacts.md rename docs/{models/extras/configcontext.md => features/context-data.md} (100%) create mode 100644 docs/features/customization.md create mode 100644 docs/features/devices-cabling.md create mode 100644 docs/features/facilities.md create mode 100644 docs/features/ipam.md rename docs/{additional-features => features}/journaling.md (100%) create mode 100644 docs/features/l2vpn-overlay.md create mode 100644 docs/features/permissions.md create mode 100644 docs/features/power-tracking.md create mode 100644 docs/features/services.md create mode 100644 docs/features/sso.md rename docs/{models/extras/tag.md => features/tags.md} (100%) create mode 100644 docs/features/tenancy.md create mode 100644 docs/features/vlan-management.md rename docs/{models/extras/webhook.md => features/webhooks.md} (67%) create mode 100644 docs/features/wireless.md rename docs/{graphql-api/overview.md => integrations/graphql-api.md} (100%) rename docs/{additional-features => integrations}/napalm.md (100%) rename docs/{additional-features => integrations}/prometheus-metrics.md (100%) rename docs/{rest-api/overview.md => integrations/rest-api.md} (78%) delete mode 100644 docs/models/extras/customfield.md delete mode 100644 docs/models/extras/exporttemplate.md delete mode 100644 docs/models/extras/imageattachment.md delete mode 100644 docs/models/users/objectpermission.md delete mode 100644 docs/models/users/token.md rename docs/{rest-api => reference}/filtering.md (100%) delete mode 100644 docs/rest-api/authentication.md diff --git a/docs/additional-features/webhooks.md b/docs/additional-features/webhooks.md deleted file mode 100644 index 5077f3a68..000000000 --- a/docs/additional-features/webhooks.md +++ /dev/null @@ -1,57 +0,0 @@ -{!models/extras/webhook.md!} - -## Conditional Webhooks - -A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": - -```json -{ - "and": [ - { - "attr": "status.value", - "value": "active" - } - ] -} -``` - -For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md). - -## Webhook Processing - -When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. - -A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. - -## Troubleshooting - -To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: - -```no-highlight -$ python netbox/manage.py webhook_receiver -Listening on port http://localhost:9000. Stop with CONTROL-C. -``` - -You can test the receiver itself by sending any HTTP request to it. For example: - -```no-highlight -$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' -``` - -The server will print output similar to the following: - -```no-highlight -[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - -Host: localhost:9000 -User-Agent: curl/7.58.0 -Accept: */* -Content-Length: 14 -Content-Type: application/x-www-form-urlencoded - -{"foo": "bar"} ------------- -``` - -Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. - -Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/docs/administration/permissions.md b/docs/administration/permissions.md index 60717c28a..21f259979 100644 --- a/docs/administration/permissions.md +++ b/docs/administration/permissions.md @@ -1,8 +1,75 @@ -# Permissions +# Object-Based Permissions NetBox v2.9 introduced a new object-based permissions framework, which replaces Django's built-in permissions model. Object-based permissions enable an administrator to grant users or groups the ability to perform an action on arbitrary subsets of objects in NetBox, rather than all objects of a certain type. For example, it is possible to grant a user permission to view only sites within a particular region, or to modify only VLANs with a numeric ID within a certain range. -{!models/users/objectpermission.md!} +A permission in NetBox represents a relationship shared by several components: + +* Object type(s) - One or more types of object in NetBox +* User(s)/Group(s) - One or more users or groups of users +* Action(s) - The action(s) that can be performed on an object +* Constraints - An arbitrary filter used to limit the granted action(s) to a specific subset of objects + +At a minimum, a permission assignment must specify one object type, one user or group, and one action. The specification of constraints is optional: A permission without any constraints specified will apply to all instances of the selected model(s). + +## Actions + +There are four core actions that can be permitted for each type of object within NetBox, roughly analogous to the CRUD convention (create, read, update, and delete): + +* **View** - Retrieve an object from the database +* **Add** - Create a new object +* **Change** - Modify an existing object +* **Delete** - Delete an existing object + +In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `napalm_read` permission on the device model allows a user to execute NAPALM queries on a device via NetBox's REST API. These can be specified when granting a permission in the "additional actions" field. + +!!! note + Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named `actions`. + +## Constraints + +Constraints are expressed as a JSON object or list representing a [Django query filter](https://docs.djangoproject.com/en/stable/ref/models/querysets/#field-lookups). This is the same syntax that you would pass to the QuerySet `filter()` method when performing a query using the Django ORM. As with query filters, double underscores can be used to traverse related objects or invoke lookup expressions. Some example queries and their corresponding definitions are shown below. + +All attributes defined within a single JSON object are applied with a logical AND. For example, suppose you assign a permission for the site model with the following constraints. + +```json +{ + "status": "active", + "region__name": "Americas" +} +``` + +The permission will grant access only to sites which have a status of "active" **and** which are assigned to the "Americas" region. + +To achieve a logical OR with a different set of constraints, define multiple objects within a list. For example, if you want to constrain the permission to VLANs with an ID between 100 and 199 _or_ a status of "reserved," do the following: + +```json +[ + { + "vid__gte": 100, + "vid__lt": 200 + }, + { + "status": "reserved" + } +] +``` + +Additionally, where multiple permissions have been assigned for an object type, their collective constraints will be merged using a logical "OR" operation. + +### User Token + +!!! info "This feature was introduced in NetBox v3.3" + +When defining a permission constraint, administrators may use the special token `$user` to reference the current user at the time of evaluation. This can be helpful to restrict users to editing only their own journal entries, for example. Such a constraint might be defined as: + +```json +{ + "created_by": "$user" +} +``` + +The `$user` token can be used only as a constraint value, or as an item within a list of values. It cannot be modified or extended to reference specific user attributes. + #### Example Constraint Definitions diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md index 2aa21b7e5..614e90eac 100644 --- a/docs/configuration/miscellaneous.md +++ b/docs/configuration/miscellaneous.md @@ -127,7 +127,7 @@ A web user or API consumer can request an arbitrary number of objects by appendi Default: False -Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../additional-features/prometheus-metrics.md) documentation for more details. +Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../integrations/prometheus-metrics.md) documentation for more details. --- diff --git a/docs/configuration/napalm.md b/docs/configuration/napalm.md index 925ec17e6..253bea297 100644 --- a/docs/configuration/napalm.md +++ b/docs/configuration/napalm.md @@ -6,7 +6,7 @@ !!! tip "Dynamic Configuration Parameter" -NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional. +NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../integrations/napalm.md), if installed. Both parameters are optional. !!! note If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed. diff --git a/docs/customization/custom-fields.md b/docs/customization/custom-fields.md index 757416626..bfe412edc 100644 --- a/docs/customization/custom-fields.md +++ b/docs/customization/custom-fields.md @@ -1,4 +1,77 @@ -{!models/extras/customfield.md!} +# Custom Fields + +Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. + +However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. + +Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. + +## Creating Custom Fields + +Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: + +* Text: Free-form text (intended for single-line use) +* Long text: Free-form of any length; supports Markdown rendering +* Integer: A whole number (positive or negative) +* Boolean: True or false +* Date: A date in ISO 8601 format (YYYY-MM-DD) +* URL: This will be presented as a link in the web UI +* JSON: Arbitrary data stored in JSON format +* Selection: A selection of one of several pre-defined custom choices +* Multiple selection: A selection field which supports the assignment of multiple values +* Object: A single NetBox object of the type defined by `object_type` +* Multiple object: One or more NetBox objects of the type defined by `object_type` + +Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. + +Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. + +A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. + +### Filtering + +The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. + +### Grouping + +!!! note + This feature was introduced in NetBox v3.3. + +Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) + +This parameter has no effect on the API representation of custom field data. + +### Visibility + +!!! note + This feature was introduced in NetBox v3.3. + +When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. + +* **Read/write** (default): The custom field is included when viewing and editing objects. +* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. + +Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. + +### Validation + +NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: + +* Text: Regular expression (optional) +* Integer: Minimum and/or maximum value (optional) +* Selection: Must exactly match one of the prescribed choices + +### Custom Selection Fields + +Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. + +If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. + +### Custom Object Fields + +An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. + ## Custom Fields in Templates diff --git a/docs/models/extras/customlink.md b/docs/customization/custom-links.md similarity index 100% rename from docs/models/extras/customlink.md rename to docs/customization/custom-links.md diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index 3c7ff7d20..640a97531 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -1,4 +1,41 @@ -{!models/extras/exporttemplate.md!} +# Export Templates + +NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. + +Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. + +Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). + +!!! note + The name `table` is reserved for internal use. + +!!! warning + Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. + +The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: + +```jinja2 +{% for rack in queryset %} +Rack: {{ rack.name }} +Site: {{ rack.site.name }} +Height: {{ rack.u_height }}U +{% endfor %} +``` + +To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. + +If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: +``` +{% for server in queryset %} +{% set data = server.get_config_context() %} +{{ data.syslog }} +{% endfor %} +``` + +The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) + +A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. + ## REST API Integration diff --git a/docs/development/models.md b/docs/development/models.md index b6b2e4da2..be3608a30 100644 --- a/docs/development/models.md +++ b/docs/development/models.md @@ -8,12 +8,12 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/ ### Features Matrix -* [Change logging](../additional-features/change-logging.md) - Changes to these objects are automatically recorded in the change log -* [Webhooks](../additional-features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects +* [Change logging](../features/change-logging.md) - Changes to these objects are automatically recorded in the change log +* [Webhooks](../features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects * [Custom fields](../customization/custom-fields.md) - These models support the addition of user-defined fields * [Export templates](../customization/export-templates.md) - Users can create custom export templates for these models -* [Tagging](../models/extras/tag.md) - The models can be tagged with user-defined tags -* [Journaling](../additional-features/journaling.md) - These models support persistent historical commentary +* [Tagging](../features/tags.md) - The models can be tagged with user-defined tags +* [Journaling](../features/journaling.md) - These models support persistent historical commentary * Nesting - These models can be nested recursively to create a hierarchy | Type | Change Logging | Webhooks | Custom Fields | Export Templates | Tags | Journaling | Nesting | diff --git a/docs/additional-features/change-logging.md b/docs/features/change-logging.md similarity index 100% rename from docs/additional-features/change-logging.md rename to docs/features/change-logging.md diff --git a/docs/features/circuits.md b/docs/features/circuits.md new file mode 100644 index 000000000..63c8bc970 --- /dev/null +++ b/docs/features/circuits.md @@ -0,0 +1,3 @@ +# Circuits + +TODO diff --git a/docs/features/contacts.md b/docs/features/contacts.md new file mode 100644 index 000000000..fb23e53da --- /dev/null +++ b/docs/features/contacts.md @@ -0,0 +1,3 @@ +# Contacts + +TODO diff --git a/docs/models/extras/configcontext.md b/docs/features/context-data.md similarity index 100% rename from docs/models/extras/configcontext.md rename to docs/features/context-data.md diff --git a/docs/features/customization.md b/docs/features/customization.md new file mode 100644 index 000000000..ae775312e --- /dev/null +++ b/docs/features/customization.md @@ -0,0 +1,3 @@ +# Customization + +TODO diff --git a/docs/features/devices-cabling.md b/docs/features/devices-cabling.md new file mode 100644 index 000000000..ab09b4443 --- /dev/null +++ b/docs/features/devices-cabling.md @@ -0,0 +1,3 @@ +# Devices & Cabling + +TODO diff --git a/docs/features/facilities.md b/docs/features/facilities.md new file mode 100644 index 000000000..5ace5b18b --- /dev/null +++ b/docs/features/facilities.md @@ -0,0 +1,3 @@ +# Facilities + +TODO \ No newline at end of file diff --git a/docs/features/ipam.md b/docs/features/ipam.md new file mode 100644 index 000000000..f263f3ab3 --- /dev/null +++ b/docs/features/ipam.md @@ -0,0 +1,3 @@ +# IP Address Management + +TODO diff --git a/docs/additional-features/journaling.md b/docs/features/journaling.md similarity index 100% rename from docs/additional-features/journaling.md rename to docs/features/journaling.md diff --git a/docs/features/l2vpn-overlay.md b/docs/features/l2vpn-overlay.md new file mode 100644 index 000000000..002c483f9 --- /dev/null +++ b/docs/features/l2vpn-overlay.md @@ -0,0 +1,3 @@ +# L2VPN & Overlay + +TODO diff --git a/docs/features/permissions.md b/docs/features/permissions.md new file mode 100644 index 000000000..a422ca7b3 --- /dev/null +++ b/docs/features/permissions.md @@ -0,0 +1,3 @@ +# Object-Based Permissions + +TODO diff --git a/docs/features/power-tracking.md b/docs/features/power-tracking.md new file mode 100644 index 000000000..1267af1e6 --- /dev/null +++ b/docs/features/power-tracking.md @@ -0,0 +1,3 @@ +# Power Tracking + +TODO diff --git a/docs/features/services.md b/docs/features/services.md new file mode 100644 index 000000000..338fc349a --- /dev/null +++ b/docs/features/services.md @@ -0,0 +1,3 @@ +# Services + +TODO diff --git a/docs/features/sso.md b/docs/features/sso.md new file mode 100644 index 000000000..b4f9782c2 --- /dev/null +++ b/docs/features/sso.md @@ -0,0 +1,3 @@ +# Single Sign-On (SSO) + +TODO diff --git a/docs/models/extras/tag.md b/docs/features/tags.md similarity index 100% rename from docs/models/extras/tag.md rename to docs/features/tags.md diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md new file mode 100644 index 000000000..20534b13c --- /dev/null +++ b/docs/features/tenancy.md @@ -0,0 +1,3 @@ +# Tenancy + +TODO diff --git a/docs/features/vlan-management.md b/docs/features/vlan-management.md new file mode 100644 index 000000000..3d4fd4d1f --- /dev/null +++ b/docs/features/vlan-management.md @@ -0,0 +1,3 @@ +# VLAN Management + +TODO diff --git a/docs/models/extras/webhook.md b/docs/features/webhooks.md similarity index 67% rename from docs/models/extras/webhook.md rename to docs/features/webhooks.md index 9f64401ae..4705243d1 100644 --- a/docs/models/extras/webhook.md +++ b/docs/features/webhooks.md @@ -81,3 +81,59 @@ If no body template is specified, the request body will be populated with a JSON } } ``` + +## Conditional Webhooks + +A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": + +```json +{ + "and": [ + { + "attr": "status.value", + "value": "active" + } + ] +} +``` + +For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md). + +## Webhook Processing + +When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. + +A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. + +## Troubleshooting + +To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: + +```no-highlight +$ python netbox/manage.py webhook_receiver +Listening on port http://localhost:9000. Stop with CONTROL-C. +``` + +You can test the receiver itself by sending any HTTP request to it. For example: + +```no-highlight +$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' +``` + +The server will print output similar to the following: + +```no-highlight +[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - +Host: localhost:9000 +User-Agent: curl/7.58.0 +Accept: */* +Content-Length: 14 +Content-Type: application/x-www-form-urlencoded + +{"foo": "bar"} +------------ +``` + +Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. + +Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/docs/features/wireless.md b/docs/features/wireless.md new file mode 100644 index 000000000..ff3d5d10b --- /dev/null +++ b/docs/features/wireless.md @@ -0,0 +1,3 @@ +# Wireless + +TODO diff --git a/docs/getting-started/populating-data.md b/docs/getting-started/populating-data.md index e182a9d52..bb0e8e17f 100644 --- a/docs/getting-started/populating-data.md +++ b/docs/getting-started/populating-data.md @@ -39,4 +39,4 @@ Sometimes you'll find that data you need to populate in NetBox can be easily red You can also use the REST API to facilitate the population of data in NetBox. The REST API offers full programmatic control over the creation of objects, subject to the same validation rules enforced by the UI forms. Additionally, the REST API supports the bulk creation of multiple objects using a single request. -For more information about this option, see the [REST API documentation](../rest-api/overview.md). +For more information about this option, see the [REST API documentation](../integrations/rest-api.md). diff --git a/docs/installation/3-netbox.md b/docs/installation/3-netbox.md index 7c4a60500..eeb5e6f20 100644 --- a/docs/installation/3-netbox.md +++ b/docs/installation/3-netbox.md @@ -201,7 +201,7 @@ All Python packages required by NetBox are listed in `requirements.txt` and will ### NAPALM -Integration with the [NAPALM automation](../additional-features/napalm.md) library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The `NAPALM_USERNAME` and `NAPALM_PASSWORD` configuration parameters define the credentials to be used when connecting to a device. +Integration with the [NAPALM automation](../integrations/napalm.md) library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The `NAPALM_USERNAME` and `NAPALM_PASSWORD` configuration parameters define the credentials to be used when connecting to a device. ```no-highlight sudo sh -c "echo 'napalm' >> /opt/netbox/local_requirements.txt" diff --git a/docs/graphql-api/overview.md b/docs/integrations/graphql-api.md similarity index 100% rename from docs/graphql-api/overview.md rename to docs/integrations/graphql-api.md diff --git a/docs/additional-features/napalm.md b/docs/integrations/napalm.md similarity index 100% rename from docs/additional-features/napalm.md rename to docs/integrations/napalm.md diff --git a/docs/additional-features/prometheus-metrics.md b/docs/integrations/prometheus-metrics.md similarity index 100% rename from docs/additional-features/prometheus-metrics.md rename to docs/integrations/prometheus-metrics.md diff --git a/docs/rest-api/overview.md b/docs/integrations/rest-api.md similarity index 78% rename from docs/rest-api/overview.md rename to docs/integrations/rest-api.md index 5fc4f18bb..3a5aed055 100644 --- a/docs/rest-api/overview.md +++ b/docs/integrations/rest-api.md @@ -91,7 +91,7 @@ Lists of objects can be filtered using a set of query parameters. For example, t GET /api/dcim/interfaces/?device_id=123 ``` -See the [filtering documentation](filtering.md) for more details. +See the [filtering documentation](../reference/filtering.md) for more details. ## Serialization @@ -269,7 +269,7 @@ The brief format is supported for both lists and individual objects. ### Excluding Config Contexts -When retrieving devices and virtual machines via the REST API, each will included its rendered [configuration context data](../models/extras/configcontext.md) by default. Users with large amounts of context data will likely observe suboptimal performance when returning multiple objects, particularly with very high page sizes. To combat this, context data may be excluded from the response data by attaching the query parameter `?exclude=config_context` to the request. This parameter works for both list and detail views. +When retrieving devices and virtual machines via the REST API, each will include its rendered [configuration context data](../features/context-data.md) by default. Users with large amounts of context data will likely observe suboptimal performance when returning multiple objects, particularly with very high page sizes. To combat this, context data may be excluded from the response data by attaching the query parameter `?exclude=config_context` to the request. This parameter works for both list and detail views. ## Pagination @@ -387,7 +387,7 @@ curl -s -X GET http://netbox/api/ipam/ip-addresses/5618/ | jq '.' ### Creating a New Object -To create a new object, make a `POST` request to the model's _list_ endpoint with JSON data pertaining to the object being created. Note that a REST API token is required for all write operations; see the [authentication documentation](authentication.md) for more information. Also be sure to set the `Content-Type` HTTP header to `application/json`. +To create a new object, make a `POST` request to the model's _list_ endpoint with JSON data pertaining to the object being created. Note that a REST API token is required for all write operations; see the [authentication section](#authenticating-to-the-api) for more information. Also be sure to set the `Content-Type` HTTP header to `application/json`. ```no-highlight curl -s -X POST \ @@ -561,3 +561,96 @@ http://netbox/api/dcim/sites/ \ !!! note The bulk deletion of objects is an all-or-none operation, meaning that if NetBox fails to delete any of the specified objects (e.g. due a dependency by a related object), the entire operation will be aborted and none of the objects will be deleted. + +## Authentication + +The NetBox REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browsable API. + +### Tokens + +A token is a unique identifier mapped to a NetBox user account. Each user may have one or more tokens which he or she can use for authentication when making REST API requests. To create a token, navigate to the API tokens page under your user profile. + +!!! note + All users can create and manage REST API tokens under the user control panel in the UI. The ability to view, add, change, or delete tokens via the REST API itself is controlled by the relevant model permissions, assigned to users and/or groups in the admin UI. These permissions should be used with great care to avoid accidentally permitting a user to create tokens for other user accounts. + +Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, NetBox allows you to specify a key in case you need to restore a previously deleted token to operation. + +By default, a token can be used to perform all actions via the API that a user would be permitted to do via the web UI. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only. + +Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox. + +#### Client IP Restriction + +!!! note + This feature was introduced in NetBox v3.3. + +Each API token can optionally be restricted by client IP address. If one or more allowed IP prefixes/addresses is defined for a token, authentication will fail for any client connecting from an IP address outside the defined range(s). This enables restricting the use a token to a specific client. (By default, any client IP address is permitted.) + + +### Authenticating to the API + +An authentication token is attached to a request by setting the `Authorization` header to the string `Token` followed by a space and the user's token: + +``` +$ curl -H "Authorization: Token $TOKEN" \ +-H "Accept: application/json; indent=4" \ +https://netbox/api/dcim/sites/ +{ + "count": 10, + "next": null, + "previous": null, + "results": [...] +} +``` + +A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/security.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response: + +``` +$ curl https://netbox/api/dcim/sites/ +{ + "detail": "Authentication credentials were not provided." +} +``` + +When a token is used to authenticate a request, its `last_updated` time updated to the current time if its last use was recorded more than 60 seconds ago (or was never recorded). This allows users to determine which tokens have been active recently. + +!!! note + The "last used" time for tokens will not be updated while maintenance mode is enabled. + +### Initial Token Provisioning + +Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. NetBox provides a special endpoint to provision tokens using a valid username and password combination. + +To provision a token via the REST API, make a `POST` request to the `/api/users/tokens/provision/` endpoint: + +``` +$ curl -X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json; indent=4" \ +https://netbox/api/users/tokens/provision/ \ +--data '{ + "username": "hankhill", + "password": "I<3C3H8", +}' +``` + +Note that we are _not_ passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled. + +```json +{ + "id": 6, + "url": "https://netbox/api/users/tokens/6/", + "display": "3c9cb9 (hankhill)", + "user": { + "id": 2, + "url": "https://netbox/api/users/users/2/", + "display": "hankhill", + "username": "hankhill" + }, + "created": "2021-06-11T20:09:13.339367Z", + "expires": null, + "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9", + "write_enabled": true, + "description": "" +} +``` diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md deleted file mode 100644 index 3f6860758..000000000 --- a/docs/models/extras/customfield.md +++ /dev/null @@ -1,73 +0,0 @@ -# Custom Fields - -Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. - -However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. - -Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. - -## Creating Custom Fields - -Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: - -* Text: Free-form text (intended for single-line use) -* Long text: Free-form of any length; supports Markdown rendering -* Integer: A whole number (positive or negative) -* Boolean: True or false -* Date: A date in ISO 8601 format (YYYY-MM-DD) -* URL: This will be presented as a link in the web UI -* JSON: Arbitrary data stored in JSON format -* Selection: A selection of one of several pre-defined custom choices -* Multiple selection: A selection field which supports the assignment of multiple values -* Object: A single NetBox object of the type defined by `object_type` -* Multiple object: One or more NetBox objects of the type defined by `object_type` - -Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. - -Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. - -A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. - -### Filtering - -The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. - -### Grouping - -!!! note - This feature was introduced in NetBox v3.3. - -Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) - -This parameter has no effect on the API representation of custom field data. - -### Visibility - -!!! note - This feature was introduced in NetBox v3.3. - -When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. - -* **Read/write** (default): The custom field is included when viewing and editing objects. -* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) -* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. - -Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. - -### Validation - -NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: - -* Text: Regular expression (optional) -* Integer: Minimum and/or maximum value (optional) -* Selection: Must exactly match one of the prescribed choices - -### Custom Selection Fields - -Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. - -If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. - -### Custom Object Fields - -An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. diff --git a/docs/models/extras/exporttemplate.md b/docs/models/extras/exporttemplate.md deleted file mode 100644 index e76a3ad47..000000000 --- a/docs/models/extras/exporttemplate.md +++ /dev/null @@ -1,37 +0,0 @@ -# Export Templates - -NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. - -Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. - -Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). - -!!! note - The name `table` is reserved for internal use. - -!!! warning - Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. - -The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: - -```jinja2 -{% for rack in queryset %} -Rack: {{ rack.name }} -Site: {{ rack.site.name }} -Height: {{ rack.u_height }}U -{% endfor %} -``` - -To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. - -If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: -``` -{% for server in queryset %} -{% set data = server.get_config_context() %} -{{ data.syslog }} -{% endfor %} -``` - -The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) - -A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. diff --git a/docs/models/extras/imageattachment.md b/docs/models/extras/imageattachment.md deleted file mode 100644 index da15462ab..000000000 --- a/docs/models/extras/imageattachment.md +++ /dev/null @@ -1,3 +0,0 @@ -# Image Attachments - -Certain objects in NetBox support the attachment of uploaded images. These will be saved to the NetBox server and made available whenever the object is viewed. diff --git a/docs/models/users/objectpermission.md b/docs/models/users/objectpermission.md deleted file mode 100644 index 82dbc955a..000000000 --- a/docs/models/users/objectpermission.md +++ /dev/null @@ -1,69 +0,0 @@ -# Object Permissions - -A permission in NetBox represents a relationship shared by several components: - -* Object type(s) - One or more types of object in NetBox -* User(s)/Group(s) - One or more users or groups of users -* Action(s) - The action(s) that can be performed on an object -* Constraints - An arbitrary filter used to limit the granted action(s) to a specific subset of objects - -At a minimum, a permission assignment must specify one object type, one user or group, and one action. The specification of constraints is optional: A permission without any constraints specified will apply to all instances of the selected model(s). - -## Actions - -There are four core actions that can be permitted for each type of object within NetBox, roughly analogous to the CRUD convention (create, read, update, and delete): - -* **View** - Retrieve an object from the database -* **Add** - Create a new object -* **Change** - Modify an existing object -* **Delete** - Delete an existing object - -In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `napalm_read` permission on the device model allows a user to execute NAPALM queries on a device via NetBox's REST API. These can be specified when granting a permission in the "additional actions" field. - -!!! note - Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named `actions`. - -## Constraints - -Constraints are expressed as a JSON object or list representing a [Django query filter](https://docs.djangoproject.com/en/stable/ref/models/querysets/#field-lookups). This is the same syntax that you would pass to the QuerySet `filter()` method when performing a query using the Django ORM. As with query filters, double underscores can be used to traverse related objects or invoke lookup expressions. Some example queries and their corresponding definitions are shown below. - -All attributes defined within a single JSON object are applied with a logical AND. For example, suppose you assign a permission for the site model with the following constraints. - -```json -{ - "status": "active", - "region__name": "Americas" -} -``` - -The permission will grant access only to sites which have a status of "active" **and** which are assigned to the "Americas" region. - -To achieve a logical OR with a different set of constraints, define multiple objects within a list. For example, if you want to constrain the permission to VLANs with an ID between 100 and 199 _or_ a status of "reserved," do the following: - -```json -[ - { - "vid__gte": 100, - "vid__lt": 200 - }, - { - "status": "reserved" - } -] -``` - -Additionally, where multiple permissions have been assigned for an object type, their collective constraints will be merged using a logical "OR" operation. - -### User Token - -!!! info "This feature was introduced in NetBox v3.3" - -When defining a permission constraint, administrators may use the special token `$user` to reference the current user at the time of evaluation. This can be helpful to restrict users to editing only their own journal entries, for example. Such a constraint might be defined as: - -```json -{ - "created_by": "$user" -} -``` - -The `$user` token can be used only as a constraint value, or as an item within a list of values. It cannot be modified or extended to reference specific user attributes. diff --git a/docs/models/users/token.md b/docs/models/users/token.md deleted file mode 100644 index f6c5bfe80..000000000 --- a/docs/models/users/token.md +++ /dev/null @@ -1,19 +0,0 @@ -## Tokens - -A token is a unique identifier mapped to a NetBox user account. Each user may have one or more tokens which he or she can use for authentication when making REST API requests. To create a token, navigate to the API tokens page under your user profile. - -!!! note - All users can create and manage REST API tokens under the user control panel in the UI. The ability to view, add, change, or delete tokens via the REST API itself is controlled by the relevant model permissions, assigned to users and/or groups in the admin UI. These permissions should be used with great care to avoid accidentally permitting a user to create tokens for other user accounts. - -Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, NetBox allows you to specify a key in case you need to restore a previously deleted token to operation. - -By default, a token can be used to perform all actions via the API that a user would be permitted to do via the web UI. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only. - -Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox. - -### Client IP Restriction - -!!! note - This feature was introduced in NetBox v3.3. - -Each API token can optionally be restricted by client IP address. If one or more allowed IP prefixes/addresses is defined for a token, authentication will fail for any client connecting from an IP address outside the defined range(s). This enables restricting the use a token to a specific client. (By default, any client IP address is permitted.) diff --git a/docs/rest-api/filtering.md b/docs/reference/filtering.md similarity index 100% rename from docs/rest-api/filtering.md rename to docs/reference/filtering.md diff --git a/docs/release-notes/version-3.0.md b/docs/release-notes/version-3.0.md index 93ff33d95..06b889c22 100644 --- a/docs/release-notes/version-3.0.md +++ b/docs/release-notes/version-3.0.md @@ -357,7 +357,7 @@ And the response: ... ``` -All GraphQL requests are made at the `/graphql` URL (which also serves the GraphiQL UI). The API is currently read-only, however users who wish to disable it until needed can do so by setting the `GRAPHQL_ENABLED` configuration parameter to False. For more detail on NetBox's GraphQL implementation, see [the GraphQL API documentation](../graphql-api/overview.md). +All GraphQL requests are made at the `/graphql` URL (which also serves the GraphiQL UI). The API is currently read-only, however users who wish to disable it until needed can do so by setting the `GRAPHQL_ENABLED` configuration parameter to False. For more detail on NetBox's GraphQL implementation, see [the GraphQL API documentation](../integrations/graphql-api.md). #### IP Ranges ([#834](https://github.com/netbox-community/netbox/issues/834)) diff --git a/docs/rest-api/authentication.md b/docs/rest-api/authentication.md deleted file mode 100644 index 411063338..000000000 --- a/docs/rest-api/authentication.md +++ /dev/null @@ -1,73 +0,0 @@ -# REST API Authentication - -The NetBox REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browsable API. - -{!models/users/token.md!} - -## Authenticating to the API - -An authentication token is attached to a request by setting the `Authorization` header to the string `Token` followed by a space and the user's token: - -``` -$ curl -H "Authorization: Token $TOKEN" \ --H "Accept: application/json; indent=4" \ -https://netbox/api/dcim/sites/ -{ - "count": 10, - "next": null, - "previous": null, - "results": [...] -} -``` - -A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/security.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response: - -``` -$ curl https://netbox/api/dcim/sites/ -{ - "detail": "Authentication credentials were not provided." -} -``` - -When a token is used to authenticate a request, its `last_updated` time updated to the current time if its last use was recorded more than 60 seconds ago (or was never recorded). This allows users to determine which tokens have been active recently. - -!!! note - The "last used" time for tokens will not be updated while maintenance mode is enabled. - -## Initial Token Provisioning - -Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. NetBox provides a special endpoint to provision tokens using a valid username and password combination. - -To provision a token via the REST API, make a `POST` request to the `/api/users/tokens/provision/` endpoint: - -``` -$ curl -X POST \ --H "Content-Type: application/json" \ --H "Accept: application/json; indent=4" \ -https://netbox/api/users/tokens/provision/ \ ---data '{ - "username": "hankhill", - "password": "I<3C3H8", -}' -``` - -Note that we are _not_ passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled. - -```json -{ - "id": 6, - "url": "https://netbox/api/users/tokens/6/", - "display": "3c9cb9 (hankhill)", - "user": { - "id": 2, - "url": "https://netbox/api/users/users/2/", - "display": "hankhill", - "username": "hankhill" - }, - "created": "2021-06-11T20:09:13.339367Z", - "expires": null, - "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9", - "write_enabled": true, - "description": "" -} -``` diff --git a/mkdocs.yml b/mkdocs.yml index 4c5279127..f76a91484 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,6 +62,26 @@ markdown_extensions: alternate_style: true nav: - Introduction: 'introduction.md' + - Features: + - Facilities: 'features/facilities.md' + - Tenancy: 'features/tenancy.md' + - Contacts: 'features/contacts.md' + - Devices & Cabling: 'features/devices-cabling.md' + - Power Tracking: 'features/power-tracking.md' + - IPAM: 'features/ipam.md' + - VLAN Management: 'features/vlan-management.md' + - Service Mapping: 'features/services.md' + - L2VPN & Overlay: 'features/l2vpn-overlay.md' + - Circuits: 'features/circuits.md' + - Wireless: 'features/wireless.md' + - Context Data: 'features/context-data.md' + - Change Logging: 'features/change-logging.md' + - Journaling: 'features/journaling.md' + - Webhooks: 'features/webhooks.md' + - Tags: 'features/tags.md' + - Customization: 'features/customization.md' + - Object-Based Permissions: 'features/permissions.md' + - Single Sign-On (SSO): 'features/sso.md' - Installation & Upgrade: - Installing NetBox: 'installation/index.md' - 1. PostgreSQL: 'installation/1-postgresql.md' @@ -90,19 +110,16 @@ nav: - Development: 'configuration/development.md' - Customization: - Custom Fields: 'customization/custom-fields.md' + - Custom Links: 'customization/custom-links.md' - Custom Validation: 'customization/custom-validation.md' - - Custom Links: 'models/extras/customlink.md' - Export Templates: 'customization/export-templates.md' - - Custom Scripts: 'customization/custom-scripts.md' - Reports: 'customization/reports.md' - - Additional Features: - - Change Logging: 'additional-features/change-logging.md' - - Context Data: 'models/extras/configcontext.md' - - Journaling: 'additional-features/journaling.md' - - NAPALM: 'additional-features/napalm.md' - - Prometheus Metrics: 'additional-features/prometheus-metrics.md' - - Tags: 'models/extras/tag.md' - - Webhooks: 'additional-features/webhooks.md' + - Custom Scripts: 'customization/custom-scripts.md' + - Integrations: + - REST API: 'integrations/rest-api.md' + - GraphQL API: 'integrations/graphql-api.md' + - NAPALM: 'integrations/napalm.md' + - Prometheus Metrics: 'integrations/prometheus-metrics.md' - Plugins: - Using Plugins: 'plugins/index.md' - Developing Plugins: @@ -128,12 +145,6 @@ nav: - Housekeeping: 'administration/housekeeping.md' - Replicating NetBox: 'administration/replicating-netbox.md' - NetBox Shell: 'administration/netbox-shell.md' - - REST API: - - Overview: 'rest-api/overview.md' - - Filtering & Ordering: 'rest-api/filtering.md' - - Authentication: 'rest-api/authentication.md' - - GraphQL API: - - Overview: 'graphql-api/overview.md' - Data Model: - Circuits: - Circuit: 'models/circuits/circuit.md' @@ -143,8 +154,6 @@ nav: - Provider Network: 'models/circuits/providernetwork.md' - DCIM: - Cable: 'models/dcim/cable.md' - - CablePath: 'models/dcim/cablepath.md' - - CableTermination: 'models/dcim/cabletermination.md' - ConsolePort: 'models/dcim/consoleport.md' - ConsolePortTemplate: 'models/dcim/consoleporttemplate.md' - ConsoleServerPort: 'models/dcim/consoleserverport.md' @@ -203,7 +212,6 @@ nav: - VRF: 'models/ipam/vrf.md' - Tenancy: - Contact: 'models/tenancy/contact.md' - - ContactAssignment: 'models/tenancy/contactassignment.md' - ContactGroup: 'models/tenancy/contactgroup.md' - ContactRole: 'models/tenancy/contactrole.md' - Tenant: 'models/tenancy/tenant.md' @@ -219,6 +227,7 @@ nav: - WirelessLANGroup: 'models/wireless/wirelesslangroup.md' - WirelessLink: 'models/wireless/wirelesslink.md' - Reference: + - Filtering: 'reference/filtering.md' - Conditions: 'reference/conditions.md' - Markdown: 'reference/markdown.md' - Development: From 4c899f151cce9fae6ae1596c481f2fa92e6a6cf9 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 4 Aug 2022 14:12:51 -0400 Subject: [PATCH 07/28] Drop markdown-include --- mkdocs.yml | 3 --- requirements.txt | 1 - 2 files changed, 4 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index f76a91484..78ca5031c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,9 +47,6 @@ extra_css: markdown_extensions: - admonition - attr_list - - markdown_include.include: - base_path: 'docs/' - headingOffset: 1 - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg diff --git a/requirements.txt b/requirements.txt index 8a7dd79d4..facf925f4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -19,7 +19,6 @@ graphene-django==2.15.0 gunicorn==20.1.0 Jinja2==3.1.2 Markdown==3.4.1 -markdown-include==0.7.0 mkdocs-material==8.3.9 mkdocstrings[python-legacy]==0.19.0 netaddr==0.8.0 From 8c0ef1a0a2e324a8b46af2591a9f1b087fcecb4d Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 4 Aug 2022 16:35:32 -0400 Subject: [PATCH 08/28] Started on feature docs --- docs/features/contacts.md | 23 +++++++++- docs/features/devices-cabling.md | 78 +++++++++++++++++++++++++++++++- docs/features/facilities.md | 57 ++++++++++++++++++++++- docs/features/tenancy.md | 18 +++++++- 4 files changed, 172 insertions(+), 4 deletions(-) diff --git a/docs/features/contacts.md b/docs/features/contacts.md index fb23e53da..7d717b2de 100644 --- a/docs/features/contacts.md +++ b/docs/features/contacts.md @@ -1,3 +1,24 @@ # Contacts -TODO +Much like [tenancy](./tenancy.md), contact assignment enables you to track ownership of resources modeled in NetBox. A contact represents an individual responsible for a resource within the context of its assigned role. + +```mermaid +flowchart TD + ContactGroup --> ContactGroup & Contact + ContactRole & Contact --> assignment([Assignment]) + assignment --> Object +``` + +## Contact Groups + +Contacts can be grouped arbitrarily into a recursive hierarchy, and a contact can be assigned to a group at any level within the hierarchy. + +## Contact Roles + +A contact role defines the relationship of a contact to an assigned object. For example, you might define roles for administrative, operational, and emergency contacts. + +## Contacts + +A contact should represent an individual or permanent point of contact. Each contact must define a name, and may optionally include a title, phone number, email address, and related details. + +Contacts are reused for assignments, so each unique contact must be created only once and can be assigned to any number of NetBox objects, and there is no limit to the number of assigned contacts an object may have. Most core objects in NetBox can have contacts assigned to them. diff --git a/docs/features/devices-cabling.md b/docs/features/devices-cabling.md index ab09b4443..7297f79ac 100644 --- a/docs/features/devices-cabling.md +++ b/docs/features/devices-cabling.md @@ -1,3 +1,79 @@ # Devices & Cabling -TODO +At its heart, NetBox is a tool for modeling your network infrastructure, and the device object is pivotal to that function. A device can be any piece of physical hardware installed within your network, such as server, router, or switch, and may optionally be mounted within a rack. Within each device, resources such as network interfaces and console ports are modeled as discrete components, which may optionally be grouped into modules. + +NetBox uses device types to represent unique real-world device models. This allows a user to define a device type and all its components once, and easily replicate an unlimited number of device instances from it. + +```mermaid +flowchart TD + Manufacturer -.-> Platform & DeviceType & ModuleType + Manufacturer --> DeviceType & ModuleType + DeviceRole & Platform & DeviceType --> Device + Device & ModuleType ---> Module + Device & Module --> Interface & ConsolePort & PowerPort & ... +``` + +## Manufacturers + +A manufacturer generally represents an organization which produces hardware devices. These can be defined by users, however they should represent an actual entity rather than some abstract idea. + +## Device Types + +A device type represents a unique combination of manufacturer and hardware model which maps to discrete make and model of device which exists in the real world. Each device type typically has a number of components created on it, representing network interfaces, device bays, and so on. New devices of this type can then be created in NetBox, and any associated components will be automatically replicated from the device type. This avoids needing to tediously recreate components for each device as it is added in NetBox. + +!!! tip "The Device Type Library" + While users are always free to create their own device types in NetBox, many find it convenient to draw from our [community library](https://github.com/netbox-community/devicetype-library) of pre-defined device types. This is possible because a particular make and model of device is applicable universally and never changes. + +All the following can be modeled as components: + +* Interfaces +* Console ports +* Console server ports +* Power ports +* Power outlets +* Pass-through ports (front and rear) +* Module bays (which house modules) +* Device bays (which house child devices) + +For example, a Juniper EX4300-48T device type might have the following component templates defined: + +* One template for a console port ("Console") +* Two templates for power ports ("PSU0" and "PSU1") +* 48 templates for 1GE interfaces ("ge-0/0/0" through "ge-0/0/47") +* Four templates for 10GE interfaces ("xe-0/2/0" through "xe-0/2/3") + +Once component templates have been created, every new device that you create as an instance of this type will automatically be assigned each of the components listed above. + +!!! note "Component Instantiation is not Retroactive" + The instantiation of components from a device type definition occurs only at the time of device creation. If you modify the components assigned to a device type, it will not affect devices which have already been created. This guards against any inadvertent changes to existing devices. However, you always have the option of adding, modifying, or deleting components on existing devices. (These changes can easily be applied to multiple devices at once using the bulk operations available in the UI.) + +## Devices + +Whereas a device type defines the make and model of a device, a device itself represents an actual piece of installed hardware somewhere in the real world. A device can be installed at a particular position within an equipment rack, or simply associated with a site (and optionally with a location within that site). + +Each device can have an operational status, functional role, and software platform assigned. Device components are instantiated automatically from the assigned device type upon creation. + +### Virtual Chassis + +Sometimes it is necessary to model a set of physical devices as sharing a single management plane. Perhaps the most common example of such a scenario is stackable switches. These can be modeled as virtual chassis in NetBox, with one device acting as the chassis master and the rest as members. All components of member devices will appear on the master. + +## Module Types & Modules + +Much like device types and devices, module types can instantiate discrete modules, which are hardware components installed within devices. Modules often have their own child components, which become available to the parent device. For example, when modeling a chassis-based switch with multiple line cards in NetBox, the chassis would be created (from a device type) as a device, and each of its line cards would be instantiated from a module type as a module installed in one of the device's module bays. + +!!! tip "Device Bays vs. Module Bays" + What's the difference between device bays and module bays? Device bays are appropriate when the installed hardware has its own management plane, isolated from the parent device. A common example is a blade server chassis in which the blades share power but operate independently. In contrast, a module bay holds a module which does _not_ operate independently of its parent device, as with the chassis switch line card example mentioned above. + +One especially nice feature of modules is that templated components can be automatically renamed according to the module bay into which the parent module is installed. For example, if we create a module type with interfaces named `Gi{module}/0/1-48` and install a module of this type into module bay 7 of a device, NetBox will create interfaces named `Gi7/0/1-48`. + +## Cables + +NetBox models cables as connections among certain types of device components and other objects. Each cable can be assigned a type, color, length, and label. NetBox will enforce basic sanity checks to prevent invalid connections. (For example, a network interface cannot be connected to a power outlet.) + +Either end of a cable may terminate to multiple objects of the same type. For example, a network interface can be connected via a fiber optic cable to two discrete ports on a patch panel (each port attaching to an individual fiber strand in the patch cable). + +```mermaid +flowchart LR + Interface --> Cable + Cable --> fp1[Front Port] & fp2[Front Port] +``` diff --git a/docs/features/facilities.md b/docs/features/facilities.md index 5ace5b18b..0fb65aae7 100644 --- a/docs/features/facilities.md +++ b/docs/features/facilities.md @@ -1,3 +1,58 @@ # Facilities -TODO \ No newline at end of file +From global regions down to individual equipment racks, NetBox allows you to model your network's entire presence. This is accomplished through the use of several purpose-built models. The graph below illustrates these models and their relationships. + +```mermaid +flowchart TD + Region --> Region + SiteGroup --> SiteGroup + Region & SiteGroup --> Site + Site --> Location & Device + Location --> Location + Location --> Rack & Device + Rack --> Device + Site --> Rack + RackRole --> Rack +``` + +## Regions + +Regions represent geographic domains in which your network or its customers have a presence. These are typically used to model countries, states, and cities, although NetBox does not prescribe any precise uses and your needs may differ. + +Regions are self-nesting, so you can define child regions within a parent, and grandchildren within each child. For example, you might create a hierarchy like this: + +* Europe + * France + * Germany + * Spain +* North America + * Canada + * United States + * California + * New York + * Texas + +Regions will always be listed alphabetically by name within each parent, and there is no maximum depth for the hierarchy. + +## Site Groups + +Like regions, site groups can be arranged in a recursive hierarchy for grouping sites. However, whereas regions are intended for geographic organization, site groups may be used for functional grouping. For example, you might classify sites as corporate, branch, or customer sites in addition to where they are physically located. + +The use of both regions and site groups affords to independent but complementary dimensions across which sites can be organized. + +## Site + +A site typically represents a building within a region and/or site group. Each site is assigned an operational status (e.g. active or planned), and can have a discrete mailing address and GPS coordinates assigned to it. + +## Location + +A location can be any logical subdivision within a building, such as a floor or room. Like regions and site groups, locations can be nested into a self-recursive hierarchy for maximum flexibility. And like sites, each location has an operational status assigned to it. + +## Rack + +Finally, NetBox models each equipment rack as a discrete object within a site and location. These are physical objects into which devices are installed. Each rack can be assigned an operational status, type, facility ID, and other attributes related to inventory tracking. Each rack also must define a height (in rack units) and width, and may optionally specify its physical dimensions. + +Each rack must be associated to a site, but the assignment to a location within that site is optional. Users can also create custom roles to which racks can be assigned. + +!!! tip "Devices" + You'll notice in the diagram above that a device can be installed within a site, location, or rack. This approach affords plenty of flexibility as not all sites need to define child locations, and not all devices reside in racks. diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md index 20534b13c..fe6d8e5a8 100644 --- a/docs/features/tenancy.md +++ b/docs/features/tenancy.md @@ -1,3 +1,19 @@ # Tenancy -TODO +Most core objects within NetBox's data model support _tenancy_. This is the association of an object with a particular tenant to convey ownership or dependency. For example, an enterprise might represent its internal business units as tenants, whereas a managed services provider might create a tenant in NetBox to represent each of its customers. + +```mermaid +flowchart TD + TenantGroup --> TenantGroup & Tenant + Tenant --> Site & Device & Prefix & Circuit & ... +``` + +## Tenant Groups + +Tenants can be grouped by any logic that your use case demands, and groups can nested recursively for maximum flexibility. For example, You might define a parent "Customers" group with child groups "Current" and "Past" within it. A tenant can be assigned to a group at any level within the hierarchy. + +## Tenants + +Typically, the tenant model is used to represent a customer or internal organization, however it can be used for whatever purpose meets your needs. + +Most core objects within NetBox can be assigned to particular tenant, so this model provides a very convenient way to correlate ownership across object types. For example, each of your customers might have its own racks, devices, IP addresses, circuits and so on: These can all be easily tracked via tenant assignment. From 1a0b6d6cb03c144caf770f9ccd02ce0970b8c37e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 9 Aug 2022 16:49:28 -0400 Subject: [PATCH 09/28] Continued work on feature docs --- docs/features/facilities.md | 8 ++--- docs/features/ipam.md | 55 ++++++++++++++++++++++++++++++++- docs/features/power-tracking.md | 19 +++++++++++- 3 files changed, 76 insertions(+), 6 deletions(-) diff --git a/docs/features/facilities.md b/docs/features/facilities.md index 0fb65aae7..f105bd4c5 100644 --- a/docs/features/facilities.md +++ b/docs/features/facilities.md @@ -40,19 +40,19 @@ Like regions, site groups can be arranged in a recursive hierarchy for grouping The use of both regions and site groups affords to independent but complementary dimensions across which sites can be organized. -## Site +## Sites A site typically represents a building within a region and/or site group. Each site is assigned an operational status (e.g. active or planned), and can have a discrete mailing address and GPS coordinates assigned to it. -## Location +## Locations A location can be any logical subdivision within a building, such as a floor or room. Like regions and site groups, locations can be nested into a self-recursive hierarchy for maximum flexibility. And like sites, each location has an operational status assigned to it. -## Rack +## Racks Finally, NetBox models each equipment rack as a discrete object within a site and location. These are physical objects into which devices are installed. Each rack can be assigned an operational status, type, facility ID, and other attributes related to inventory tracking. Each rack also must define a height (in rack units) and width, and may optionally specify its physical dimensions. -Each rack must be associated to a site, but the assignment to a location within that site is optional. Users can also create custom roles to which racks can be assigned. +Each rack must be associated to a site, but the assignment to a location within that site is optional. Users can also create custom roles to which racks can be assigned. NetBox supports tracking rack space in half-unit increments, so it's possible to mount devices at e.g. position 2.5 within a rack. !!! tip "Devices" You'll notice in the diagram above that a device can be installed within a site, location, or rack. This approach affords plenty of flexibility as not all sites need to define child locations, and not all devices reside in racks. diff --git a/docs/features/ipam.md b/docs/features/ipam.md index f263f3ab3..7832fab44 100644 --- a/docs/features/ipam.md +++ b/docs/features/ipam.md @@ -1,3 +1,56 @@ # IP Address Management -TODO +IP address management (IPAM) is one of NetBox's core features. It supports full parity for IP4 and IPv6, advanced VRF assignment, automatic hierarchy formation, and much more. + +## IP Hierarchy + +NetBox employs several object types to represent a hierarchy of IP resources: + +* **Aggregate** - A prefix which represents the root of an addressing hierarchy. This is typically a large swath of public or private address space allocated for use by your organization. Each aggregate is assigned to an authoritative RIR. +* **Prefix** - A subnet defined within an aggregate. Prefixes extend the hierarchy by nesting within one another. (For example, 192.168.123.0/24 will appear within 192.168.0.0/16.) Each prefix can be assigned a functional role as well as an operational status. +* **IP Range** - An arbitrary range of individual IP addresses within a prefix, all sharing the same mask. Ranges are commonly affiliated with DHCP scopes, but can be used for any similar purpose. +* **IP Address** - An individual IP address along with its subnet mask, automatically arranged beneath its parent prefix. + +```mermaid +flowchart TD + RIR --> Aggregate + Aggregate & Role --> Prefix + Prefix --> Prefix + Prefix --> IPRange & IPAddress +``` + +!!! tip "Automatic Hierarchies" + IP objects in NetBox never need to be manually assigned to the parent objects. The construction of hierarchies is handled automatically by the application according to the inherent rules of IP addressing. + +An example hierarchy might look like this: + +* 100.64.0.0/10 (aggregate) + * 100.64.0.0/20 (prefix) + * 100.64.16.0/20 (prefix) + * 100.64.16.0/24 (prefix) + * 100.64.16.1/24 (address) + * 100.64.16.2/24 (address) + * 100.64.16.3/24 (address) + * 100.64.16.9/24 (prefix) + * 100.64.32.0/20 (prefix) + * 100.64.32.1/24 (address) + * 100.64.32.10-99/24 (range) + +## Utilization Stats + +The utilization rate for each prefix is calculated automatically depending on its status. _Container_ prefixes are those which house child prefixes; their utilization rate is determined based on how much of their available IP space is consumed by child prefixes. The utilization rate for any other type of prefix is determined by the aggregate usage of any child IP addresses and/or ranges defined. + +Similarly, utilization rates for aggregates is determined based on the space consumed by their child prefixes. + +## VRF Tracking + +NetBox supports the modeling of discrete virtual routing and forwarding (VRF) instances to represent multiple routing tables, including those with overlapping address space. Each type of IP object within an aggregate - prefix, IP range, and IP address - can be assigned to a particular VRF. Consequently, each VRF maintains its own isolated IP hierarchy. This makes it very easy to track overlapping IP space. + +VRF modeling in NetBox very closely follows what you find in real-world network configurations, with each VRF assigned a standards-compliant route distinguisher. You can even create route targets to manage the import and export of routing information among VRFs. + +!!! tip "Enforcing Unique IP Space" + Each VRF can be independently configured to permit or prohibit duplicate IP objects. For example, a VRF which has been configured to enforce unique IP space will not allow the creation of two 192.0.2.0/24 prefixes. The ability to toggle this restriction per VRF affords the user maximum flexibility in modeling their IP space. + +## AS Numbers + +An often overlooked component of IPAM, NetBox also tracks autonomous system (AS) numbers and their assignment to sites. Both 16- and 32-bit AS numbers are supported, and like aggregates each ASN is assigned to an authoritative RIR. diff --git a/docs/features/power-tracking.md b/docs/features/power-tracking.md index 1267af1e6..e19ec421b 100644 --- a/docs/features/power-tracking.md +++ b/docs/features/power-tracking.md @@ -1,3 +1,20 @@ # Power Tracking -TODO +As part of its DCIM feature set, NetBox supports modeling facility power as discrete power panels and feeds. These are most commonly used to document power distribution within a data center, but can serve more traditional environments as well. + +![Power distribution model](../media/power_distribution.png) + +## Power Panels + +A power panel is the furthest upstream power element modeled in NetBox. It typically represents a power distribution panel (or breaker panel) where facility power is split into multiple discrete circuits, which are modeled as feeds. + +Each power panel is associated with a site, and may optionally be associated with a particular location within that site. There is no limit to how many power feeds a single panel can supply, however both of these object types should map to real-world objects. + +## Power Feeds + +A power feed represents a discrete power circuit originating from an upstream power panel. Each power feed can be assigned a name, operational status, and various electrical characteristics such as supply (AC or DC), voltage, amperage, and so on. + +A device power port can be connected to a power feed via a cable. Only one port can be connected to a feed: Where multiple devices draw power from the same feed, a power distribution unit (PDU) must be modeled as an individual device mapping a power port to multiple power outlets to which the downstream devices can connect (as in the example above). + +!!! tip "Primary and Redundant Power" + Each power feed in NetBox is assigned a type: primary or redundant. This allows easily modeling redundant power distribution topologies. In scenarios involving only a single, non-redundant power supply, mark all power feeds as primary. From e69be8f9a631e255caf08b838951d2041efbf4b1 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 10 Aug 2022 12:51:21 -0400 Subject: [PATCH 10/28] Continued work on feature docs --- docs/features/circuits.md | 26 +++++++++++++++++++++++++- docs/features/ipam.md | 6 ++++++ docs/features/l2vpn-overlay.md | 4 +++- docs/features/services.md | 3 --- docs/features/vlan-management.md | 19 ++++++++++++++++++- docs/features/wireless.md | 25 ++++++++++++++++++++++++- mkdocs.yml | 1 - 7 files changed, 76 insertions(+), 8 deletions(-) delete mode 100644 docs/features/services.md diff --git a/docs/features/circuits.md b/docs/features/circuits.md index 63c8bc970..f0c5832c4 100644 --- a/docs/features/circuits.md +++ b/docs/features/circuits.md @@ -1,3 +1,27 @@ # Circuits -TODO +NetBox is ideal for managing your network's transit and peering providers and circuits. It provides all the flexibility needed to model physical circuits in both data center and enterprise environments, and allows for "connecting" circuits directly to device interfaces via cables. + +```mermaid +flowchart TD + ASN --> Provider + Provider --> ProviderNetwork & Circuit + CircuitType --> Circuit +``` + +## Providers + +A provider is any organization which provides Internet or private connectivity. Typically, these are large carriers, however they might also include regional providers or even internal services. Each provider can be assigned account and contact details, and may have one or more AS numbers assigned to it. + +Sometimes you'll need to model provider networks into which you don't have full visibility; these are typically represented on topology diagrams with cloud icons. NetBox facilitates this through its provider network model: A provider network represents a "black box" network to which your circuits can connect. A common example is a provider MPLS network connecting multiple sites. + +## Circuits + +A circuit is a physical connection between two points, which is installed and maintained by an external provider. For example, an Internet connection delivered as a fiber optic cable would be modeled as a circuit in NetBox. + +Each circuit is associated with a provider and assigned a circuit ID, which must be unique to that provider. A circuit is also assigned a user-defined type, operational status, and various other operating characteristics. + +Each circuit may have up to two terminations (A and Z) defined. Each termination can be associated with a particular site or provider network. In the case of the former, a cable can be connected between the circuit termination and a device component to map its physical connectivity. + +!!! warning "Physical vs. Virtual Circuits" + The circuit model in NetBox represents **physical** connections. Don't confuse these with _virtual_ circuits which may be offered by providers overlaid on physical infrastructure. (For example, a VLAN-tagged subinterface would be a virtual circuit.) A good rule of thumb: If you can't point to it, it's not a physical circuit. diff --git a/docs/features/ipam.md b/docs/features/ipam.md index 7832fab44..45a6a0221 100644 --- a/docs/features/ipam.md +++ b/docs/features/ipam.md @@ -54,3 +54,9 @@ VRF modeling in NetBox very closely follows what you find in real-world network ## AS Numbers An often overlooked component of IPAM, NetBox also tracks autonomous system (AS) numbers and their assignment to sites. Both 16- and 32-bit AS numbers are supported, and like aggregates each ASN is assigned to an authoritative RIR. + +## Service Mapping + +NetBox models network applications as discrete service objects associated with devices and/or virtual machines, and optionally with specific IP addresses attached to those parent objects. These can be used to catalog the applications running on your network for reference by other objects or integrated tools. + +To model services in NetBox, begin by creating a service template defining the name, protocol, and port number(s) on which the service listens. This template can then be easily instantiated to "attach" new services to a device or virtual machine. It's also possible to create new services by hand, without a template, however this approach can be tedious. diff --git a/docs/features/l2vpn-overlay.md b/docs/features/l2vpn-overlay.md index 002c483f9..51fbf2a78 100644 --- a/docs/features/l2vpn-overlay.md +++ b/docs/features/l2vpn-overlay.md @@ -1,3 +1,5 @@ # L2VPN & Overlay -TODO +L2VPN and overlay networks, such as VXLAN and EVPN, can be defined in NetBox and tied to interfaces and VLANs. This allows for easy tracking of overlay assets and their relationships with underlay resources. + +Each L2VPN instance has a type and optional unique identifier. Like VRFs, L2VPNs can also have import and export route targets assigned to them. Terminations can then be created to assign VLANs and/or device and virtual machine interfaces to the overlay. diff --git a/docs/features/services.md b/docs/features/services.md deleted file mode 100644 index 338fc349a..000000000 --- a/docs/features/services.md +++ /dev/null @@ -1,3 +0,0 @@ -# Services - -TODO diff --git a/docs/features/vlan-management.md b/docs/features/vlan-management.md index 3d4fd4d1f..4af05dea3 100644 --- a/docs/features/vlan-management.md +++ b/docs/features/vlan-management.md @@ -1,3 +1,20 @@ # VLAN Management -TODO +Complementing its IPAM capabilities, NetBox also tracks VLAN information to assist with layer two network configurations. VLANs are defined per IEEE 802.1Q and related standards, and can be assigned to groups and functional roles. + +```mermaid +flowchart TD + VLANGroup & Role --> VLAN +``` + +## VLAN Groups + +A VLAN group is a collection of VLANs defined within a particular scope. Each VLAN group can be associated with a particular site, location, rack, or similar object to indicate its domain, and designates a minimum and maximum VLAN ID within the group. (By default, these are the standard minimum and maximum values of 1 and 4094, respectively.) + +Within a group, each VLAN must have a unique ID and name. There is no limit to how many groups can be created per scope. + +## VLANs + +NetBox models VLANs according to their definition under IEEE 802.1Q, with a 12-bit VLAN ID and a name. Each VLAN also has an operational status, and may be assigned a function role, just like prefixes. Each VLAN can be assigned to a VLAN group or site to convey the domain in which the VLAN exists. + +Once defined, VLANs can be associated with device and virtual machine interfaces. Each interface can be assigned an 802.1Q mode (access or tagged), and the relevant VLANs can be applied as tagged or untagged. diff --git a/docs/features/wireless.md b/docs/features/wireless.md index ff3d5d10b..215d1a682 100644 --- a/docs/features/wireless.md +++ b/docs/features/wireless.md @@ -1,3 +1,26 @@ # Wireless -TODO +Just as NetBox provides robust modeling for physical cable plants, it also supports modeling wireless LANs and point-to-point links. + +## Wireless LANs + +```mermaid +flowchart TD + WirelessLANGroup --> WirelessLANGroup & WirelessLAN +``` + +A wireless LAN is a multi-access network shared by multiple wireless clients, identified by a common service set identifier (SSID) and authentication parameters. Wireless LANs can be organized into self-nesting groups, and each wireless LAN may optionally be bound to a particular VLAN. This allows easily mapping wireless networks to their wired counterparts. + +Authentication attributes for wireless LANs include: + +* **Type** - Open, WEP, WPA, etc. +* **Cipher** - Auto, TKIP, or AES +* **Pre-shared key (PSK)** - The secret key configured on all participating clients + +The definition of authentication parameters is optional. + +## Wireless Links + +Whereas a wireless LAN represents a physical multi-access segment with any number of clients, a wireless link is a point-to-point connection between exactly two stations. These links behave much like cables, but more accurately model the nature of wireless communications. + +Like wireless LANs, wireless links also have an SSID and (optional) authentication attributes. diff --git a/mkdocs.yml b/mkdocs.yml index 78ca5031c..784e4498e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,7 +67,6 @@ nav: - Power Tracking: 'features/power-tracking.md' - IPAM: 'features/ipam.md' - VLAN Management: 'features/vlan-management.md' - - Service Mapping: 'features/services.md' - L2VPN & Overlay: 'features/l2vpn-overlay.md' - Circuits: 'features/circuits.md' - Wireless: 'features/wireless.md' From 9733cee3d208d017382c44d966e2ab8f80a1f31f Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 10 Aug 2022 14:07:51 -0400 Subject: [PATCH 11/28] Continued work on feature docs --- docs/development/models.md | 2 +- docs/features/context-data.md | 79 ++++++--------------- docs/features/customization.md | 38 ++++++++++ docs/features/integrations.md | 41 +++++++++++ docs/features/tags.md | 17 ----- docs/{features => integrations}/webhooks.md | 0 docs/models/extras/configcontext.md | 69 ++++++++++++++++++ docs/models/extras/tag.md | 17 +++++ mkdocs.yml | 6 +- 9 files changed, 193 insertions(+), 76 deletions(-) create mode 100644 docs/features/integrations.md rename docs/{features => integrations}/webhooks.md (100%) create mode 100644 docs/models/extras/configcontext.md create mode 100644 docs/models/extras/tag.md diff --git a/docs/development/models.md b/docs/development/models.md index be3608a30..3c7aaaa78 100644 --- a/docs/development/models.md +++ b/docs/development/models.md @@ -9,7 +9,7 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/ ### Features Matrix * [Change logging](../features/change-logging.md) - Changes to these objects are automatically recorded in the change log -* [Webhooks](../features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects +* [Webhooks](../integrations/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects * [Custom fields](../customization/custom-fields.md) - These models support the addition of user-defined fields * [Export templates](../customization/export-templates.md) - Users can create custom export templates for these models * [Tagging](../features/tags.md) - The models can be tagged with user-defined tags diff --git a/docs/features/context-data.md b/docs/features/context-data.md index 08b5f4fd5..d202482da 100644 --- a/docs/features/context-data.md +++ b/docs/features/context-data.md @@ -1,69 +1,34 @@ -# Configuration Contexts +# Context Data -Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments: - -* Region -* Site group -* Site -* Location (devices only) -* Device type (devices only) -* Role -* Platform -* Cluster type (VMs only) -* Cluster group (VMs only) -* Cluster (VMs only) -* Tenant group -* Tenant -* Tag - -## Hierarchical Rendering - -Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object. - -For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data: - -```json -{ - "ntp-servers": [ - "172.16.10.22", - "172.16.10.33" - ], - "syslog-servers": [ - "172.16.9.100", - "172.16.9.101" - ] -} -``` - -But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data: +Configuration context data (or "config contexts" for short) is a powerful feature that enables users to define arbitrary data that applies to device and virtual machines based on certain characteristics. For example, suppose you want to define syslog servers for devices assigned to sites within a particular region. In NetBox, you can create a config context instance containing this data and apply it to the desired region. All devices within this region will now include this data when fetched via an API. ```json { "syslog-servers": [ - "192.168.43.107" + "192.168.43.107", + "192.168.48.112" ] } ``` -When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following: +While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases. -```json -{ - "ntp-servers": [ - "172.16.10.22", - "172.16.10.33" - ], - "syslog-servers": [ - "192.168.43.107" - ] -} -``` +There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. Additionally, each device and VM may have local context data defined: This data is stored directly on the assigned object, and applies to it only. This is a convenient way for "attaching" miscellaneous data to a single device or VM as needed. -Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved. +Config contexts can be computed for objects based on the following criteria: -## Local Context Data - -Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object. - -!!! warning - If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution. +| Type | Devices | Virtual Machines | +|---------------|------------------|------------------| +| Region | :material-check: | :material-check: | +| Site group | :material-check: | :material-check: | +| Site | :material-check: | :material-check: | +| Location | :material-check: | | +| Device type | :material-check: | | +| Role | :material-check: | :material-check: | +| Platform | :material-check: | :material-check: | +| Cluster type | | :material-check: | +| Cluster group | | :material-check: | +| Cluster | | :material-check: | +| Tenant group | :material-check: | :material-check: | +| Tenant | :material-check: | :material-check: | +| Tag | :material-check: | :material-check: | diff --git a/docs/features/customization.md b/docs/features/customization.md index ae775312e..5b42d5e43 100644 --- a/docs/features/customization.md +++ b/docs/features/customization.md @@ -1,3 +1,41 @@ # Customization +While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs. + +## Custom Fields + +While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs. + +NetBox supports many types of custom field, from basic data types like strings and integers, to complex structures like selection lists or raw JSON. It's even possible to add a custom field which references other NetBox objects. Custom field data is stored directly alongside the object to which it is applied in the database, which ensures minimal performance impact. And custom field data can be written and read via the REST API, just like built-in fields. + +To learn more about this feature, check out the [custom field documentation](../customization/custom-fields.md). + +## Custom Links + TODO + +To learn more about this feature, check out the [custom link documentation](../customization/custom-links.md). + +## Custom Validation + +TODO + +To learn more about this feature, check out the [custom validation documentation](../customization/custom-validation.md). + +## Export Templates + +TODO + +To learn more about this feature, check out the [export template documentation](../customization/export-templates.md). + +## Reports + +TODO + +To learn more about this feature, check out the [documentation for reports](../customization/reports.md). + +## Custom Scripts + +TODO + +To learn more about this feature, check out the [documentation for custom scripts](../customization/custom-scripts.md). diff --git a/docs/features/integrations.md b/docs/features/integrations.md new file mode 100644 index 000000000..c2f68c5c8 --- /dev/null +++ b/docs/features/integrations.md @@ -0,0 +1,41 @@ +# Integrations + +NetBox includes a slew of features which enable integration with other tools and resources powering your network. + +## REST API + +NetBox's REST API, powered by the [Django REST Framework](https://www.django-rest-framework.org/), provides a robust yet accessible interface for creating, modifying, and deleting objects. Employing HTTP for transfer and JSON for data encapsulation, the REST API is easily consumed by clients on any platform and extremely well suited for automation tasks. + +```no-highlight +curl -s -X POST \ +-H "Authorization: Token $TOKEN" \ +-H "Content-Type: application/json" \ +http://netbox/api/ipam/prefixes/ \ +--data '{"prefix": "192.0.2.0/24", "site": {"name": "Branch 12"}}' +``` + +The REST API employs token-based authentication, which maps API clients to user accounts and their assigned permissions. The API endpoints are fully documented using OpenAPI, and NetBox even includes a convenient browser-based version of the API for exploration. The open source [pynetbox](https://github.com/netbox-community/pynetbox) and [go-netbox](https://github.com/netbox-community/go-netbox) API client libraries are also available for Python and Go, respectively. + +To learn more about this feature, check out the [REST API documentation](../integrations/rest-api.md). + +## GraphQL API + +NetBox also provides a [GraphQL](https://graphql.org/) API to complement its REST API. GraphQL enables complex queries for arbitrary objects and fields, enabling the client to retrieve only the specific data it needs from NetBox. This is a special-purpose read-only API intended for efficient queries. Like the REST API, the GraphQL API employs token-based authentication. + +To learn more about this feature, check out the [GraphQL API documentation](../integrations/graphql-api.md). + +## Webhooks + +A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are an excellent mechanism for building event-based automation processes. + +To learn more about this feature, check out the [webhooks documentation](../integrations/webhooks.md). + +## NAPALM + +[NAPALM](https://github.com/napalm-automation/napalm) is a Python library which enables direct interaction with network devices of various platforms. When configured, NetBox supports fetching live operational and status data directly from network devices to be compared to what has been defined in NetBox. This allows for easily validating the device's operational state against its desired state. Additionally, NetBox's REST API can act as a sort of proxy for NAPALM commands, allowing external clients to interact with network devices by sending HTTP requests to the appropriate API endpoint. + +To learn more about this feature, check out the [NAPALM documentation](../integrations/napalm.md). + +## Prometheus Metrics + +NetBox includes a special `/metrics` view which exposes metrics for a [Prometheus](https://prometheus.io/) scraper, powered by the open source [django-prometheus](https://github.com/korfuri/django-prometheus) library. To learn more about this feature, check out the [Prometheus metrics documentation](../integrations/prometheus-metrics.md). diff --git a/docs/features/tags.md b/docs/features/tags.md index fe6a1ef36..e69de29bb 100644 --- a/docs/features/tags.md +++ b/docs/features/tags.md @@ -1,17 +0,0 @@ -# Tags - -Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects. - -Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose. - -Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": - -```no-highlight -GET /api/dcim/devices/?tag=monitored -``` - -The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned: - -```no-highlight -GET /api/dcim/devices/?tag=monitored&tag=deprecated -``` diff --git a/docs/features/webhooks.md b/docs/integrations/webhooks.md similarity index 100% rename from docs/features/webhooks.md rename to docs/integrations/webhooks.md diff --git a/docs/models/extras/configcontext.md b/docs/models/extras/configcontext.md new file mode 100644 index 000000000..08b5f4fd5 --- /dev/null +++ b/docs/models/extras/configcontext.md @@ -0,0 +1,69 @@ +# Configuration Contexts + +Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments: + +* Region +* Site group +* Site +* Location (devices only) +* Device type (devices only) +* Role +* Platform +* Cluster type (VMs only) +* Cluster group (VMs only) +* Cluster (VMs only) +* Tenant group +* Tenant +* Tag + +## Hierarchical Rendering + +Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object. + +For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data: + +```json +{ + "ntp-servers": [ + "172.16.10.22", + "172.16.10.33" + ], + "syslog-servers": [ + "172.16.9.100", + "172.16.9.101" + ] +} +``` + +But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data: + +```json +{ + "syslog-servers": [ + "192.168.43.107" + ] +} +``` + +When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following: + +```json +{ + "ntp-servers": [ + "172.16.10.22", + "172.16.10.33" + ], + "syslog-servers": [ + "192.168.43.107" + ] +} +``` + +Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved. + +## Local Context Data + +Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object. + +!!! warning + If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution. diff --git a/docs/models/extras/tag.md b/docs/models/extras/tag.md new file mode 100644 index 000000000..fe6a1ef36 --- /dev/null +++ b/docs/models/extras/tag.md @@ -0,0 +1,17 @@ +# Tags + +Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects. + +Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose. + +Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": + +```no-highlight +GET /api/dcim/devices/?tag=monitored +``` + +The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned: + +```no-highlight +GET /api/dcim/devices/?tag=monitored&tag=deprecated +``` diff --git a/mkdocs.yml b/mkdocs.yml index 784e4498e..95672cede 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,8 +73,8 @@ nav: - Context Data: 'features/context-data.md' - Change Logging: 'features/change-logging.md' - Journaling: 'features/journaling.md' - - Webhooks: 'features/webhooks.md' - Tags: 'features/tags.md' + - Integrations: 'features/integrations.md' - Customization: 'features/customization.md' - Object-Based Permissions: 'features/permissions.md' - Single Sign-On (SSO): 'features/sso.md' @@ -114,6 +114,7 @@ nav: - Integrations: - REST API: 'integrations/rest-api.md' - GraphQL API: 'integrations/graphql-api.md' + - Webhooks: 'integrations/webhooks.md' - NAPALM: 'integrations/napalm.md' - Prometheus Metrics: 'integrations/prometheus-metrics.md' - Plugins: @@ -188,6 +189,9 @@ nav: - Site: 'models/dcim/site.md' - SiteGroup: 'models/dcim/sitegroup.md' - VirtualChassis: 'models/dcim/virtualchassis.md' + - Extras: + - ConfigContext: 'models/extras/configcontext.md' + - Tag: 'models/extras/tag.md' - IPAM: - ASN: 'models/ipam/asn.md' - Aggregate: 'models/ipam/aggregate.md' From 5f15f550c9fdf3603b5fd17816c929434f42b78e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 11:37:07 -0400 Subject: [PATCH 12/28] Restore model documentation for all models under extras --- docs/customization/custom-fields.md | 109 ------------------- docs/customization/custom-links.md | 66 ------------ docs/customization/export-templates.md | 81 -------------- docs/integrations/webhooks.md | 139 ------------------------- docs/models/extras/customfield.md | 109 +++++++++++++++++++ docs/models/extras/customlink.md | 66 ++++++++++++ docs/models/extras/exporttemplate.md | 81 ++++++++++++++ docs/models/extras/imageattachment.md | 3 + docs/models/extras/webhook.md | 139 +++++++++++++++++++++++++ mkdocs.yml | 5 + 10 files changed, 403 insertions(+), 395 deletions(-) create mode 100644 docs/models/extras/customfield.md create mode 100644 docs/models/extras/customlink.md create mode 100644 docs/models/extras/exporttemplate.md create mode 100644 docs/models/extras/imageattachment.md create mode 100644 docs/models/extras/webhook.md diff --git a/docs/customization/custom-fields.md b/docs/customization/custom-fields.md index bfe412edc..e69de29bb 100644 --- a/docs/customization/custom-fields.md +++ b/docs/customization/custom-fields.md @@ -1,109 +0,0 @@ -# Custom Fields - -Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. - -However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. - -Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. - -## Creating Custom Fields - -Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: - -* Text: Free-form text (intended for single-line use) -* Long text: Free-form of any length; supports Markdown rendering -* Integer: A whole number (positive or negative) -* Boolean: True or false -* Date: A date in ISO 8601 format (YYYY-MM-DD) -* URL: This will be presented as a link in the web UI -* JSON: Arbitrary data stored in JSON format -* Selection: A selection of one of several pre-defined custom choices -* Multiple selection: A selection field which supports the assignment of multiple values -* Object: A single NetBox object of the type defined by `object_type` -* Multiple object: One or more NetBox objects of the type defined by `object_type` - -Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. - -Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. - -A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. - -### Filtering - -The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. - -### Grouping - -!!! note - This feature was introduced in NetBox v3.3. - -Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) - -This parameter has no effect on the API representation of custom field data. - -### Visibility - -!!! note - This feature was introduced in NetBox v3.3. - -When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. - -* **Read/write** (default): The custom field is included when viewing and editing objects. -* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) -* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. - -Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. - -### Validation - -NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: - -* Text: Regular expression (optional) -* Integer: Minimum and/or maximum value (optional) -* Selection: Must exactly match one of the prescribed choices - -### Custom Selection Fields - -Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. - -If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. - -### Custom Object Fields - -An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. - - -## Custom Fields in Templates - -Several features within NetBox, such as export templates and webhooks, utilize Jinja2 templating. For convenience, objects which support custom field assignment expose custom field data through the `cf` property. This is a bit cleaner than accessing custom field data through the actual field (`custom_field_data`). - -For example, a custom field named `foo123` on the Site model is accessible on an instance as `{{ site.cf.foo123 }}`. - -## Custom Fields and the REST API - -When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined: - -```json -{ - "id": 123, - "url": "http://localhost:8000/api/dcim/sites/123/", - "name": "Raleigh 42", - ... - "custom_fields": { - "deployed": "2018-06-19", - "site_code": "US-NC-RAL42" - }, - ... -``` - -To set or change these values, simply include nested JSON data. For example: - -```json -{ - "name": "New Site", - "slug": "new-site", - "custom_fields": { - "deployed": "2019-03-24" - } -} -``` diff --git a/docs/customization/custom-links.md b/docs/customization/custom-links.md index 16ba9d2af..e69de29bb 100644 --- a/docs/customization/custom-links.md +++ b/docs/customization/custom-links.md @@ -1,66 +0,0 @@ -# Custom Links - -Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS). - -Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the NetBox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`. - -For example, you might define a link like this: - -* Text: `View NMS` -* URL: `https://nms.example.com/nodes/?name={{ obj.name }}` - -When viewing a device named Router4, this link would render as: - -```no-highlight -View NMS -``` - -Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually. - -!!! warning - Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users. - -## Context Data - -The following context data is available within the template when rendering a custom link's text or URL. - -| Variable | Description | -|-----------|-------------------------------------------------------------------------------------------------------------------| -| `object` | The NetBox object being displayed | -| `obj` | Same as `object`; maintained for backward compatability until NetBox v3.5 | -| `debug` | A boolean indicating whether debugging is enabled | -| `request` | The current WSGI request | -| `user` | The current user (if authenticated) | -| `perms` | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user | - -While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type. - -Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list. - -## Conditional Rendering - -Only links which render with non-empty text are included on the page. You can employ conditional Jinja2 logic to control the conditions under which a link gets rendered. - -For example, if you only want to display a link for active devices, you could set the link text to - -```jinja2 -{% if obj.status == 'active' %}View NMS{% endif %} -``` - -The link will not appear when viewing a device with any status other than "active." - -As another example, if you wanted to show only devices belonging to a certain manufacturer, you could do something like this: - -```jinja2 -{% if obj.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %} -``` - -The link will only appear when viewing a device with a manufacturer name of "Cisco." - -## Link Groups - -Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group. - -## Table Columns - -Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL. diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index 640a97531..e69de29bb 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -1,81 +0,0 @@ -# Export Templates - -NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. - -Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. - -Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). - -!!! note - The name `table` is reserved for internal use. - -!!! warning - Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. - -The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: - -```jinja2 -{% for rack in queryset %} -Rack: {{ rack.name }} -Site: {{ rack.site.name }} -Height: {{ rack.u_height }}U -{% endfor %} -``` - -To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. - -If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: -``` -{% for server in queryset %} -{% set data = server.get_config_context() %} -{{ data.syslog }} -{% endfor %} -``` - -The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) - -A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. - - -## REST API Integration - -When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: - -``` -GET /api/dcim/sites/?export=MyTemplateName -``` - -Note that the body of the response will contain only the rendered export template content, as opposed to a JSON object or list. - -## Example - -Here's an example device export template that will generate a simple Nagios configuration from a list of devices. - -``` -{% for device in queryset %}{% if device.status and device.primary_ip %}define host{ - use generic-switch - host_name {{ device.name }} - address {{ device.primary_ip.address.ip }} -} -{% endif %}{% endfor %} -``` - -The generated output will look something like this: - -``` -define host{ - use generic-switch - host_name switch1 - address 192.0.2.1 -} -define host{ - use generic-switch - host_name switch2 - address 192.0.2.2 -} -define host{ - use generic-switch - host_name switch3 - address 192.0.2.3 -} -``` diff --git a/docs/integrations/webhooks.md b/docs/integrations/webhooks.md index 4705243d1..e69de29bb 100644 --- a/docs/integrations/webhooks.md +++ b/docs/integrations/webhooks.md @@ -1,139 +0,0 @@ -# Webhooks - -A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks. - -!!! warning - Webhooks support the inclusion of user-submitted code to generate URL, custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users. - -## Configuration - -* **Name** - A unique name for the webhook. The name is not included with outbound messages. -* **Object type(s)** - The type or types of NetBox object that will trigger the webhook. -* **Enabled** - If unchecked, the webhook will be inactive. -* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected. -* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. -* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field. -* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`) -* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below). -* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.) -* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key. -* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object. -* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!) -* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional). - -## Jinja2 Template Support - -[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands. - -For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration: - -* Object type: IPAM > IP address -* HTTP method: `POST` -* URL: Slack incoming webhook URL -* HTTP content type: `application/json` -* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}` - -### Available Context - -The following data is available as context for Jinja2 templates: - -* `event` - The type of event which triggered the webhook: created, updated, or deleted. -* `model` - The NetBox model which triggered the change. -* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). -* `username` - The name of the user account associated with the change. -* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request. -* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API. -* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed. - -### Default Request Body - -If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows: - -```json -{ - "event": "created", - "timestamp": "2021-03-09 17:55:33.968016+00:00", - "model": "site", - "username": "jstretch", - "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a", - "data": { - "id": 19, - "name": "Site 1", - "slug": "site-1", - "status": - "value": "active", - "label": "Active", - "id": 1 - }, - "region": null, - ... - }, - "snapshots": { - "prechange": null, - "postchange": { - "created": "2021-03-09", - "last_updated": "2021-03-09T17:55:33.851Z", - "name": "Site 1", - "slug": "site-1", - "status": "active", - ... - } - } -} -``` - -## Conditional Webhooks - -A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": - -```json -{ - "and": [ - { - "attr": "status.value", - "value": "active" - } - ] -} -``` - -For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md). - -## Webhook Processing - -When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. - -A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. - -## Troubleshooting - -To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: - -```no-highlight -$ python netbox/manage.py webhook_receiver -Listening on port http://localhost:9000. Stop with CONTROL-C. -``` - -You can test the receiver itself by sending any HTTP request to it. For example: - -```no-highlight -$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' -``` - -The server will print output similar to the following: - -```no-highlight -[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - -Host: localhost:9000 -User-Agent: curl/7.58.0 -Accept: */* -Content-Length: 14 -Content-Type: application/x-www-form-urlencoded - -{"foo": "bar"} ------------- -``` - -Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. - -Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md new file mode 100644 index 000000000..bfe412edc --- /dev/null +++ b/docs/models/extras/customfield.md @@ -0,0 +1,109 @@ +# Custom Fields + +Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. + +However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. + +Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. + +## Creating Custom Fields + +Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: + +* Text: Free-form text (intended for single-line use) +* Long text: Free-form of any length; supports Markdown rendering +* Integer: A whole number (positive or negative) +* Boolean: True or false +* Date: A date in ISO 8601 format (YYYY-MM-DD) +* URL: This will be presented as a link in the web UI +* JSON: Arbitrary data stored in JSON format +* Selection: A selection of one of several pre-defined custom choices +* Multiple selection: A selection field which supports the assignment of multiple values +* Object: A single NetBox object of the type defined by `object_type` +* Multiple object: One or more NetBox objects of the type defined by `object_type` + +Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. + +Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. + +A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. + +### Filtering + +The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. + +### Grouping + +!!! note + This feature was introduced in NetBox v3.3. + +Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) + +This parameter has no effect on the API representation of custom field data. + +### Visibility + +!!! note + This feature was introduced in NetBox v3.3. + +When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. + +* **Read/write** (default): The custom field is included when viewing and editing objects. +* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. + +Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. + +### Validation + +NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: + +* Text: Regular expression (optional) +* Integer: Minimum and/or maximum value (optional) +* Selection: Must exactly match one of the prescribed choices + +### Custom Selection Fields + +Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. + +If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. + +### Custom Object Fields + +An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. + + +## Custom Fields in Templates + +Several features within NetBox, such as export templates and webhooks, utilize Jinja2 templating. For convenience, objects which support custom field assignment expose custom field data through the `cf` property. This is a bit cleaner than accessing custom field data through the actual field (`custom_field_data`). + +For example, a custom field named `foo123` on the Site model is accessible on an instance as `{{ site.cf.foo123 }}`. + +## Custom Fields and the REST API + +When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined: + +```json +{ + "id": 123, + "url": "http://localhost:8000/api/dcim/sites/123/", + "name": "Raleigh 42", + ... + "custom_fields": { + "deployed": "2018-06-19", + "site_code": "US-NC-RAL42" + }, + ... +``` + +To set or change these values, simply include nested JSON data. For example: + +```json +{ + "name": "New Site", + "slug": "new-site", + "custom_fields": { + "deployed": "2019-03-24" + } +} +``` diff --git a/docs/models/extras/customlink.md b/docs/models/extras/customlink.md new file mode 100644 index 000000000..16ba9d2af --- /dev/null +++ b/docs/models/extras/customlink.md @@ -0,0 +1,66 @@ +# Custom Links + +Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS). + +Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the NetBox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`. + +For example, you might define a link like this: + +* Text: `View NMS` +* URL: `https://nms.example.com/nodes/?name={{ obj.name }}` + +When viewing a device named Router4, this link would render as: + +```no-highlight +View NMS +``` + +Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually. + +!!! warning + Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users. + +## Context Data + +The following context data is available within the template when rendering a custom link's text or URL. + +| Variable | Description | +|-----------|-------------------------------------------------------------------------------------------------------------------| +| `object` | The NetBox object being displayed | +| `obj` | Same as `object`; maintained for backward compatability until NetBox v3.5 | +| `debug` | A boolean indicating whether debugging is enabled | +| `request` | The current WSGI request | +| `user` | The current user (if authenticated) | +| `perms` | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user | + +While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type. + +Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list. + +## Conditional Rendering + +Only links which render with non-empty text are included on the page. You can employ conditional Jinja2 logic to control the conditions under which a link gets rendered. + +For example, if you only want to display a link for active devices, you could set the link text to + +```jinja2 +{% if obj.status == 'active' %}View NMS{% endif %} +``` + +The link will not appear when viewing a device with any status other than "active." + +As another example, if you wanted to show only devices belonging to a certain manufacturer, you could do something like this: + +```jinja2 +{% if obj.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %} +``` + +The link will only appear when viewing a device with a manufacturer name of "Cisco." + +## Link Groups + +Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group. + +## Table Columns + +Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL. diff --git a/docs/models/extras/exporttemplate.md b/docs/models/extras/exporttemplate.md new file mode 100644 index 000000000..b4b69108a --- /dev/null +++ b/docs/models/extras/exporttemplate.md @@ -0,0 +1,81 @@ +# Export Templates + +NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. + +Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. + +Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). + +!!! note + The name `table` is reserved for internal use. + +!!! warning + Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. + +The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: + +```jinja2 +{% for rack in queryset %} +Rack: {{ rack.name }} +Site: {{ rack.site.name }} +Height: {{ rack.u_height }}U +{% endfor %} +``` + +To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. + +If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: +``` +{% for server in queryset %} +{% set data = server.get_config_context() %} +{{ data.syslog }} +{% endfor %} +``` + +The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) + +A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. + + +## REST API Integration + +When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: + +``` +GET /api/dcim/sites/?export=MyTemplateName +``` + +Note that the body of the response will contain only the rendered export template content, as opposed to a JSON object or list. + +## Example + +Here's an example device export template that will generate a simple Nagios configuration from a list of devices. + +``` +{% for device in queryset %}{% if device.status and device.primary_ip %}define host{ + use generic-switch + host_name {{ device.name }} + address {{ device.primary_ip.address.ip }} +} +{% endif %}{% endfor %} +``` + +The generated output will look something like this: + +``` +define host{ + use generic-switch + host_name switch1 + address 192.0.2.1 +} +define host{ + use generic-switch + host_name switch2 + address 192.0.2.2 +} +define host{ + use generic-switch + host_name switch3 + address 192.0.2.3 +} +``` diff --git a/docs/models/extras/imageattachment.md b/docs/models/extras/imageattachment.md new file mode 100644 index 000000000..da15462ab --- /dev/null +++ b/docs/models/extras/imageattachment.md @@ -0,0 +1,3 @@ +# Image Attachments + +Certain objects in NetBox support the attachment of uploaded images. These will be saved to the NetBox server and made available whenever the object is viewed. diff --git a/docs/models/extras/webhook.md b/docs/models/extras/webhook.md new file mode 100644 index 000000000..427ae3dd1 --- /dev/null +++ b/docs/models/extras/webhook.md @@ -0,0 +1,139 @@ +# Webhooks + +A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks. + +!!! warning + Webhooks support the inclusion of user-submitted code to generate URL, custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users. + +## Configuration + +* **Name** - A unique name for the webhook. The name is not included with outbound messages. +* **Object type(s)** - The type or types of NetBox object that will trigger the webhook. +* **Enabled** - If unchecked, the webhook will be inactive. +* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected. +* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. +* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field. +* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`) +* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below). +* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.) +* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key. +* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object. +* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!) +* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional). + +## Jinja2 Template Support + +[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands. + +For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration: + +* Object type: IPAM > IP address +* HTTP method: `POST` +* URL: Slack incoming webhook URL +* HTTP content type: `application/json` +* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}` + +### Available Context + +The following data is available as context for Jinja2 templates: + +* `event` - The type of event which triggered the webhook: created, updated, or deleted. +* `model` - The NetBox model which triggered the change. +* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). +* `username` - The name of the user account associated with the change. +* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request. +* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API. +* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed. + +### Default Request Body + +If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows: + +```json +{ + "event": "created", + "timestamp": "2021-03-09 17:55:33.968016+00:00", + "model": "site", + "username": "jstretch", + "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a", + "data": { + "id": 19, + "name": "Site 1", + "slug": "site-1", + "status": + "value": "active", + "label": "Active", + "id": 1 + }, + "region": null, + ... + }, + "snapshots": { + "prechange": null, + "postchange": { + "created": "2021-03-09", + "last_updated": "2021-03-09T17:55:33.851Z", + "name": "Site 1", + "slug": "site-1", + "status": "active", + ... + } + } +} +``` + +## Conditional Webhooks + +A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": + +```json +{ + "and": [ + { + "attr": "status.value", + "value": "active" + } + ] +} +``` + +For more detail, see the reference documentation for NetBox's [conditional logic](../../reference/conditions.md). + +## Webhook Processing + +When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. + +A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. + +## Troubleshooting + +To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: + +```no-highlight +$ python netbox/manage.py webhook_receiver +Listening on port http://localhost:9000. Stop with CONTROL-C. +``` + +You can test the receiver itself by sending any HTTP request to it. For example: + +```no-highlight +$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' +``` + +The server will print output similar to the following: + +```no-highlight +[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - +Host: localhost:9000 +User-Agent: curl/7.58.0 +Accept: */* +Content-Length: 14 +Content-Type: application/x-www-form-urlencoded + +{"foo": "bar"} +------------ +``` + +Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. + +Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/mkdocs.yml b/mkdocs.yml index 95672cede..a5eb36d81 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -191,7 +191,12 @@ nav: - VirtualChassis: 'models/dcim/virtualchassis.md' - Extras: - ConfigContext: 'models/extras/configcontext.md' + - CustomField: 'models/extras/customfield.md' + - CustomLink: 'models/extras/customlink.md' + - ExportTemplate: 'models/extras/exporttemplate.md' + - ImageAttachment: 'models/extras/imageattachment.md' - Tag: 'models/extras/tag.md' + - Webhook: 'models/extras/webhook.md' - IPAM: - ASN: 'models/ipam/asn.md' - Aggregate: 'models/ipam/aggregate.md' From a7b78565a199c6c5d1459decdd0d0019a743e974 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 11:55:45 -0400 Subject: [PATCH 13/28] Split webhooks documentation --- docs/integrations/webhooks.md | 127 ++++++++++++++++++++++++++++++++++ docs/models/extras/webhook.md | 122 +------------------------------- 2 files changed, 128 insertions(+), 121 deletions(-) diff --git a/docs/integrations/webhooks.md b/docs/integrations/webhooks.md index e69de29bb..3ef28fb11 100644 --- a/docs/integrations/webhooks.md +++ b/docs/integrations/webhooks.md @@ -0,0 +1,127 @@ +# Webhooks + +NetBox can be configured to transmit outgoing webhooks to remote systems in response to internal object changes. The receiver can act on the data in these webhook messages to perform related tasks. + +For example, suppose you want to automatically configure a monitoring system to start monitoring a device when its operational status is changed to active, and remove it from monitoring for any other status. You can create a webhook in NetBox for the device model and craft its content and destination URL to effect the desired change on the receiving system. Webhooks will be sent automatically by NetBox whenever the configured constraints are met. + +Each webhook must be associated with at least one NetBox object type and at least one event (create, update, or delete). Users can specify the receiver URL, HTTP request type (`GET`, `POST`, etc.), content type, and headers. A request body can also be specified; if left blank, this will default to a serialized representation of the affected object. + +!!! warning "Security Notice" + Webhooks support the inclusion of user-submitted code to generate the URL, custom headers, and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users. + +## Jinja2 Template Support + +[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands. + +For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration: + +* Object type: IPAM > IP address +* HTTP method: `POST` +* URL: Slack incoming webhook URL +* HTTP content type: `application/json` +* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}` + +### Available Context + +The following data is available as context for Jinja2 templates: + +* `event` - The type of event which triggered the webhook: created, updated, or deleted. +* `model` - The NetBox model which triggered the change. +* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). +* `username` - The name of the user account associated with the change. +* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request. +* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API. +* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed. + +### Default Request Body + +If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows: + +```json +{ + "event": "created", + "timestamp": "2021-03-09 17:55:33.968016+00:00", + "model": "site", + "username": "jstretch", + "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a", + "data": { + "id": 19, + "name": "Site 1", + "slug": "site-1", + "status": + "value": "active", + "label": "Active", + "id": 1 + }, + "region": null, + ... + }, + "snapshots": { + "prechange": null, + "postchange": { + "created": "2021-03-09", + "last_updated": "2021-03-09T17:55:33.851Z", + "name": "Site 1", + "slug": "site-1", + "status": "active", + ... + } + } +} +``` + +## Conditional Webhooks + +A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": + +```json +{ + "and": [ + { + "attr": "status.value", + "value": "active" + } + ] +} +``` + +For more detail, see the reference documentation for NetBox's [conditional logic](../../reference/conditions.md). + +## Webhook Processing + +When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. + +A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. + +## Troubleshooting + +To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: + +```no-highlight +$ python netbox/manage.py webhook_receiver +Listening on port http://localhost:9000. Stop with CONTROL-C. +``` + +You can test the receiver itself by sending any HTTP request to it. For example: + +```no-highlight +$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' +``` + +The server will print output similar to the following: + +```no-highlight +[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - +Host: localhost:9000 +User-Agent: curl/7.58.0 +Accept: */* +Content-Length: 14 +Content-Type: application/x-www-form-urlencoded + +{"foo": "bar"} +------------ +``` + +Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. + +Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/docs/models/extras/webhook.md b/docs/models/extras/webhook.md index 427ae3dd1..2d598f8ae 100644 --- a/docs/models/extras/webhook.md +++ b/docs/models/extras/webhook.md @@ -2,10 +2,7 @@ A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks. -!!! warning - Webhooks support the inclusion of user-submitted code to generate URL, custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users. - -## Configuration +## Model Fields * **Name** - A unique name for the webhook. The name is not included with outbound messages. * **Object type(s)** - The type or types of NetBox object that will trigger the webhook. @@ -20,120 +17,3 @@ A webhook is a mechanism for conveying to some external system a change that too * **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object. * **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!) * **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional). - -## Jinja2 Template Support - -[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands. - -For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration: - -* Object type: IPAM > IP address -* HTTP method: `POST` -* URL: Slack incoming webhook URL -* HTTP content type: `application/json` -* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}` - -### Available Context - -The following data is available as context for Jinja2 templates: - -* `event` - The type of event which triggered the webhook: created, updated, or deleted. -* `model` - The NetBox model which triggered the change. -* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). -* `username` - The name of the user account associated with the change. -* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request. -* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API. -* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed. - -### Default Request Body - -If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows: - -```json -{ - "event": "created", - "timestamp": "2021-03-09 17:55:33.968016+00:00", - "model": "site", - "username": "jstretch", - "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a", - "data": { - "id": 19, - "name": "Site 1", - "slug": "site-1", - "status": - "value": "active", - "label": "Active", - "id": 1 - }, - "region": null, - ... - }, - "snapshots": { - "prechange": null, - "postchange": { - "created": "2021-03-09", - "last_updated": "2021-03-09T17:55:33.851Z", - "name": "Site 1", - "slug": "site-1", - "status": "active", - ... - } - } -} -``` - -## Conditional Webhooks - -A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": - -```json -{ - "and": [ - { - "attr": "status.value", - "value": "active" - } - ] -} -``` - -For more detail, see the reference documentation for NetBox's [conditional logic](../../reference/conditions.md). - -## Webhook Processing - -When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. - -A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. - -## Troubleshooting - -To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: - -```no-highlight -$ python netbox/manage.py webhook_receiver -Listening on port http://localhost:9000. Stop with CONTROL-C. -``` - -You can test the receiver itself by sending any HTTP request to it. For example: - -```no-highlight -$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' -``` - -The server will print output similar to the following: - -```no-highlight -[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - -Host: localhost:9000 -User-Agent: curl/7.58.0 -Accept: */* -Content-Length: 14 -Content-Type: application/x-www-form-urlencoded - -{"foo": "bar"} ------------- -``` - -Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. - -Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). From f9fb2cc69827559d7934718b3eb84806c278510b Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 15:29:26 -0400 Subject: [PATCH 14/28] Finish features documentation --- docs/development/models.md | 2 +- .../{integrations.md => api-integration.md} | 2 +- docs/features/authentication-permissions.md | 49 +++++++++++++++++++ docs/features/customization.md | 41 ++++++++++++++-- docs/features/permissions.md | 3 -- docs/features/sso.md | 3 -- docs/features/tags.md | 0 docs/integrations/webhooks.md | 2 +- mkdocs.yml | 10 ++-- 9 files changed, 92 insertions(+), 20 deletions(-) rename docs/features/{integrations.md => api-integration.md} (99%) create mode 100644 docs/features/authentication-permissions.md delete mode 100644 docs/features/permissions.md delete mode 100644 docs/features/sso.md delete mode 100644 docs/features/tags.md diff --git a/docs/development/models.md b/docs/development/models.md index 3c7aaaa78..3b03c8935 100644 --- a/docs/development/models.md +++ b/docs/development/models.md @@ -12,7 +12,7 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/ * [Webhooks](../integrations/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects * [Custom fields](../customization/custom-fields.md) - These models support the addition of user-defined fields * [Export templates](../customization/export-templates.md) - Users can create custom export templates for these models -* [Tagging](../features/tags.md) - The models can be tagged with user-defined tags +* [Tagging](../models/extras/tag.md) - The models can be tagged with user-defined tags * [Journaling](../features/journaling.md) - These models support persistent historical commentary * Nesting - These models can be nested recursively to create a hierarchy diff --git a/docs/features/integrations.md b/docs/features/api-integration.md similarity index 99% rename from docs/features/integrations.md rename to docs/features/api-integration.md index c2f68c5c8..50c31ec4f 100644 --- a/docs/features/integrations.md +++ b/docs/features/api-integration.md @@ -1,4 +1,4 @@ -# Integrations +# API & Integration NetBox includes a slew of features which enable integration with other tools and resources powering your network. diff --git a/docs/features/authentication-permissions.md b/docs/features/authentication-permissions.md new file mode 100644 index 000000000..14e13d5cd --- /dev/null +++ b/docs/features/authentication-permissions.md @@ -0,0 +1,49 @@ +# Authentication & Permissions + +## Object-Based Permissions + +NetBox boasts a very robust permissions system which extends well beyond the model-based permissions of the underlying Django framework. Assigning permissions in NetBox involves several dimensions: + +* The type(s) of object to which the permission applies +* The users and/or groups being granted the permissions +* The action(s) permitted by the permission (e.g. view, add, change, etc.) +* Any constraints limiting application of the permission to a particular subset of objects + +The implementation of constrains is what enables NetBox administrators to assign per-object permissions: Users can be limited to viewing or interacting with arbitrary subsets of objects based on the objects' attributes. For example, you might restrict a particular user to viewing only those prefixes or IP addresses within a particular VRF. Or you might restrict a group to modifying devices within a particular region. + +Permission constraints are declared in JSON format when creating a permission, and operate very similarly to Django ORM queries. For instance, here's a constraint that matches reserved VLANs with a VLAN ID between 100 and 199: + +```json +[ + { + "vid__gte": 100, + "vid__lt": 200 + }, + { + "status": "reserved" + } +] +``` + +Check out the [permissions documentation](../administration/permissions.md) for more information about permission constraints. + +## LDAP Authentication + +NetBox includes a built-in authentication backend for authenticating users against a remote LDAP server. The [installation documentation](../installation/6-ldap.md) provides more detail on this capability. + +## Single Sign-On (SSO) + +NetBox integrates with the open source [python-social-auth](https://github.com/python-social-auth) library to provide [myriad options](https://python-social-auth.readthedocs.io/en/latest/backends/index.html#supported-backends) for single sign-on (SSO) authentication. These include: + +* Cognito +* GitHub & GitHub Enterprise +* GitLab +* Google +* Hashicorp Vault +* Keycloak +* Microsoft Azure AD +* Microsoft Graph +* Okta +* OIDC + +...and many others. It's also possible to build your own custom backends as needed using python-social-auth's base OAuth, OpenID, and SAML classes. You can find some examples of configuring SSO in NetBox' [authentication documentation](../administration/authentication/overview.md). diff --git a/docs/features/customization.md b/docs/features/customization.md index 5b42d5e43..d7f2cf40a 100644 --- a/docs/features/customization.md +++ b/docs/features/customization.md @@ -2,6 +2,10 @@ While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs. +## Tags + +Most objects in NetBox can be assigned user-created tags to aid with organization and filtering. Tag values are completely arbitrary: They may be used to store data in key-value pairs, or they may be employed simply as labels against which objects can be filtered. Each tag can also be assigned a color for quicker differentiation in the user interface. + ## Custom Fields While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs. @@ -12,30 +16,57 @@ To learn more about this feature, check out the [custom field documentation](../ ## Custom Links -TODO +Custom links allow you to conveniently reference external resources related to NetBox objects from within the NetBox UI. For example, you might wish to link each virtual machine modeled in NetBox to its corresponding view in some orchestration application. You can do this by creating a templatized custom link for the virtual machine model, specifying something like the following for the link URL: + +```no-highlight +http://server.local/vms/?name={{ object.name }} +``` + +Now, when viewing a virtual machine in NetBox, a user will see a handy button with the chosen title and link (complete with the name of the VM being viewed). Both the text and URL of custom links can be templatized in this manner, and custom links can be grouped together into dropdowns for more efficient display. To learn more about this feature, check out the [custom link documentation](../customization/custom-links.md). ## Custom Validation -TODO +While NetBox employs robust built-in object validation to ensure the integrity of its database, you might wish to enforce additional rules governing the creation and modification of certain objects. For example, perhaps you require that every device defined in NetBox adheres to a particular naming scheme and includes an asset tag. You can configure a custom validation rule in NetBox to enforce these requirements for the device model: + +```python +CUSTOM_VALIDATORS = { + "dcim.device": [ + { + "name": { + "regex": "[a-z]+\d{3}" + }, + "asset_tag": { + "required": True + } + } + ] +} +``` To learn more about this feature, check out the [custom validation documentation](../customization/custom-validation.md). ## Export Templates -TODO +Most NetBox objects can be exported in bulk in two built-in CSV formats: The current view (what the user currently sees in the objects list), or all available data. NetBox also provides the capability to define your own custom data export formats via export templates. An export template is essentially [Jinja2](https://jinja.palletsprojects.com/) template code associated with a particular object type. From the objects list in the NetBox UI, a user can select any of the created export templates to export the objects according to the template logic. + +An export template doesn't have to render CSV data: Its output can be in any character-based format. For example, you might want to render data using tabs as delimiters, or even create DNS address records directly from the IP addresses list. Export templates are a great way to get the data you need in the format you need quickly. To learn more about this feature, check out the [export template documentation](../customization/export-templates.md). ## Reports -TODO +NetBox administrators can install custom Python scripts, known as _reports_, which run within NetBox and can be executed and analyzed within the NetBox UI. Reports are a great way to evaluate NetBox objects against a set of arbitrary rules. For example, you could write a report to check that every router has a loopback interface with an IP address assigned, or that every site has a minimum set of VLANs defined. + +When a report runs, its logs messages pertaining to the operations being performed, and will ultimately result in either a pass or fail. Reports can be executed via the UI, REST API, or CLI (as a management command). To learn more about this feature, check out the [documentation for reports](../customization/reports.md). ## Custom Scripts -TODO +Custom scripts are similar to reports, but more powerful. A custom script can prompt the user for input via a form (or API data), and is built to do much more than just reporting. Custom scripts are generally used to automate tasks, such as the population of new objects in NetBox, or exchanging data with external systems. + +The complete Python environment is available to a custom script, including all of NetBox's internal mechanisms: There are no artificial restrictions on what a script can do. As such, custom scripting is considered an advanced feature and requires sufficient familiarity with Python and NetBox's data model. To learn more about this feature, check out the [documentation for custom scripts](../customization/custom-scripts.md). diff --git a/docs/features/permissions.md b/docs/features/permissions.md deleted file mode 100644 index a422ca7b3..000000000 --- a/docs/features/permissions.md +++ /dev/null @@ -1,3 +0,0 @@ -# Object-Based Permissions - -TODO diff --git a/docs/features/sso.md b/docs/features/sso.md deleted file mode 100644 index b4f9782c2..000000000 --- a/docs/features/sso.md +++ /dev/null @@ -1,3 +0,0 @@ -# Single Sign-On (SSO) - -TODO diff --git a/docs/features/tags.md b/docs/features/tags.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/integrations/webhooks.md b/docs/integrations/webhooks.md index 3ef28fb11..9a1094988 100644 --- a/docs/integrations/webhooks.md +++ b/docs/integrations/webhooks.md @@ -85,7 +85,7 @@ A webhook may include a set of conditional logic expressed in JSON used to contr } ``` -For more detail, see the reference documentation for NetBox's [conditional logic](../../reference/conditions.md). +For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md). ## Webhook Processing diff --git a/mkdocs.yml b/mkdocs.yml index a5eb36d81..8bcf6cebf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,8 +61,6 @@ nav: - Introduction: 'introduction.md' - Features: - Facilities: 'features/facilities.md' - - Tenancy: 'features/tenancy.md' - - Contacts: 'features/contacts.md' - Devices & Cabling: 'features/devices-cabling.md' - Power Tracking: 'features/power-tracking.md' - IPAM: 'features/ipam.md' @@ -70,14 +68,14 @@ nav: - L2VPN & Overlay: 'features/l2vpn-overlay.md' - Circuits: 'features/circuits.md' - Wireless: 'features/wireless.md' + - Tenancy: 'features/tenancy.md' + - Contacts: 'features/contacts.md' - Context Data: 'features/context-data.md' - Change Logging: 'features/change-logging.md' - Journaling: 'features/journaling.md' - - Tags: 'features/tags.md' - - Integrations: 'features/integrations.md' + - Auth & Permissions: 'features/authentication-permissions.md' + - API & Integration: 'features/api-integration.md' - Customization: 'features/customization.md' - - Object-Based Permissions: 'features/permissions.md' - - Single Sign-On (SSO): 'features/sso.md' - Installation & Upgrade: - Installing NetBox: 'installation/index.md' - 1. PostgreSQL: 'installation/1-postgresql.md' From 0750e27351db01161b74fa7417410ae9bdead423 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 16:14:06 -0400 Subject: [PATCH 15/28] Finish customization docs --- docs/customization/custom-fields.md | 108 +++++++++++++++++++++ docs/customization/custom-links.md | 66 +++++++++++++ docs/customization/export-templates.md | 81 ++++++++++++++++ docs/models/extras/customfield.md | 128 +++++++++++-------------- docs/models/extras/customlink.md | 94 ++++++++---------- docs/models/extras/exporttemplate.md | 80 +++------------- 6 files changed, 365 insertions(+), 192 deletions(-) diff --git a/docs/customization/custom-fields.md b/docs/customization/custom-fields.md index e69de29bb..c443fa9f6 100644 --- a/docs/customization/custom-fields.md +++ b/docs/customization/custom-fields.md @@ -0,0 +1,108 @@ +# Custom Fields + +Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. + +However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. + +Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. + +## Creating Custom Fields + +Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports many types of custom field: + +* Text: Free-form text (intended for single-line use) +* Long text: Free-form of any length; supports Markdown rendering +* Integer: A whole number (positive or negative) +* Boolean: True or false +* Date: A date in ISO 8601 format (YYYY-MM-DD) +* URL: This will be presented as a link in the web UI +* JSON: Arbitrary data stored in JSON format +* Selection: A selection of one of several pre-defined custom choices +* Multiple selection: A selection field which supports the assignment of multiple values +* Object: A single NetBox object of the type defined by `object_type` +* Multiple object: One or more NetBox objects of the type defined by `object_type` + +Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. + +Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. + +A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. + +### Filtering + +The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. + +### Grouping + +!!! note + This feature was introduced in NetBox v3.3. + +Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) + +This parameter has no effect on the API representation of custom field data. + +### Visibility + +!!! note + This feature was introduced in NetBox v3.3. + +When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. + +* **Read/write** (default): The custom field is included when viewing and editing objects. +* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. + +Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. + +### Validation + +NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: + +* Text: Regular expression (optional) +* Integer: Minimum and/or maximum value (optional) +* Selection: Must exactly match one of the prescribed choices + +### Custom Selection Fields + +Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. + +If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. + +### Custom Object Fields + +An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. + +## Custom Fields in Templates + +Several features within NetBox, such as export templates and webhooks, utilize Jinja2 templating. For convenience, objects which support custom field assignment expose custom field data through the `cf` property. This is a bit cleaner than accessing custom field data through the actual field (`custom_field_data`). + +For example, a custom field named `foo123` on the Site model is accessible on an instance as `{{ site.cf.foo123 }}`. + +## Custom Fields and the REST API + +When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined: + +```json +{ + "id": 123, + "url": "http://localhost:8000/api/dcim/sites/123/", + "name": "Raleigh 42", + ... + "custom_fields": { + "deployed": "2018-06-19", + "site_code": "US-NC-RAL42" + }, + ... +``` + +To set or change these values, simply include nested JSON data. For example: + +```json +{ + "name": "New Site", + "slug": "new-site", + "custom_fields": { + "deployed": "2019-03-24" + } +} +``` diff --git a/docs/customization/custom-links.md b/docs/customization/custom-links.md index e69de29bb..16ba9d2af 100644 --- a/docs/customization/custom-links.md +++ b/docs/customization/custom-links.md @@ -0,0 +1,66 @@ +# Custom Links + +Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS). + +Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the NetBox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`. + +For example, you might define a link like this: + +* Text: `View NMS` +* URL: `https://nms.example.com/nodes/?name={{ obj.name }}` + +When viewing a device named Router4, this link would render as: + +```no-highlight +View NMS +``` + +Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually. + +!!! warning + Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users. + +## Context Data + +The following context data is available within the template when rendering a custom link's text or URL. + +| Variable | Description | +|-----------|-------------------------------------------------------------------------------------------------------------------| +| `object` | The NetBox object being displayed | +| `obj` | Same as `object`; maintained for backward compatability until NetBox v3.5 | +| `debug` | A boolean indicating whether debugging is enabled | +| `request` | The current WSGI request | +| `user` | The current user (if authenticated) | +| `perms` | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user | + +While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type. + +Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list. + +## Conditional Rendering + +Only links which render with non-empty text are included on the page. You can employ conditional Jinja2 logic to control the conditions under which a link gets rendered. + +For example, if you only want to display a link for active devices, you could set the link text to + +```jinja2 +{% if obj.status == 'active' %}View NMS{% endif %} +``` + +The link will not appear when viewing a device with any status other than "active." + +As another example, if you wanted to show only devices belonging to a certain manufacturer, you could do something like this: + +```jinja2 +{% if obj.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %} +``` + +The link will only appear when viewing a device with a manufacturer name of "Cisco." + +## Link Groups + +Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group. + +## Table Columns + +Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL. diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index e69de29bb..640a97531 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -0,0 +1,81 @@ +# Export Templates + +NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. + +Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. + +Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). + +!!! note + The name `table` is reserved for internal use. + +!!! warning + Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. + +The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: + +```jinja2 +{% for rack in queryset %} +Rack: {{ rack.name }} +Site: {{ rack.site.name }} +Height: {{ rack.u_height }}U +{% endfor %} +``` + +To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. + +If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: +``` +{% for server in queryset %} +{% set data = server.get_config_context() %} +{{ data.syslog }} +{% endfor %} +``` + +The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) + +A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. + + +## REST API Integration + +When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: + +``` +GET /api/dcim/sites/?export=MyTemplateName +``` + +Note that the body of the response will contain only the rendered export template content, as opposed to a JSON object or list. + +## Example + +Here's an example device export template that will generate a simple Nagios configuration from a list of devices. + +``` +{% for device in queryset %}{% if device.status and device.primary_ip %}define host{ + use generic-switch + host_name {{ device.name }} + address {{ device.primary_ip.address.ip }} +} +{% endif %}{% endfor %} +``` + +The generated output will look something like this: + +``` +define host{ + use generic-switch + host_name switch1 + address 192.0.2.1 +} +define host{ + use generic-switch + host_name switch2 + address 192.0.2.2 +} +define host{ + use generic-switch + host_name switch3 + address 192.0.2.3 +} +``` diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md index bfe412edc..0b2bc29f9 100644 --- a/docs/models/extras/customfield.md +++ b/docs/models/extras/customfield.md @@ -1,109 +1,93 @@ # Custom Fields -Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. +## Fields -However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. +### Model(s) -Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. +Select the NetBox object type or types to which this custom field applies. -## Creating Custom Fields +### Name -Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: +The raw field name. This will be used in the database and API, and should consist only of alphanumeric characters and underscores. (Use the `label` field to designate a human-friendly name for the custom field.) -* Text: Free-form text (intended for single-line use) -* Long text: Free-form of any length; supports Markdown rendering -* Integer: A whole number (positive or negative) -* Boolean: True or false -* Date: A date in ISO 8601 format (YYYY-MM-DD) -* URL: This will be presented as a link in the web UI -* JSON: Arbitrary data stored in JSON format -* Selection: A selection of one of several pre-defined custom choices -* Multiple selection: A selection field which supports the assignment of multiple values -* Object: A single NetBox object of the type defined by `object_type` -* Multiple object: One or more NetBox objects of the type defined by `object_type` +### Label -Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. +An optional human-friendly name for the custom field. If not defined, the field's `name` attribute will be used. -Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. +### Group Name -A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. +If this custom field should be grouped with others, specify the name of the group here. Custom fields with no group defined will be ordered only by weight and name. -### Filtering +### Type -The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. +The type of data this field holds. This must be one of the following: -### Grouping +| Type | Description | +|--------------------|--------------------------------------------------------------------| +| Text | Free-form text (intended for single-line use) | +| Long text | Free-form of any length; supports Markdown rendering | +| Integer | A whole number (positive or negative) | +| Boolean | True or false | +| Date | A date in ISO 8601 format (YYYY-MM-DD) | +| URL | This will be presented as a link in the web UI | +| JSON | Arbitrary data stored in JSON format | +| Selection | A selection of one of several pre-defined custom choices | +| Multiple selection | A selection field which supports the assignment of multiple values | +| Object | A single NetBox object of the type defined by `object_type` | +| Multiple object | One or more NetBox objects of the type defined by `object_type` | -!!! note - This feature was introduced in NetBox v3.3. +### Object Type -Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) +For object and multiple-object fields only. Designates the type of NetBox object being referenced. -This parameter has no effect on the API representation of custom field data. +### Weight -### Visibility +A numeric weight used to override alphabetic ordering of fields by name. Custom fields with a lower weight will be listed before those with a higher weight. (Note that weight applies within the context of a custom field group, if defined.) -!!! note - This feature was introduced in NetBox v3.3. +### Required -When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. +If checked, this custom field must be populated with a valid value for the object to pass validation. -* **Read/write** (default): The custom field is included when viewing and editing objects. -* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) -* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. +### Description -Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. +A brief description of the field's purpose (optional). -### Validation +### Filter Logic -NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: +Defines how filters are evaluated against custom field values. -* Text: Regular expression (optional) -* Integer: Minimum and/or maximum value (optional) -* Selection: Must exactly match one of the prescribed choices +| Option | Description | +|----------|-------------------------------------| +| Disabled | Filtering disabled | +| Loose | Match any occurrence of the value | +| Exact | Match only the complete field value | -### Custom Selection Fields +### UI Visibility -Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. +Controls how and whether the custom field is displayed within the NetBox user interface. -If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. +| Option | Description | +|------------|--------------------------------------| +| Read/write | Display and permit editing (default) | +| Read-only | Display field but disallow editing | +| Hidden | Do not display field in the UI | -### Custom Object Fields +### Default -An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. +The default value to populate for the custom field when creating new objects (optional). This value must be expressed as JSON. If this is a choice or multi-choice field, this must be one of the available choices. +### Choices -## Custom Fields in Templates +For choice and multi-choice custom fields only. A comma-delimited list of the available choices. -Several features within NetBox, such as export templates and webhooks, utilize Jinja2 templating. For convenience, objects which support custom field assignment expose custom field data through the `cf` property. This is a bit cleaner than accessing custom field data through the actual field (`custom_field_data`). +### Minimum Value -For example, a custom field named `foo123` on the Site model is accessible on an instance as `{{ site.cf.foo123 }}`. +For numeric custom fields only. The minimum valid value (optional). -## Custom Fields and the REST API +### Maximum Value -When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined: +For numeric custom fields only. The maximum valid value (optional). -```json -{ - "id": 123, - "url": "http://localhost:8000/api/dcim/sites/123/", - "name": "Raleigh 42", - ... - "custom_fields": { - "deployed": "2018-06-19", - "site_code": "US-NC-RAL42" - }, - ... -``` +### Validation Regex -To set or change these values, simply include nested JSON data. For example: - -```json -{ - "name": "New Site", - "slug": "new-site", - "custom_fields": { - "deployed": "2019-03-24" - } -} -``` +For string-based custom fields only. A regular expression used to validate the field's value (optional). diff --git a/docs/models/extras/customlink.md b/docs/models/extras/customlink.md index 16ba9d2af..458007ab1 100644 --- a/docs/models/extras/customlink.md +++ b/docs/models/extras/customlink.md @@ -1,66 +1,54 @@ # Custom Links -Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS). +## Fields -Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the NetBox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`. +### Name -For example, you might define a link like this: +The name of the custom link. This is used primarily for administrative purposes only, although custom links of the same weight are ordered alphabetically by name when being rendered in the UI. -* Text: `View NMS` -* URL: `https://nms.example.com/nodes/?name={{ obj.name }}` +### Content Type -When viewing a device named Router4, this link would render as: +The type of NetBox object to which this custom link applies. -```no-highlight -View NMS -``` +### Weight -Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually. +A numeric weight used to override alphabetic ordering of links by name. Custom fields with a lower weight will be listed before those with a higher weight. (Note that weight applies within the context of a custom link group, if defined.) -!!! warning - Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users. +### Group Name + +If this custom link should be grouped with others, specify the name of the group here. Grouped custom links will be listed in a dropdown menu attached to a single button bearing the group name. + +### Button Class + +The color of the UI button. + +### Enabled + +If not selected, the custom link will not be rendered. This can be useful for temporarily disabling a custom link. + +### New Window + +If selected, this will force the link to open in a new browser tab or window. + +### Link Text + +Jinja2 template code for rendering the button text. (Note that this does not _need_ to contain any template variables.) See below for available context data. + +!!! note + Custom links which render an empty text value will not be displayed in the UI. This can be used to toggle the inclusion of a link based on object attributes. + +### Link URL + +Jinja2 template code for rendering the hyperlink. See below for available context data. ## Context Data -The following context data is available within the template when rendering a custom link's text or URL. +The following context variables are available in to the text and link templates. -| Variable | Description | -|-----------|-------------------------------------------------------------------------------------------------------------------| -| `object` | The NetBox object being displayed | -| `obj` | Same as `object`; maintained for backward compatability until NetBox v3.5 | -| `debug` | A boolean indicating whether debugging is enabled | -| `request` | The current WSGI request | -| `user` | The current user (if authenticated) | -| `perms` | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user | - -While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type. - -Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list. - -## Conditional Rendering - -Only links which render with non-empty text are included on the page. You can employ conditional Jinja2 logic to control the conditions under which a link gets rendered. - -For example, if you only want to display a link for active devices, you could set the link text to - -```jinja2 -{% if obj.status == 'active' %}View NMS{% endif %} -``` - -The link will not appear when viewing a device with any status other than "active." - -As another example, if you wanted to show only devices belonging to a certain manufacturer, you could do something like this: - -```jinja2 -{% if obj.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %} -``` - -The link will only appear when viewing a device with a manufacturer name of "Cisco." - -## Link Groups - -Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group. - -## Table Columns - -Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL. +| Variable | Description | +|-----------|-----------------------------------------------------------------------------| +| `object` | The NetBox object being displayed | +| `debug` | A boolean indicating whether debugging is enabled | +| `request` | The current WSGI request | +| `user` | The current user (if authenticated) | +| `perms` | The [permissions](../../administration/permissions.md) assigned to the user | diff --git a/docs/models/extras/exporttemplate.md b/docs/models/extras/exporttemplate.md index b4b69108a..347184324 100644 --- a/docs/models/extras/exporttemplate.md +++ b/docs/models/extras/exporttemplate.md @@ -1,81 +1,27 @@ # Export Templates -NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. +## Fields -Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. +### Name -Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). +The name of the export template. This will appear in the "export" dropdown list in the NetBox UI. -!!! note - The name `table` is reserved for internal use. +### Content Type -!!! warning - Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. +The type of NetBox object to which the export template applies. -The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: +### Template Code -```jinja2 -{% for rack in queryset %} -Rack: {{ rack.name }} -Site: {{ rack.site.name }} -Height: {{ rack.u_height }}U -{% endfor %} -``` +Jinja2 template code for rendering the exported data. -To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. +### MIME Type -If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: -``` -{% for server in queryset %} -{% set data = server.get_config_context() %} -{{ data.syslog }} -{% endfor %} -``` +The MIME type to indicate in the response when rendering the export template (optional). Defaults to `text/plain`. -The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) +### File Extension -A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. +The file extension to append to the file name in the response (optional). +### As Attachment -## REST API Integration - -When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: - -``` -GET /api/dcim/sites/?export=MyTemplateName -``` - -Note that the body of the response will contain only the rendered export template content, as opposed to a JSON object or list. - -## Example - -Here's an example device export template that will generate a simple Nagios configuration from a list of devices. - -``` -{% for device in queryset %}{% if device.status and device.primary_ip %}define host{ - use generic-switch - host_name {{ device.name }} - address {{ device.primary_ip.address.ip }} -} -{% endif %}{% endfor %} -``` - -The generated output will look something like this: - -``` -define host{ - use generic-switch - host_name switch1 - address 192.0.2.1 -} -define host{ - use generic-switch - host_name switch2 - address 192.0.2.2 -} -define host{ - use generic-switch - host_name switch3 - address 192.0.2.3 -} -``` +If selected, the rendered content will be returned as a file attachment, rather than displayed directly in-browser (where supported). From 7e3050cf83e729ed43a9e591e7dd937c7a98febb Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 16:34:29 -0400 Subject: [PATCH 16/28] Add "getting started" links --- docs/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index a6bbcecff..d412d1a49 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,7 +24,7 @@ Unlike general-purpose CMDBs, NetBox has curated a data model which caters speci ## Customizable & Extensible -In addition to its expansive and robust data model, NetBox offers myriad mechanisms through it can be customized and extended. +In addition to its expansive and robust data model, NetBox offers myriad mechanisms through which it can be customized and extended. * Custom fields * Custom model validation @@ -39,10 +39,10 @@ Because NetBox is an open source application licensed under [Apache 2](https://w ## Getting Started -* Public Demo -* Installation Guide -* Docker install -* NetBox Cloud +* Try out our [public demo](https://demo.netbox.dev/) if you want to jump right in +* The [installation guide](./installation/index.md) will help you get your own deployment up and running +* Or try the community [Docker image](https://github.com/netbox-community/netbox-docker) for a low-touch approach +* [NetBox Cloud](https://www.getnetbox.io/) is a hosted solution offered by NS1 !!! tip "NetBox Development" Interested in contributing to NetBox? Check out our [GitHub repository](https://github.com/netbox-community/netbox) to get started! From 642fe422c458d4e5f3409c827100c2f2ac60c920 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 13:39:07 -0400 Subject: [PATCH 17/28] Touch up intro page --- docs/index.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/index.md b/docs/index.md index d412d1a49..c233dedb7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,16 +2,16 @@ # The Premiere Network Source of Truth -NetBox is the leading solution for modeling modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. +NetBox is the leading solution for modeling and documenting modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. Read on to discover why thousands of organizations worldwide put NetBox at the heart of their infrastructure. -## Built for Networks +## :material-server-network: Built for Networks -Unlike general-purpose CMDBs, NetBox has curated a data model which caters specifically to the needs of network engineers and operators. It delivers a wide assortment of object types carefully crafted to best serve the needs of network engineers and operators. These cover all facets of network design, from IP address managements to cabling to overlays and more: +Unlike general-purpose CMDBs, NetBox has curated a data model which caters specifically to the needs of network engineers and operators. It delivers a wide assortment of object types carefully crafted to best serve the needs of infrastructure design and documentation. These cover all facets of network technology, from IP address managements to cabling to overlays and more: -* Hierarchical regions, site groups, sites, and locations +* Hierarchical regions, sites, and locations * Racks, devices, and device components * Cables and wireless connections -* Power distribution +* Power distribution tracking * Data circuits and providers * Virtual machines and clusters * IP prefixes, ranges, and addresses @@ -20,11 +20,12 @@ Unlike general-purpose CMDBs, NetBox has curated a data model which caters speci * AS numbers * VLANs and scoped VLAN groups * L2VPN overlays -* Organizational tenants and contacts +* Tenancy assignments +* Contact management -## Customizable & Extensible +## :material-hammer-wrench: Customizable & Extensible -In addition to its expansive and robust data model, NetBox offers myriad mechanisms through which it can be customized and extended. +In addition to its expansive and robust data model, NetBox offers myriad mechanisms through which it can be customized and extended. Its powerful plugins architecture enables users to extend the application to meet their needs with minimal development effort. * Custom fields * Custom model validation @@ -33,16 +34,20 @@ In addition to its expansive and robust data model, NetBox offers myriad mechani * Plugins * REST & GraphQL APIs -## Always Open +## :material-lock-open: Always Open -Because NetBox is an open source application licensed under [Apache 2](https://www.apache.org/licenses/LICENSE-2.0.html), its entire code base is completely accessible to the end user, and there's never a risk of vendor lock-out. Additionally, NetBox development is an entirely public, community-driven process to which everyone can provide input. +Because NetBox is an open source application licensed under [Apache 2](https://www.apache.org/licenses/LICENSE-2.0.html), its entire code base is completely accessible to the end user, and there's never a risk of vendor lock-in. Additionally, NetBox development is an entirely public, community-driven process to which everyone can provide input. -## Getting Started +!!! tip "NetBox Development" + Interested in contributing to NetBox? Check out our [GitHub repository](https://github.com/netbox-community/netbox) to get started! + +## :material-language-python: Powered by Python + +NetBox is built on the enormously popular [Django](http://www.djangoproject.com/) framework for the Python programming language, already a favorite among network engineers. Users can leverage their existing skills coding Python tools to extend NetBox's already vast functionality via custom scripts and plugins. + +## :material-flag: Getting Started * Try out our [public demo](https://demo.netbox.dev/) if you want to jump right in * The [installation guide](./installation/index.md) will help you get your own deployment up and running * Or try the community [Docker image](https://github.com/netbox-community/netbox-docker) for a low-touch approach * [NetBox Cloud](https://www.getnetbox.io/) is a hosted solution offered by NS1 - -!!! tip "NetBox Development" - Interested in contributing to NetBox? Check out our [GitHub repository](https://github.com/netbox-community/netbox) to get started! From 8c5779c8642f5984fd101508d11b4d4e80a7d9f9 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 14:11:58 -0400 Subject: [PATCH 18/28] Add feature docs for virtualization --- docs/features/virtualization.md | 26 ++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 27 insertions(+) create mode 100644 docs/features/virtualization.md diff --git a/docs/features/virtualization.md b/docs/features/virtualization.md new file mode 100644 index 000000000..8e1bf35ef --- /dev/null +++ b/docs/features/virtualization.md @@ -0,0 +1,26 @@ +# Virtualization + +Virtual machines and clusters can be modeled in NetBox alongside physical infrastructure. IP addresses and other resources are assigned to these objects just like physical objects, providing a seamless integration between physical and virtual networks. + +```mermaid +flowchart TD + ClusterGroup & ClusterType --> Cluster + Cluster --> VirtualMachine + Platform --> VirtualMachine + VirtualMachine --> VMInterface + +click Cluster "../../models/virtualization/cluster/" +click ClusterGroup "../../models/virtualization/clustergroup/" +click ClusterType "../../models/virtualization/clustertype/" +click Platform "../../models/dcim/platform/" +click VirtualMachine "../../models/virtualization/virtualmachine/" +click VMInterface "../../models/virtualization/vminterface/" +``` + +## Clusters + +A cluster is one or more physical host devices on which virtual machines can run. Each cluster must have a type and operational status, and may be assigned to a group. (Both types and groups are user-defined.) Each cluster may designate one or more devices as hosts, however this is optional. + +## Virtual Machines + +A virtual machine is a virtualized compute instance. These behave in NetBox very similarly to device objects, but without any physical attributes. For example, a VM may have interfaces assigned to it with IP addresses and VLANs, however its interfaces cannot be connected via cables (because they are virtual). Each VM may also define its compute, memory, and storage resources as well. diff --git a/mkdocs.yml b/mkdocs.yml index 9eea20397..be9c31651 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,7 @@ nav: - L2VPN & Overlay: 'features/l2vpn-overlay.md' - Circuits: 'features/circuits.md' - Wireless: 'features/wireless.md' + - Virtualization: 'features/virtualization.md' - Tenancy: 'features/tenancy.md' - Contacts: 'features/contacts.md' - Context Data: 'features/context-data.md' From 9c667bb3af7fb8339acfd04ee586f98526ccf71e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 14:14:56 -0400 Subject: [PATCH 19/28] Add hyperlinks to Mermaid graphs --- docs/features/circuits.md | 6 ++++ docs/features/contacts.md | 4 +++ docs/features/devices-cabling.md | 8 ++++++ docs/features/facilities.md | 8 ++++++ docs/features/ipam.md | 9 +++++- docs/features/tenancy.md | 3 ++ docs/features/vlan-management.md | 4 +++ docs/features/wireless.md | 3 ++ docs/getting-started/planning.md | 49 ++++++++++++++++++++++++++++++-- 9 files changed, 91 insertions(+), 3 deletions(-) diff --git a/docs/features/circuits.md b/docs/features/circuits.md index f0c5832c4..7739efb4c 100644 --- a/docs/features/circuits.md +++ b/docs/features/circuits.md @@ -7,6 +7,12 @@ flowchart TD ASN --> Provider Provider --> ProviderNetwork & Circuit CircuitType --> Circuit + +click ASN "../../models/circuits/asn/" +click Circuit "../../models/circuits/circuit/" +click CircuitType "../../models/circuits/circuittype/" +click Provider "../../models/circuits/provider/" +click ProviderNetwork "../../models/circuits/providernetwork/" ``` ## Providers diff --git a/docs/features/contacts.md b/docs/features/contacts.md index 7d717b2de..6bbd217fc 100644 --- a/docs/features/contacts.md +++ b/docs/features/contacts.md @@ -7,6 +7,10 @@ flowchart TD ContactGroup --> ContactGroup & Contact ContactRole & Contact --> assignment([Assignment]) assignment --> Object + +click Contact "../../models/tenancy/contact/" +click ContactGroup "../../models/tenancy/contactgroup/" +click ContactRole "../../models/tenancy/contactrole/" ``` ## Contact Groups diff --git a/docs/features/devices-cabling.md b/docs/features/devices-cabling.md index 7297f79ac..bec3e56de 100644 --- a/docs/features/devices-cabling.md +++ b/docs/features/devices-cabling.md @@ -11,6 +11,14 @@ flowchart TD DeviceRole & Platform & DeviceType --> Device Device & ModuleType ---> Module Device & Module --> Interface & ConsolePort & PowerPort & ... + +click Device "../../models/dcim/device/" +click DeviceRole "../../models/dcim/devicerole/" +click DeviceType "../../models/dcim/devicetype/" +click Manufacturer "../../models/dcim/manufacturer/" +click Module "../../models/dcim/module/" +click ModuleType "../../models/dcim/moduletype/" +click Platform "../../models/dcim/platform/" ``` ## Manufacturers diff --git a/docs/features/facilities.md b/docs/features/facilities.md index f105bd4c5..84c7c5733 100644 --- a/docs/features/facilities.md +++ b/docs/features/facilities.md @@ -13,6 +13,14 @@ flowchart TD Rack --> Device Site --> Rack RackRole --> Rack + +click Device "../../models/dcim/device/" +click Location "../../models/dcim/location/" +click Rack "../../models/dcim/rack/" +click RackRole "../../models/dcim/rackrole/" +click Region "../../models/dcim/region/" +click Site "../../models/dcim/site/" +click SiteGroup "../../models/dcim/sitegroup/" ``` ## Regions diff --git a/docs/features/ipam.md b/docs/features/ipam.md index 45a6a0221..d67645b17 100644 --- a/docs/features/ipam.md +++ b/docs/features/ipam.md @@ -17,8 +17,15 @@ flowchart TD Aggregate & Role --> Prefix Prefix --> Prefix Prefix --> IPRange & IPAddress + +click Aggregate "../../models/ipam/aggregate/" +click IPAddress "../../models/ipam/ipaddress/" +click IPRange "../../models/ipam/iprange/" +click Prefix "../../models/ipam/prefix/" +click RIR "../../models/ipam/rir/" +click Role "../../models/ipam/role/" ``` - + !!! tip "Automatic Hierarchies" IP objects in NetBox never need to be manually assigned to the parent objects. The construction of hierarchies is handled automatically by the application according to the inherent rules of IP addressing. diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md index fe6d8e5a8..a278dc4c2 100644 --- a/docs/features/tenancy.md +++ b/docs/features/tenancy.md @@ -6,6 +6,9 @@ Most core objects within NetBox's data model support _tenancy_. This is the asso flowchart TD TenantGroup --> TenantGroup & Tenant Tenant --> Site & Device & Prefix & Circuit & ... + +click Tenant "../../models/tenancy/tenant/" +click TenantGroup "../../models/tenancy/tenantgroup/" ``` ## Tenant Groups diff --git a/docs/features/vlan-management.md b/docs/features/vlan-management.md index 4af05dea3..c74c9015c 100644 --- a/docs/features/vlan-management.md +++ b/docs/features/vlan-management.md @@ -5,6 +5,10 @@ Complementing its IPAM capabilities, NetBox also tracks VLAN information to assi ```mermaid flowchart TD VLANGroup & Role --> VLAN + +click Role "../../models/ipam/role/" +click VLAN "../../models/ipam/vlan/" +click VLANGroup "../../models/ipam/vlangroup/" ``` ## VLAN Groups diff --git a/docs/features/wireless.md b/docs/features/wireless.md index 215d1a682..c78387efb 100644 --- a/docs/features/wireless.md +++ b/docs/features/wireless.md @@ -7,6 +7,9 @@ Just as NetBox provides robust modeling for physical cable plants, it also suppo ```mermaid flowchart TD WirelessLANGroup --> WirelessLANGroup & WirelessLAN + +click WirelessLAN "../../models/wireless/wirelesslan/" +click WirelessLANGroup "../../models/wireless/wirelesslangroup/" ``` A wireless LAN is a multi-access network shared by multiple wireless clients, identified by a common service set identifier (SSID) and authentication parameters. Wireless LANs can be organized into self-nesting groups, and each wireless LAN may optionally be bound to a particular VLAN. This allows easily mapping wireless networks to their wired counterparts. diff --git a/docs/getting-started/planning.md b/docs/getting-started/planning.md index 5c431a4d2..5dbe6e54e 100644 --- a/docs/getting-started/planning.md +++ b/docs/getting-started/planning.md @@ -78,9 +78,15 @@ The graphs below illustrate some of the core dependencies among different models ```mermaid flowchart TD - TenantGroup --> TenantGroup - TenantGroup --> Tenant + TenantGroup --> TenantGroup & Tenant Tenant --> Site & Device & Prefix & VLAN & ... + +click Device "../../models/dcim/device/" +click Prefix "../../models/ipam/prefix/" +click Site "../../models/dcim/site/" +click Tenant "../../models/tenancy/tenant/" +click TenantGroup "../../models/tenancy/tenantgroup/" +click VLAN "../../models/ipam/vlan/" ``` ### Sites, Racks, and Devices @@ -99,6 +105,21 @@ flowchart TD DeviceType --> Device Device & ModuleType ---> Module Device & Module --> Interface + +click Device "../../models/dcim/device/" +click DeviceRole "../../models/dcim/devicerole/" +click DeviceType "../../models/dcim/devicetype/" +click Interface "../../models/dcim/interface/" +click Location "../../models/dcim/location/" +click Manufacturer "../../models/dcim/manufacturer/" +click Module "../../models/dcim/module/" +click ModuleType "../../models/dcim/moduletype/" +click Platform "../../models/dcim/platform/" +click Rack "../../models/dcim/rack/" +click RackRole "../../models/dcim/rackrole/" +click Region "../../models/dcim/region/" +click Site "../../models/dcim/site/" +click SiteGroup "../../models/dcim/sitegroup/" ``` ### VRFs, Prefixes, IP Addresses, and VLANs @@ -112,6 +133,16 @@ flowchart TD Aggregate & VRF --> Prefix VRF --> IPRange & IPAddress Prefix --> VLAN & IPRange & IPAddress + +click Aggregate "../../models/ipam/aggregate/" +click IPAddress "../../models/ipam/ipaddress/" +click IPRange "../../models/ipam/iprange/" +click Prefix "../../models/ipam/prefix/" +click RIR "../../models/ipam/rir/" +click Role "../../models/ipam/role/" +click VLAN "../../models/ipam/vlan/" +click VLANGroup "../../models/ipam/vlangroup/" +click VRF "../../models/ipam/vrf/" ``` ### Circuits @@ -121,6 +152,12 @@ flowchart TD Provider & CircuitType --> Circuit Provider --> ProviderNetwork Circuit --> CircuitTermination + +click Circuit "../../models/circuits/circuit/" +click CircuitTermination "../../models/circuits/circuittermination/" +click CircuitType "../../models/circuits/circuittype/" +click Provider "../../models/circuits/provider/" +click ProviderNetwork "../../models/circuits/providernetwork/" ``` ### Clusters and Virtual Machines @@ -132,4 +169,12 @@ flowchart TD Site --> Cluster & VirtualMachine Device & Platform --> VirtualMachine VirtualMachine --> VMInterface + +click Cluster "../../models/virtualization/cluster/" +click ClusterGroup "../../models/virtualization/clustergroup/" +click ClusterType "../../models/virtualization/clustertype/" +click Device "../../models/dcim/device/" +click Platform "../../models/dcim/platform/" +click VirtualMachine "../../models/virtualization/virtualmachine/" +click VMInterface "../../models/virtualization/vminterface/" ``` From fafc464d932bed1a03aaba959286f1fe66ada931 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 15:00:45 -0400 Subject: [PATCH 20/28] Refreshed circuits model documentation --- docs/models/circuits/circuit.md | 54 +++++++++++++++++----- docs/models/circuits/circuittermination.md | 42 +++++++++++++++-- docs/models/circuits/circuittype.md | 12 ++++- docs/models/circuits/provider.md | 39 +++++++++++++++- docs/models/circuits/providernetwork.md | 14 +++++- 5 files changed, 142 insertions(+), 19 deletions(-) diff --git a/docs/models/circuits/circuit.md b/docs/models/circuits/circuit.md index 3aaa4e99f..50637ab4e 100644 --- a/docs/models/circuits/circuit.md +++ b/docs/models/circuits/circuit.md @@ -1,19 +1,49 @@ # Circuits -A communications circuit represents a single _physical_ link connecting exactly two endpoints, commonly referred to as its A and Z terminations. A circuit in NetBox may have zero, one, or two terminations defined. It is common to have only one termination defined when you don't necessarily care about the details of the provider side of the circuit, e.g. for Internet access circuits. Both terminations would likely be modeled for circuits which connect one customer site to another. +A circuit represents a physical point-to-point data connection, typically used to interconnect sites across considerable distances (e.g. to deliver Internet connectivity). -Each circuit is associated with a provider and a user-defined type. For example, you might have Internet access circuits delivered to each site by one provider, and private MPLS circuits delivered by another. Each circuit must be assigned a circuit ID, each of which must be unique per provider. +## Fields -Each circuit is also assigned one of the following operational statuses: +### Provider -* Planned -* Provisioning -* Active -* Offline -* Deprovisioning -* Decommissioned +The [provider](./provider.md) to which this circuit belongs. -Circuits also have optional fields for annotating their installation and termination dates and commit rate, and may be assigned to NetBox tenants. +### Circuit ID -!!! note - NetBox currently models only physical circuits: those which have exactly two endpoints. It is common to layer virtualized constructs (_virtual circuits_) such as MPLS or EVPN tunnels on top of these, however NetBox does not yet support virtual circuit modeling. +An identifier for this circuit. This must be unique to the assigned provider. (Circuits assigned to different providers may have the same circuit ID.) + +### Circuit Type + +Each circuit is classified by a user-defined [circuit type](./circuittype.md). Generally this is something like "Internet access," "MPLS/VPN," etc. + +### Status + +The operational status of the circuit. By default, the following statuses are available: + +| Name | +|----------------| +| Planned | +| Provisioning | +| Active | +| Offline | +| Deprovisioning | +| Decommissioned | + +!!! tip "Custom circuit statuses" + Additional circuit statuses may be defined by setting `Circuit.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Description + +A brief description of the circuit. + +### Installation Date + +The date on which the circuit was installed. + +### Termination Date + +The date on which the circuit is scheduled to be disconnected. + +### Commit Rate + +The committed rate (throughput) of the circuit, in kilobits per second. diff --git a/docs/models/circuits/circuittermination.md b/docs/models/circuits/circuittermination.md index beea2f85a..c6aa966d0 100644 --- a/docs/models/circuits/circuittermination.md +++ b/docs/models/circuits/circuittermination.md @@ -1,10 +1,46 @@ # Circuit Terminations -The association of a circuit with a particular site and/or device is modeled separately as a circuit termination. A circuit may have up to two terminations, labeled A and Z. A single-termination circuit can be used when you don't know (or care) about the far end of a circuit (for example, an Internet access circuit which connects to a transit provider). A dual-termination circuit is useful for tracking circuits which connect two sites. - -Each circuit termination is attached to either a site or to a provider network. Site terminations may optionally be connected via a cable to a specific device interface or port within that site. Each termination must be assigned a port speed, and can optionally be assigned an upstream speed if it differs from the downstream speed (a common scenario with e.g. DOCSIS cable modems). Fields are also available to track cross-connect and patch panel details. +Each circuit may have up to two terminations, designated A and Z. At either termination, a circuit may connect to a site, device interface (via a cable), or to a provider network. In adherence with NetBox's philosophy of closely modeling the real world, a circuit may be connected only to a physical interface. For example, circuits may not terminate to LAG interfaces, which are virtual in nature. In such cases, a separate physical circuit is associated with each LAG member interface and each needs to be modeled discretely. !!! note A circuit in NetBox represents a physical link, and cannot have more than two endpoints. When modeling a multi-point topology, each leg of the topology must be defined as a discrete circuit, with one end terminating within the provider's infrastructure. The provider network model is ideal for representing these networks. + +## Fields + +### Circuit + +The [circuit](./circuit.md) to which this termination belongs. + +### Termination Side + +Designates the termination as forming either the A or Z end of the circuit. + +### Mark Connected + +If selected, the circuit termination will be considered "connected" even if no cable has been connected to it in NetBox. + +### Site + +The [site](../dcim/site.md) with which this circuit termination is associated. Once created, a cable can be connected between the circuit termination and a device interface (or similar component). + +### Provider Network + +Circuits which do not connect to a site modeled by NetBox can instead be terminated to a [provider network](./providernetwork.md) representing an unknown network operated by a [provider](./provider.md). + +### Port Speed + +The operating speed of the terminated interface, in kilobits per second. This is useful for documenting the speed of a circuit when the actual interface to which it terminates is not being modeled in NetBox. + +### Upstream Speed + +The upstream speed of the terminated interface (in kilobits per second), if different from the downstream speed (a common scenario with e.g. DOCSIS cable modems). + +### Cross-connect ID + +In a data center environment, circuits are often delivered via a local cross-connect. While it may not be appropriate to model the cross-connect itself in NetBox, it's a good idea to record its ID for reference where applicable. + +### Patch Panel & Port(s) + +Similar to the cross-connect ID, this field can be used to track physical connection details which may be outside the scope of what is being modeled in NetBox. diff --git a/docs/models/circuits/circuittype.md b/docs/models/circuits/circuittype.md index aa8258e04..d0baa0f89 100644 --- a/docs/models/circuits/circuittype.md +++ b/docs/models/circuits/circuittype.md @@ -1,8 +1,18 @@ # Circuit Types -Circuits are classified by functional type. These types are completely customizable, and are typically used to convey the type of service being delivered over a circuit. For example, you might define circuit types for: +[Circuits](./circuit.md) are classified by functional type. These types are completely customizable, and are typically used to convey the type of service being delivered over a circuit. For example, you might define circuit types for: * Internet transit * Out-of-band connectivity * Peering * Private backhaul + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/circuits/provider.md b/docs/models/circuits/provider.md index e0847b72f..a4835199e 100644 --- a/docs/models/circuits/provider.md +++ b/docs/models/circuits/provider.md @@ -1,5 +1,40 @@ # Providers -A circuit provider is any entity which provides some form of connectivity of among sites or organizations within a site. While this obviously includes carriers which offer Internet and private transit service, it might also include Internet exchange (IX) points and even organizations with whom you peer directly. Each circuit within NetBox must be assigned a provider and a circuit ID which is unique to that provider. +A provider is any entity which provides some form of connectivity of among sites or organizations within a site. While this obviously includes carriers which offer Internet and private transit service, it might also include Internet exchange (IX) points and even organizations with whom you peer directly. Each [circuit](./circuit.md) within NetBox must be assigned a provider and a circuit ID which is unique to that provider. -Each provider may be assigned an autonomous system number (ASN), an account number, and contact information. +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### ASN + +The AS number assigned to this provider. + +!!! warning "Legacy field" + This field is being removed in NetBox v3.4. Users are highly encouraged to use the [ASN model](../ipam/asn.md) to track AS number assignment for providers. + +### ASNs + +The [AS numbers](../ipam/asn.md) assigned to this provider (optional). + +### Account Number + +The administrative account identifier tied to this provider for your organization. + +### Portal URL + +The URL for the provider's customer service portal. + +### NOC Contact + +Contact details for the provider's network operations center (NOC). + +### Admin Contact + +Administrative contact details for the provider. diff --git a/docs/models/circuits/providernetwork.md b/docs/models/circuits/providernetwork.md index 42c46e13c..90db02573 100644 --- a/docs/models/circuits/providernetwork.md +++ b/docs/models/circuits/providernetwork.md @@ -2,4 +2,16 @@ This model can be used to represent the boundary of a provider network, the details of which are unknown or unimportant to the NetBox user. For example, it might represent a provider's regional MPLS network to which multiple circuits provide connectivity. -Each provider network must be assigned to a provider, and may optionally be assigned an arbitrary service ID. A circuit may terminate to either a provider network or to a site. +## Fields + +### Provider + +The [provider](./provider.md) responsible for the operation of this network. + +### Name + +A human-friendly name, unique to the provider. + +### Service ID + +An arbitrary identifier used as an alternate reference for the type of connectivity or service being delivered. From cff6b81f1fdfbc888e60e97be570262182d30fed Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 16:00:04 -0400 Subject: [PATCH 21/28] Refreshed extras model documentation --- docs/features/context-data.md | 58 ++++++++++++++-- docs/features/customization.md | 12 ++++ docs/models/extras/configcontext.md | 68 ++++--------------- docs/models/extras/customfield.md | 2 + docs/models/extras/customlink.md | 2 + docs/models/extras/exporttemplate.md | 2 + docs/models/extras/imageattachment.md | 10 +++ docs/models/extras/tag.md | 18 ++--- docs/models/extras/webhook.md | 95 ++++++++++++++++++++++----- 9 files changed, 184 insertions(+), 83 deletions(-) diff --git a/docs/features/context-data.md b/docs/features/context-data.md index d202482da..04e795fd5 100644 --- a/docs/features/context-data.md +++ b/docs/features/context-data.md @@ -11,10 +11,6 @@ Configuration context data (or "config contexts" for short) is a powerful featur } ``` -While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases. - -There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. Additionally, each device and VM may have local context data defined: This data is stored directly on the assigned object, and applies to it only. This is a convenient way for "attaching" miscellaneous data to a single device or VM as needed. - Config contexts can be computed for objects based on the following criteria: | Type | Devices | Virtual Machines | @@ -32,3 +28,57 @@ Config contexts can be computed for objects based on the following criteria: | Tenant group | :material-check: | :material-check: | | Tenant | :material-check: | :material-check: | | Tag | :material-check: | :material-check: | + +There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. + +## Hierarchical Rendering + +While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases. + +For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data: + +```json +{ + "ntp-servers": [ + "172.16.10.22", + "172.16.10.33" + ], + "syslog-servers": [ + "172.16.9.100", + "172.16.9.101" + ] +} +``` + +But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data: + +```json +{ + "syslog-servers": [ + "192.168.43.107" + ] +} +``` + +When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following: + +```json +{ + "ntp-servers": [ + "172.16.10.22", + "172.16.10.33" + ], + "syslog-servers": [ + "192.168.43.107" + ] +} +``` + +Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved. + +## Local Context Data + +Devices and virtual machines may also have a local context data defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object. + +!!! warning + If you find that you're routinely defining local context data for many individual devices or virtual machines, [custom fields](./customization.md#custom-fields) may offer a more effective solution. diff --git a/docs/features/customization.md b/docs/features/customization.md index d7f2cf40a..813914ae2 100644 --- a/docs/features/customization.md +++ b/docs/features/customization.md @@ -6,6 +6,18 @@ While NetBox strives to meet the needs of every network, the needs of users to c Most objects in NetBox can be assigned user-created tags to aid with organization and filtering. Tag values are completely arbitrary: They may be used to store data in key-value pairs, or they may be employed simply as labels against which objects can be filtered. Each tag can also be assigned a color for quicker differentiation in the user interface. +Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": + +```no-highlight +GET /api/dcim/devices/?tag=monitored +``` + +The `tag` filter can be specified multiple times to match only objects which have _all_ the specified tags assigned: + +```no-highlight +GET /api/dcim/devices/?tag=monitored&tag=deprecated +``` + ## Custom Fields While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs. diff --git a/docs/models/extras/configcontext.md b/docs/models/extras/configcontext.md index 08b5f4fd5..156b2d784 100644 --- a/docs/models/extras/configcontext.md +++ b/docs/models/extras/configcontext.md @@ -1,69 +1,27 @@ # Configuration Contexts -Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments: +Context data is made available to [devices](../dcim/device.md) and/or [virtual machines](../virtualization/virtualmachine.md) based on their relationships to other objects in NetBox. For example, context data can be associated only with devices assigned to a particular site, or only to virtual machines in a certain cluster. -* Region -* Site group -* Site -* Location (devices only) -* Device type (devices only) -* Role -* Platform -* Cluster type (VMs only) -* Cluster group (VMs only) -* Cluster (VMs only) -* Tenant group -* Tenant -* Tag +See the [context data documentation](../../features/context-data.md) for more information. -## Hierarchical Rendering +## Fields -Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object. +### Name -For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data: +A unique human-friendly name. -```json -{ - "ntp-servers": [ - "172.16.10.22", - "172.16.10.33" - ], - "syslog-servers": [ - "172.16.9.100", - "172.16.9.101" - ] -} -``` +### Weight -But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data: +A numeric value which influences the order in which context data is merged. Contexts with a lower weight are merged before those with a higher weight. -```json -{ - "syslog-servers": [ - "192.168.43.107" - ] -} -``` +### Data -When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following: +The context data expressed in JSON format. -```json -{ - "ntp-servers": [ - "172.16.10.22", - "172.16.10.33" - ], - "syslog-servers": [ - "192.168.43.107" - ] -} -``` +### Is Active -Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved. +If not selected, this config context will be excluded from rendering. This can be convenient to temporarily disable a config context. -## Local Context Data +### Object Assignment -Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object. - -!!! warning - If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution. +Each configuration context may be assigned with any number of objects of the supported types. If no related objects are selected, it will be considered a "global" config context and apply to all devices and virtual machines. diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md index 0b2bc29f9..ee1fde2b7 100644 --- a/docs/models/extras/customfield.md +++ b/docs/models/extras/customfield.md @@ -1,5 +1,7 @@ # Custom Fields +NetBox administrators can extend NetBox's built-in data model by adding custom fields to most object types. See the [custom fields documentation](../../customization/custom-fields.md) for more information. + ## Fields ### Model(s) diff --git a/docs/models/extras/customlink.md b/docs/models/extras/customlink.md index 458007ab1..dae9978aa 100644 --- a/docs/models/extras/customlink.md +++ b/docs/models/extras/customlink.md @@ -1,5 +1,7 @@ # Custom Links +Users can add custom links to object views in NetBox to reference external resources. For example, you might create a custom link for devices pointing to a monitoring system. See the [custom links documentation](../../customization/custom-links.md) for more information. + ## Fields ### Name diff --git a/docs/models/extras/exporttemplate.md b/docs/models/extras/exporttemplate.md index 347184324..3215201b3 100644 --- a/docs/models/extras/exporttemplate.md +++ b/docs/models/extras/exporttemplate.md @@ -1,5 +1,7 @@ # Export Templates +Export templates are used to render arbitrary data from a set of NetBox objects. For example, you might want to automatically generate a network monitoring service configuration from a list of device objects. See the [export templates documentation](../../customization/export-templates.md) for more information. + ## Fields ### Name diff --git a/docs/models/extras/imageattachment.md b/docs/models/extras/imageattachment.md index da15462ab..b8c48f055 100644 --- a/docs/models/extras/imageattachment.md +++ b/docs/models/extras/imageattachment.md @@ -1,3 +1,13 @@ # Image Attachments Certain objects in NetBox support the attachment of uploaded images. These will be saved to the NetBox server and made available whenever the object is viewed. + +## Fields + +### Name + +The name of the image being attached. If not defined, this will be inferred from the name of the uploaded file. + +### Image + +The image file to upload. Note that the uploaded file **must** be a supported image type, or validation will fail. diff --git a/docs/models/extras/tag.md b/docs/models/extras/tag.md index fe6a1ef36..97ebd9d72 100644 --- a/docs/models/extras/tag.md +++ b/docs/models/extras/tag.md @@ -2,16 +2,16 @@ Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects. -Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose. +## Fields -Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": +### Name -```no-highlight -GET /api/dcim/devices/?tag=monitored -``` +A unique human-friendly label for the tag. -The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned: +### Slug -```no-highlight -GET /api/dcim/devices/?tag=monitored&tag=deprecated -``` +A unique URL-friendly identifier. (This value will be used for filtering.) This is automatically generated from the tag's name, but can be altered as needed. + +### Color + +The color to use when displaying the tag in the NetBox UI. diff --git a/docs/models/extras/webhook.md b/docs/models/extras/webhook.md index 2d598f8ae..1ca6ec191 100644 --- a/docs/models/extras/webhook.md +++ b/docs/models/extras/webhook.md @@ -1,19 +1,84 @@ # Webhooks -A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks. +A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. -## Model Fields +See the [webhooks documentation](../../integrations/webhooks.md) for more information. -* **Name** - A unique name for the webhook. The name is not included with outbound messages. -* **Object type(s)** - The type or types of NetBox object that will trigger the webhook. -* **Enabled** - If unchecked, the webhook will be inactive. -* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected. -* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. -* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field. -* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`) -* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below). -* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.) -* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key. -* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object. -* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!) -* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional). +## Fields + +### Name + +A unique human-friendly name. + +### Content Types + +The type(s) of object in NetBox that will trigger the webhook. + +### Enabled + +If not selected, the webhook will be inactive. + +### Events + +The events which will trigger the webhook. At least one event type must be selected. + +| Name | Description | +|-----------|--------------------------------------| +| Creations | A new object has been created | +| Updates | An existing object has been modified | +| Deletions | An object has been deleted | + +### URL + +The URL to which the webhook HTTP request will be made. + +### HTTP Method + +The type of HTTP request to send. Options are: + +* `GET` +* `POST` +* `PUT` +* `PATCH` +* `DELETE` + +### HTTP Content Type + +The content type to indicate in the outgoing HTTP request header. See [this list](https://www.iana.org/assignments/media-types/media-types.xhtml) of known types for reference. + +### Additional Headers + +Any additional header to include with the outgoing HTTP request. These should be defined in the format `Name: Value`, with each header on a separate line. Jinja2 templating is supported for this field. + +### Body Template + +Jinja2 template for a custom request body, if desired. If not defined, NetBox will populate the request body with a raw dump of the webhook context. + +### Secret + +A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key. + +### SSL Verification + +Controls whether validation of the receiver's SSL certificate is enforced when HTTPS is used. + +!!! warning + Disabling this can expose your webhooks to man-in-the-middle attacks. + +### CA File Path + +The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (if not using the system defaults). + +## Context Data + +The following context variables are available in to the text and link templates. + +| Variable | Description | +|--------------|----------------------------------------------------| +| `event` | The event type (`create`, `update`, or `delete`) | +| `timestamp` | The time at which the event occured | +| `model` | The type of object impacted | +| `username` | The name of the user associated with the change | +| `request_id` | The unique request ID | +| `data` | A complete serialized representation of the object | +| `snapshots` | Pre- and post-change snapshots of the object | From 040feddcf1ee29c65c1a0515d23b3412cf89b217 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 16:19:34 -0400 Subject: [PATCH 22/28] Refreshed tenancy model documentation --- docs/features/contacts.md | 17 ++++++++++ docs/features/tenancy.md | 18 ++++++++++- docs/models/tenancy/contact.md | 48 +++++++++++++++-------------- docs/models/tenancy/contactgroup.md | 16 +++++++++- docs/models/tenancy/contactrole.md | 12 +++++++- docs/models/tenancy/tenant.md | 26 ++++++++-------- docs/models/tenancy/tenantgroup.md | 16 +++++++++- 7 files changed, 113 insertions(+), 40 deletions(-) diff --git a/docs/features/contacts.md b/docs/features/contacts.md index 6bbd217fc..40e8dd12c 100644 --- a/docs/features/contacts.md +++ b/docs/features/contacts.md @@ -26,3 +26,20 @@ A contact role defines the relationship of a contact to an assigned object. For A contact should represent an individual or permanent point of contact. Each contact must define a name, and may optionally include a title, phone number, email address, and related details. Contacts are reused for assignments, so each unique contact must be created only once and can be assigned to any number of NetBox objects, and there is no limit to the number of assigned contacts an object may have. Most core objects in NetBox can have contacts assigned to them. + +The following models support the assignment of contacts: + +* circuits.Circuit +* circuits.Provider +* dcim.Device +* dcim.Location +* dcim.Manufacturer +* dcim.PowerPanel +* dcim.Rack +* dcim.Region +* dcim.Site +* dcim.SiteGroup +* tenancy.Tenant +* virtualization.Cluster +* virtualization.ClusterGroup +* virtualization.VirtualMachine diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md index a278dc4c2..470905f20 100644 --- a/docs/features/tenancy.md +++ b/docs/features/tenancy.md @@ -13,10 +13,26 @@ click TenantGroup "../../models/tenancy/tenantgroup/" ## Tenant Groups -Tenants can be grouped by any logic that your use case demands, and groups can nested recursively for maximum flexibility. For example, You might define a parent "Customers" group with child groups "Current" and "Past" within it. A tenant can be assigned to a group at any level within the hierarchy. +Tenants can be grouped by any logic that your use case demands, and groups can be nested recursively for maximum flexibility. For example, You might define a parent "Customers" group with child groups "Current" and "Past" within it. A tenant can be assigned to a group at any level within the hierarchy. ## Tenants Typically, the tenant model is used to represent a customer or internal organization, however it can be used for whatever purpose meets your needs. Most core objects within NetBox can be assigned to particular tenant, so this model provides a very convenient way to correlate ownership across object types. For example, each of your customers might have its own racks, devices, IP addresses, circuits and so on: These can all be easily tracked via tenant assignment. + +The following objects can be assigned to tenants: + +* Sites +* Racks +* Rack reservations +* Devices +* VRFs +* Prefixes +* IP addresses +* VLANs +* Circuits +* Clusters +* Virtual machines + +Tenant assignment is used to signify the ownership of an object in NetBox. As such, each object may only be owned by a single tenant. For example, if you have a firewall dedicated to a particular customer, you would assign it to the tenant which represents that customer. However, if the firewall serves multiple customers, it doesn't *belong* to any particular customer, so tenant assignment would not be appropriate. diff --git a/docs/models/tenancy/contact.md b/docs/models/tenancy/contact.md index 9d81e2d85..eac630180 100644 --- a/docs/models/tenancy/contact.md +++ b/docs/models/tenancy/contact.md @@ -1,31 +1,33 @@ # Contacts -A contact represent an individual or group that has been associated with an object in NetBox for administrative reasons. For example, you might assign one or more operational contacts to each site. Contacts can be arranged within nested contact groups. +A contact represents an individual or group that has been associated with an object in NetBox for administrative reasons. For example, you might assign one or more operational contacts to each site. -Each contact must include a name, which is unique to its parent group (if any). The following optional descriptors are also available: +## Fields -* Title -* Phone -* Email -* Address +### Group -## Contact Assignment +The [contact group](./contactgroup.md) to which this contact is assigned (if any). -Each contact can be assigned to one or more objects, allowing for the efficient reuse of contact information. When assigning a contact to an object, the user may optionally specify a role and/or priority (primary, secondary, tertiary, or inactive) to better convey the nature of the contact's relationship to the assigned object. +### Name -The following models support the assignment of contacts: +The name of the contact. This may be an individual or a team/department. (This is the only required contact detail; all others are optional.) -* circuits.Circuit -* circuits.Provider -* dcim.Device -* dcim.Location -* dcim.Manufacturer -* dcim.PowerPanel -* dcim.Rack -* dcim.Region -* dcim.Site -* dcim.SiteGroup -* tenancy.Tenant -* virtualization.Cluster -* virtualization.ClusterGroup -* virtualization.VirtualMachine +### Title + +The contact's title or role. + +### Phone + +The contact's phone number. (Note that NetBox does _not_ enforce a particular numbering format.) + +### Email + +The contact's email address. + +### Address + +The contact's physical or mailing address. + +### Link + +A URL to reach the contact via some other means. diff --git a/docs/models/tenancy/contactgroup.md b/docs/models/tenancy/contactgroup.md index ea566c58a..49efb7c18 100644 --- a/docs/models/tenancy/contactgroup.md +++ b/docs/models/tenancy/contactgroup.md @@ -1,3 +1,17 @@ # Contact Groups -Contacts can be organized into arbitrary groups. These groups can be recursively nested for convenience. Each contact within a group must have a unique name, but other attributes can be repeated. +[Contacts](./contact.md) can be organized into arbitrary groups. These groups can be recursively nested for convenience. Each contact within a group must have a unique name, but other attributes can be repeated. + +## Fields + +### Parent + +The parent contact group (if any). + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/tenancy/contactrole.md b/docs/models/tenancy/contactrole.md index 23642ca03..bc8e1c802 100644 --- a/docs/models/tenancy/contactrole.md +++ b/docs/models/tenancy/contactrole.md @@ -1,3 +1,13 @@ # Contact Roles -Contacts can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for administrative, operational, or emergency contacts. +[Contacts](./contact.md) can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for administrative, operational, or emergency contacts. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/tenancy/tenant.md b/docs/models/tenancy/tenant.md index 60a160b9e..7df6992d1 100644 --- a/docs/models/tenancy/tenant.md +++ b/docs/models/tenancy/tenant.md @@ -1,17 +1,17 @@ # Tenants -A tenant represents a discrete grouping of resources used for administrative purposes. Typically, tenants are used to represent individual customers or internal departments within an organization. The following objects can be assigned to tenants: +A tenant represents a discrete grouping of resources used for administrative purposes. Typically, tenants are used to represent individual customers or internal departments within an organization. -* Sites -* Racks -* Rack reservations -* Devices -* VRFs -* Prefixes -* IP addresses -* VLANs -* Circuits -* Clusters -* Virtual machines +## Fields -Tenant assignment is used to signify the ownership of an object in NetBox. As such, each object may only be owned by a single tenant. For example, if you have a firewall dedicated to a particular customer, you would assign it to the tenant which represents that customer. However, if the firewall serves multiple customers, it doesn't *belong* to any particular customer, so tenant assignment would not be appropriate. +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Group + +The [tenant group](./tenantgroup.md) to which this tenant belongs (if any). diff --git a/docs/models/tenancy/tenantgroup.md b/docs/models/tenancy/tenantgroup.md index 078a71a72..f9929ff66 100644 --- a/docs/models/tenancy/tenantgroup.md +++ b/docs/models/tenancy/tenantgroup.md @@ -1,5 +1,19 @@ # Tenant Groups -Tenants can be organized by custom groups. For instance, you might create one group called "Customers" and one called "Departments." The assignment of a tenant to a group is optional. +[Tenants](./tenant.md) can be organized by custom groups. For instance, you might create one group called "Customers" and one called "Departments." The assignment of a tenant to a group is optional. Tenant groups may be nested recursively to achieve a multi-level hierarchy. For example, you might have a group called "Customers" containing subgroups of individual tenants grouped by product or account team. + +## Fields + +### Parent + +The parent tenant group (if any). + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) From d4f976ac8dd2cd39f4e41520c003f77a7eac6210 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 16:37:47 -0400 Subject: [PATCH 23/28] Refreshed wireless model documentation --- docs/models/wireless/wirelesslan.md | 39 +++++++++++++++++---- docs/models/wireless/wirelesslangroup.md | 16 ++++++++- docs/models/wireless/wirelesslink.md | 43 +++++++++++++++++++++--- 3 files changed, 86 insertions(+), 12 deletions(-) diff --git a/docs/models/wireless/wirelesslan.md b/docs/models/wireless/wirelesslan.md index cb478664c..5bb3dbd65 100644 --- a/docs/models/wireless/wirelesslan.md +++ b/docs/models/wireless/wirelesslan.md @@ -1,11 +1,38 @@ # Wireless LANs -A wireless LAN is a set of interfaces connected via a common wireless channel. Each instance must have an SSID, and may optionally be correlated to a VLAN. Wireless LANs can be arranged into hierarchical groups, and each may be associated with a particular tenant. +A wireless LAN is a set of interfaces connected via a common wireless channel, identified by its SSID and authentication parameters. Wireless [interfaces](../dcim/interface.md) can be associated with wireless LANs to model multi-acess wireless segments. -An interface may be attached to multiple wireless LANs, provided they are all operating on the same channel. Only wireless interfaces may be attached to wireless LANs. +## Fields -Each wireless LAN may have authentication attributes associated with it, including: +### SSID -* Authentication type -* Cipher -* Pre-shared key +The service set identifier (SSID) for the wireless network. + +### Group + +The [wireless LAN group](./wirelesslangroup.md) to which this wireless LAN is assigned (if any). + +### VLAN + +Each wireless LAN can optionally be mapped to a [VLAN](../ipam/vlan.md), to model a bridge between wired and wireless segments. + +### Authentication Type + +The type of wireless authentication in use. Options include: + +* Open +* WEP +* WPA Personal (PSK) +* WPA Enterprise + +### Authentication Cipher + +The security cipher used to apply wireless authentication. Options include: + +* Auto (automatic) +* TKIP +* AES + +### Pre-Shared Key + +The security key configured on each client to grant access to the secured wireless LAN. This applies only to certain authentication types. diff --git a/docs/models/wireless/wirelesslangroup.md b/docs/models/wireless/wirelesslangroup.md index e477abd0b..37871f208 100644 --- a/docs/models/wireless/wirelesslangroup.md +++ b/docs/models/wireless/wirelesslangroup.md @@ -1,3 +1,17 @@ # Wireless LAN Groups -Wireless LAN groups can be used to organize and classify wireless LANs. These groups are hierarchical: groups can be nested within parent groups. However, each wireless LAN may assigned only to one group. +Wireless LAN groups can be used to organize and classify [wireless LANs](./wirelesslan.md). These groups are hierarchical: groups can be nested within parent groups. However, each wireless LAN may be assigned only to one group. + +## Fields + +### Parent + +The parent wireless LAN group (if any). + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/wireless/wirelesslink.md b/docs/models/wireless/wirelesslink.md index f52dc7191..c9b331570 100644 --- a/docs/models/wireless/wirelesslink.md +++ b/docs/models/wireless/wirelesslink.md @@ -1,9 +1,42 @@ # Wireless Links -A wireless link represents a connection between exactly two wireless interfaces. It may optionally be assigned an SSID and a description. It may also have a status assigned to it, similar to the cable model. Each wireless link may also be assigned to a particular tenant. +A wireless link represents a connection between exactly two wireless interfaces. Unlike a [wireless LAN](./wirelesslan.md), which permit an arbitrary number of client associations, wireless links are used to model point-to-point wireless connections. -Each wireless link may have authentication attributes associated with it, including: +## Fields -* Authentication type -* Cipher -* Pre-shared key +### Interfaces + +Select two interfaces: One for side A and one for side B. (Both must be wireless interfaces.) + +### Status + +The operational status of the link. Options include: + +* Connected +* Planned +* Decommissioning + +### SSID + +The service set identifier (SSID) for the wireless link (optional). + +### Authentication Type + +The type of wireless authentication in use. Options include: + +* Open +* WEP +* WPA Personal (PSK) +* WPA Enterprise + +### Authentication Cipher + +The security cipher used to apply wireless authentication. Options include: + +* Auto (automatic) +* TKIP +* AES + +### Pre-Shared Key + +The security key configured on each client to grant access to the secured wireless LAN. This applies only to certain authentication types. From f76ce172e04c1f8561d48416083e72f99a992c37 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 15 Aug 2022 11:57:38 -0400 Subject: [PATCH 24/28] Update model docs for device components --- docs/models/dcim/consoleport.md | 37 ++++- docs/models/dcim/consoleporttemplate.md | 4 +- docs/models/dcim/consoleserverport.md | 37 ++++- docs/models/dcim/consoleserverporttemplate.md | 4 +- docs/models/dcim/devicebay.md | 18 ++- docs/models/dcim/devicebaytemplate.md | 4 +- docs/models/dcim/frontport.md | 41 ++++- docs/models/dcim/frontporttemplate.md | 4 +- docs/models/dcim/interface.md | 140 +++++++++++++++--- docs/models/dcim/interfacetemplate.md | 4 +- docs/models/dcim/inventoryitem.md | 40 ++++- docs/models/dcim/inventoryitemtemplate.md | 2 +- docs/models/dcim/modulebay.md | 25 +++- docs/models/dcim/modulebaytemplate.md | 4 +- docs/models/dcim/poweroutlet.md | 38 ++++- docs/models/dcim/poweroutlettemplate.md | 4 +- docs/models/dcim/powerport.md | 40 ++++- docs/models/dcim/powerporttemplate.md | 4 +- docs/models/dcim/rearport.md | 38 ++++- docs/models/dcim/rearporttemplate.md | 4 +- 20 files changed, 432 insertions(+), 60 deletions(-) diff --git a/docs/models/dcim/consoleport.md b/docs/models/dcim/consoleport.md index 1a0782f25..e9cd09836 100644 --- a/docs/models/dcim/consoleport.md +++ b/docs/models/dcim/consoleport.md @@ -1,5 +1,36 @@ -## Console Ports +# Console Ports -A console port provides connectivity to the physical console of a device. These are typically used for temporary access by someone who is physically near the device, or for remote out-of-band access provided via a networked console server. Each console port may be assigned a physical type. +A console port provides connectivity to the physical console of a device. These are typically used for temporary access by someone who is physically near the device, or for remote out-of-band access provided via a networked console server. -Cables can connect console ports to console server ports or pass-through ports. +!!! tip + Like most device components, console ports are instantiated automatically from [console port templates](./consoleporttemplate.md) assigned to the selected device type when a device is created. + +## Fields + +### Device + +The device to which this console port belongs. + +### Module + +The installed module within the assigned device to which this console port belongs (optional). + +### Name + +The name of the console port. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the console port. + +### Type + +The type of console port. + +### Speed + +Operating speed, in bits per second (bps). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/consoleporttemplate.md b/docs/models/dcim/consoleporttemplate.md index 3462ff253..67d91de68 100644 --- a/docs/models/dcim/consoleporttemplate.md +++ b/docs/models/dcim/consoleporttemplate.md @@ -1,3 +1,3 @@ -## Console Port Templates +# Console Port Templates -A template for a console port that will be created on all instantiations of the parent device type. Each console port can be assigned a physical type. +A template for a console port that will be created on all instantiations of the parent device type. See the [console port](./consoleport.md) documentation for more detail. diff --git a/docs/models/dcim/consoleserverport.md b/docs/models/dcim/consoleserverport.md index da1ee8986..1fbb653a8 100644 --- a/docs/models/dcim/consoleserverport.md +++ b/docs/models/dcim/consoleserverport.md @@ -1,5 +1,36 @@ -## Console Server Ports +# Console Server Ports -A console server is a device which provides remote access to the local consoles of connected devices. They are typically used to provide remote out-of-band access to network devices. Each console server port may be assigned a physical type. +A console server is a device which provides remote access to the local consoles of connected devices. They are typically used to provide remote out-of-band access to network devices, and generally connect to [console ports](./consoleport.md). -Cables can connect console server ports to console ports or pass-through ports. +!!! tip + Like most device components, console server ports are instantiated automatically from [console server port templates](./consoleserverporttemplate.md) assigned to the selected device type when a device is created. + +## Fields + +### Device + +The device to which this console server port belongs. + +### Module + +The installed module within the assigned device to which this console server port belongs (optional). + +### Name + +The name of the console server port. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the console server port. + +### Type + +The type of console server port. + +### Speed + +Operating speed, in bits per second (bps). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. \ No newline at end of file diff --git a/docs/models/dcim/consoleserverporttemplate.md b/docs/models/dcim/consoleserverporttemplate.md index cc4e8bcd3..c599e738a 100644 --- a/docs/models/dcim/consoleserverporttemplate.md +++ b/docs/models/dcim/consoleserverporttemplate.md @@ -1,3 +1,3 @@ -## Console Server Port Templates +# Console Server Port Templates -A template for a console server port that will be created on all instantiations of the parent device type. Each console server port can be assigned a physical type. +A template for a console server port that will be created on all instantiations of the parent device type. See the [console server port](./consoleserverport.md) documentation for more detail. diff --git a/docs/models/dcim/devicebay.md b/docs/models/dcim/devicebay.md index e79c426dc..f4f807c4a 100644 --- a/docs/models/dcim/devicebay.md +++ b/docs/models/dcim/devicebay.md @@ -1,8 +1,22 @@ -## Device Bays +# Device Bays Device bays represent a space or slot within a parent device in which a child device may be installed. For example, a 2U parent chassis might house four individual blade servers. The chassis would appear in the rack elevation as a 2U device with four device bays, and each server within it would be defined as a 0U device installed in one of the device bays. Child devices do not appear within rack elevations or count as consuming rack units. Child devices are first-class Devices in their own right: That is, they are fully independent managed entities which don't share any control plane with the parent. Just like normal devices, child devices have their own platform (OS), role, tags, and components. LAG interfaces may not group interfaces belonging to different child devices. !!! note - Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as modules installed within module bays. + Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as [modules](./module.md) installed within [module bays](./modulebay.md). + +## Fields + +### Device + +The device to which this device bay belongs. + +### Name + +The device bay's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the device bay. diff --git a/docs/models/dcim/devicebaytemplate.md b/docs/models/dcim/devicebaytemplate.md index a4c50067a..060b799c0 100644 --- a/docs/models/dcim/devicebaytemplate.md +++ b/docs/models/dcim/devicebaytemplate.md @@ -1,3 +1,3 @@ -## Device Bay Templates +# Device Bay Templates -A template for a device bay that will be created on all instantiations of the parent device type. Device bays hold child devices, such as blade servers. +A template for a device bay that will be created on all instantiations of the parent device type. See the [device bay](./devicebay.md) documentation for more detail. diff --git a/docs/models/dcim/frontport.md b/docs/models/dcim/frontport.md index 6f12e8cbf..0b291c9ed 100644 --- a/docs/models/dcim/frontport.md +++ b/docs/models/dcim/frontport.md @@ -1,3 +1,40 @@ -## Front Ports +# Front Ports -Front ports are pass-through ports used to represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific rear port on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each. +Front ports are pass-through ports which represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific [rear port](./rearport.md) on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each. + +## Fields + +### Device + +The device to which this port belongs. + +### Module + +The installed module within the assigned device to which this port belongs (optional). + +### Name + +The port's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the port. + +### Type + +The port's termination type. + +### Rear Ports + +The rear port and position to which this front port maps. + +!!! tip + When creating multiple front ports using a patterned name (e.g. `Port [1-12]`), you may select the equivalent number of rear port-position mappings from the list. + +### Color + +The port's color (optional). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/frontporttemplate.md b/docs/models/dcim/frontporttemplate.md index 03de0eae4..09535e3b6 100644 --- a/docs/models/dcim/frontporttemplate.md +++ b/docs/models/dcim/frontporttemplate.md @@ -1,3 +1,3 @@ -## Front Port Templates +# Front Port Templates -A template for a front-facing pass-through port that will be created on all instantiations of the parent device type. Front ports may have a physical type assigned, and must be associated with a corresponding rear port and position. This association will be automatically replicated when the device type is instantiated. +A template for a front-facing pass-through port that will be created on all instantiations of the parent device type. See the [front port](./frontport.md) documentation for more detail. diff --git a/docs/models/dcim/interface.md b/docs/models/dcim/interface.md index 87a1411b9..b69f7c6b1 100644 --- a/docs/models/dcim/interface.md +++ b/docs/models/dcim/interface.md @@ -1,34 +1,138 @@ -## Interfaces +# Interfaces -Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. Each interface must be assigned a type, and may optionally be assigned a MAC address, MTU, and IEEE 802.1Q mode (tagged or access). Each interface can also be enabled or disabled, and optionally designated as management-only (for out-of-band management). Additionally, each interface may optionally be assigned to a VRF. +Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. IP addresses and VLANs can be assigned to interfaces. !!! note - Although devices and virtual machines both can have interfaces, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa. + Although both devices and virtual machines both can have interfaces assigned, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa. -### Interface Types +## Fields -Interfaces may be physical or virtual in nature, but only physical interfaces may be connected via cables. Cables can connect interfaces to pass-through ports, circuit terminations, or other interfaces. Virtual interfaces, such as 802.1Q-tagged subinterfaces, may be assigned to physical parent interfaces. +### Device -Physical interfaces may be arranged into a link aggregation group (LAG) and associated with a parent LAG (virtual) interface. LAG interfaces can be recursively nested to model bonding of trunk groups. Like all virtual interfaces, LAG interfaces cannot be connected physically. +The device to which this interface belongs. -### Power over Ethernet (PoE) +### Module + +The installed module within the assigned device to which this interface belongs (optional). + +### Name + +The name of the interface, as reported by the device's operating system. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the interface. + +### Type + +The type of interface. Interfaces may be physical or virtual in nature, but only physical interfaces may be connected via cables. !!! note - This feature was added in NetBox v3.3. + The interface type refers to the physical termination or port on the device. Interfaces which employ a removable optic or similar transceiver should be defined to represent the type of transceiver in use, irrespective of the physical termination to that transceiver. -Physical interfaces can be assigned a PoE mode to indicate PoE capability: power supplying equipment (PSE) or powered device (PD). Additionally, a PoE mode may be specified. This can be one of the listed IEEE 802.3 standards, or a passive setting (24 or 48 volts across two or four pairs). +### Speed -### Wireless Interfaces +The operating speed, in kilobits per second (kbps). -Wireless interfaces may additionally track the following attributes: +### Duplex -* **Role** - AP or station -* **Channel** - One of several standard wireless channels -* **Channel Frequency** - The transmit frequency -* **Channel Width** - Channel bandwidth +The operation duplex (full, half, or auto). -If a predefined channel is selected, the frequency and width attributes will be assigned automatically. If no channel is selected, these attributes may be defined manually. +### VRF -### IP Address Assignment +The [virtual routing and forwarding](../ipam/vrf.md) instance to which this interface is assigned. -IP addresses can be assigned to interfaces. VLANs can also be assigned to each interface as either tagged or untagged. (An interface may have only one untagged VLAN.) +### MAC Address + +The 48-bit MAC address (for Ethernet interfaces). + +### WWN + +The 64-bit world-wide name (for Fibre Channel interfaces). + +### MTU + +The interface's configured maximum transmissible unit (MTU). + +### Transmit Power + +The interface's configured output power, in dBm (for optical interfaces). + +### Enabled + +If not selected, this interface will be treated as disabled/inoperative. + +### Management Only + +Designates the interface as handling management traffic only (e.g. for out-of-band management connections). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. + +### Parent Interface + +Virtual interfaces can be bound to a physical parent interface. This is helpful for modeling virtual interfaces which employ encapsulation on a physical interface, such as an 802.1Q VLAN-tagged subinterface. + +### Bridged Interface + +Interfaces can be bridged to other interfaces on a device in two manners: symmetric or grouped. + +* **Symmetric:** For example, eth0 is bridged to eth1, and eth1 is bridged to eth0. This effects a point-to-point bridge between the two interfaces, which NetBox will follow when tracing cable paths. +* **Grouped:** Multiple interfaces are each bridged to a common virtual bridge interface, effecting a multiaccess bridged segment. NetBox cannot follow these relationships when tracing cable paths, because no forwarding information is available. + +### LAG Interface + +Physical interfaces may be arranged into link aggregation groups (LAGs, also known as "trunks") and associated with a parent LAG (virtual) interface. LAG interfaces can be recursively nested to model bonding of trunk groups. Like all virtual interfaces, LAG interfaces cannot be connected physically. + +### PoE Mode + +The power over Ethernet (PoE) mode for this interface. (This field must be left empty for interfaces which do not support PoE.) Choices include: + +* Powered device (PD) +* Power-supplying equipment (PSE) + +### PoE Type + +The classification of PoE transmission supported, for PoE-enabled interfaces. This can be one of the listed IEEE 802.3 standards, or a passive setting (24 or 48 volts across two or four pairs). + +### 802.1Q Mode + +For switched Ethernet interfaces, this identifies the 802.1Q encapsulation strategy in effect. Options include: + +* **Access:** All traffic is assigned to a single VLAN, with no tagging. +* **Tagged:** One untagged "native" VLAN is allowed, as well as any number of tagged VLANs. +* **Tagged (all):** Implies that all VLANs are carried by the interface. One untagged VLAN may be designated. + +This field must be left blank for routed interfaces which do employ 802.1Q encapsulation. + +### Untagged VLAN + +The "native" (untagged) VLAN for the interface. Valid only when one of the above 802.1Q mode is selected. + +### Tagged VLANs + +The tagged VLANs which are configured to be carried by this interface. Valid only for the "tagged" 802.1Q mode above. + +### Wireless Role + +Indicates the configured role for wireless interfaces (access point or station). + +### Wireless Channel + +The configured channel for wireless interfaces. + +!!! tip + Selecting one of the pre-defined wireless channels will automatically populate the channel frequency and width upon saving the interface. + +### Channel Frequency + +The configured operation frequency of a wireless interface, in MHz. This is typically inferred by the configured channel above, but may be set manually e.g. to identify a licensed channel not available for general use. + +### Channel Width + +The configured channel width of a wireless interface, in MHz. This is typically inferred by the configured channel above, but may be set manually e.g. to identify a licensed channel not available for general use. + +### Wireless LANs + +The [wireless LANs](../wireless/wirelesslan.md) for which this interface carries traffic. (Valid for wireless interfaces only.) diff --git a/docs/models/dcim/interfacetemplate.md b/docs/models/dcim/interfacetemplate.md index e11abcce4..898c4843f 100644 --- a/docs/models/dcim/interfacetemplate.md +++ b/docs/models/dcim/interfacetemplate.md @@ -1,3 +1,3 @@ -## Interface Templates +# Interface Templates -A template for a network interface that will be created on all instantiations of the parent device type. Each interface may be assigned a physical or virtual type, and may be designated as "management-only." Power over Ethernet (PoE) mode and type may also be assigned to interface templates. +A template for a network interface that will be created on all instantiations of the parent device type. See the [interface](./interface.md) documentation for more detail. diff --git a/docs/models/dcim/inventoryitem.md b/docs/models/dcim/inventoryitem.md index fbd3172bb..1c2e894ed 100644 --- a/docs/models/dcim/inventoryitem.md +++ b/docs/models/dcim/inventoryitem.md @@ -2,6 +2,42 @@ Inventory items represent hardware components installed within a device, such as a power supply or CPU or line card. They are intended to be used primarily for inventory purposes. -Each inventory item can be assigned a functional role, manufacturer, part ID, serial number, and asset tag (all optional). A boolean toggle is also provided to indicate whether each item was entered manually or discovered automatically (by some process outside NetBox). - Inventory items are hierarchical in nature, such that any individual item may be designated as the parent for other items. For example, an inventory item might be created to represent a line card which houses several SFP optics, each of which exists as a child item within the device. An inventory item may also be associated with a specific component within the same device. For example, you may wish to associate a transceiver with an interface. + +## Fields + +### Device + +The device in which the inventory item is installed. + +### Parent + +The parent inventory item to which this item is assigned (optional). + +### Name + +The inventory item's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the inventory item. + +### Role + +The functional [role](./inventoryitemrole.md) assigned to this inventory item. + +### Manufacturer + +The [manufacturer](./manufacturer.md) that produced the item. + +### Part ID + +The part identification or model number assigned by the manufacturer. + +### Serial Number + +The serial number assigned by the manufacturer. + +### Asset Tag + +A unique, locally-administered label used to identify hardware resources. diff --git a/docs/models/dcim/inventoryitemtemplate.md b/docs/models/dcim/inventoryitemtemplate.md index 3167ed4ab..02fde5995 100644 --- a/docs/models/dcim/inventoryitemtemplate.md +++ b/docs/models/dcim/inventoryitemtemplate.md @@ -1,3 +1,3 @@ # Inventory Item Templates -A template for an inventory item that will be automatically created when instantiating a new device. All attributes of this object will be copied to the new inventory item, including the associations with a parent item and assigned component, if any. +A template for an inventory item that will be automatically created when instantiating a new device. All attributes of this object will be copied to the new inventory item, including the associations with a parent item and assigned component, if any. See the [inventory item](./inventoryitem.md) documentation for more detail. diff --git a/docs/models/dcim/modulebay.md b/docs/models/dcim/modulebay.md index 6c6f94598..9291ff554 100644 --- a/docs/models/dcim/modulebay.md +++ b/docs/models/dcim/modulebay.md @@ -1,3 +1,24 @@ -## Module Bays +# Module Bays -Module bays represent a space or slot within a device in which a field-replaceable module may be installed. A common example is that of a chassis-based switch such as the Cisco Nexus 9000 or Juniper EX9200. Modules in turn hold additional components that become available to the parent device. +Module bays represent a space or slot within a device in which a field-replaceable [module](./module.md) may be installed. A common example is that of a chassis-based switch such as the Cisco Nexus 9000 or Juniper EX9200. Modules in turn hold additional components that become available to the parent device. + +!!! note + If you need to model child devices rather than modules, use a [device bay](./devicebay.md) instead. + +## Fields + +### Device + +The device to which this module bay belongs. + +### Name + +The module bay's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the module bay. + +### Position + +The numeric position in which this module bay is situated. For example, this would be the number assigned to a slot within a chassis-based switch. diff --git a/docs/models/dcim/modulebaytemplate.md b/docs/models/dcim/modulebaytemplate.md index 463789305..3d5845d2e 100644 --- a/docs/models/dcim/modulebaytemplate.md +++ b/docs/models/dcim/modulebaytemplate.md @@ -1,3 +1,3 @@ -## Module Bay Templates +# Module Bay Templates -A template for a module bay that will be created on all instantiations of the parent device type. Module bays hold installed modules that do not have an independent management plane, such as line cards. +A template for a module bay that will be created on all instantiations of the parent device type. See the [module bay](./modulebay.md) documentation for more detail. diff --git a/docs/models/dcim/poweroutlet.md b/docs/models/dcim/poweroutlet.md index e9ef307bd..f6ca2c143 100644 --- a/docs/models/dcim/poweroutlet.md +++ b/docs/models/dcim/poweroutlet.md @@ -1,7 +1,39 @@ -## Power Outlets +# Power Outlets -Power outlets represent the outlets on a power distribution unit (PDU) or other device that supply power to dependent devices. Each power port may be assigned a physical type, and may be associated with a specific feed leg (where three-phase power is used) and/or a specific upstream power port. This association can be used to model the distribution of power within a device. +Power outlets represent the outlets on a power distribution unit (PDU) or other device that supplies power to dependent devices. Each power port may be assigned a physical type, and may be associated with a specific feed leg (where three-phase power is used) and/or a specific upstream power port. This association can be used to model the distribution of power within a device. For example, imagine a PDU with one power port which draws from a three-phase feed and 48 power outlets arranged into three banks of 16 outlets each. Outlets 1-16 would be associated with leg A on the port, and outlets 17-32 and 33-48 would be associated with legs B and C, respectively. -Cables can connect power outlets only to downstream power ports. (Pass-through ports cannot be used to model power distribution.) +## Fields + +### Device + +The device to which this power outlet belongs. + +### Module + +The installed module within the assigned device to which this power outlet belongs (optional). + +### Name + +The name of the power outlet. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the power outlet. + +### Type + +The type of power outlet. + +### Power Port + +When modeling a device which redistributes power from an upstream supply, such as a power distribution unit (PDU), each power outlet should be mapped to the respective [power port](./powerport.md) on the device which supplies power. For example, a 24-outlet PDU may two power ports, each distributing power to 12 of its outlets. + +### Feed Leg + +This field is used to indicate to which leg of three-phase power circuit the outlet is bound. (This should be left blank for single-phase applications.) + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/poweroutlettemplate.md b/docs/models/dcim/poweroutlettemplate.md index 6f81891f1..0803ede97 100644 --- a/docs/models/dcim/poweroutlettemplate.md +++ b/docs/models/dcim/poweroutlettemplate.md @@ -1,3 +1,3 @@ -## Power Outlet Templates +# Power Outlet Templates -A template for a power outlet that will be created on all instantiations of the parent device type. Each power outlet can be assigned a physical type, and its power source may be mapped to a specific feed leg and power port template. This association will be automatically replicated when the device type is instantiated. +A template for a power outlet that will be created on all instantiations of the parent device type. See the [power outlet](./poweroutlet.md) documentation for more detail. diff --git a/docs/models/dcim/powerport.md b/docs/models/dcim/powerport.md index 1948920d0..cfe513fbd 100644 --- a/docs/models/dcim/powerport.md +++ b/docs/models/dcim/powerport.md @@ -1,8 +1,40 @@ -## Power Ports +# Power Ports -A power port represents the inlet of a device where it draws its power, i.e. the connection port(s) on a device's power supply. Each power port may be assigned a physical type, as well as allocated and maximum draw values (in watts). These values can be used to calculate the overall utilization of an upstream power feed. +A power port is a device component which draws power from some external source (e.g. an upstream [power outlet](./poweroutlet.md)), and generally represents a power supply internal to a device. + +## Fields + +### Device + +The device to which this power port belongs. + +### Module + +The installed module within the assigned device to which this power port belongs (optional). + +### Name + +The name of the power port. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the power port. + +### Type + +The type of power port. + +### Maximum Draw + +The maximum amount of power this port consumes (in watts). !!! info - When creating a power port on a device which supplies power to downstream devices, the allocated and maximum draw numbers should be left blank. Utilization will be calculated by taking the sum of all power ports of devices connected downstream. + When creating a power port on a device which is mapped to outlets and supplies power to downstream devices, the maximum and allocated draw numbers should be left blank. Utilization will be calculated by taking the sum of all power ports of devices connected downstream. -Cables can connect power ports only to power outlets or power feeds. (Pass-through ports cannot be used to model power distribution.) +### Allocated Draw + +The budgeted amount of power this port consumes (in watts). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/powerporttemplate.md b/docs/models/dcim/powerporttemplate.md index 947f146ae..32579f4d5 100644 --- a/docs/models/dcim/powerporttemplate.md +++ b/docs/models/dcim/powerporttemplate.md @@ -1,3 +1,3 @@ -## Power Port Templates +# Power Port Templates -A template for a power port that will be created on all instantiations of the parent device type. Each power port can be assigned a physical type, as well as a maximum and allocated draw in watts. +A template for a power port that will be created on all instantiations of the parent device type. See the [power port](./powerport.md) documentation for more detail. diff --git a/docs/models/dcim/rearport.md b/docs/models/dcim/rearport.md index 41c5b3037..3d161f65d 100644 --- a/docs/models/dcim/rearport.md +++ b/docs/models/dcim/rearport.md @@ -1,6 +1,40 @@ -## Rear Ports +# Rear Ports -Like front ports, rear ports are pass-through ports which represent the continuation of a path from one cable to the next. Each rear port is defined with its physical type and a number of positions: Rear ports with more than one position can be mapped to multiple front ports. This can be useful for modeling instances where multiple paths share a common cable (for example, six discrete two-strand fiber connections sharing a 12-strand MPO cable). +Like [front ports](./frontport.md), rear ports are pass-through ports which represent the continuation of a path from one cable to the next. Each rear port is defined with its physical type and a number of positions: Rear ports with more than one position can be mapped to multiple front ports. This can be useful for modeling instances where multiple paths share a common cable (for example, six discrete two-strand fiber connections sharing a 12-strand MPO cable). !!! note Front and rear ports need not necessarily reside on the actual front or rear device face. This terminology is used primarily to distinguish between the two components in a pass-through port pairing. + +## Fields + +### Device + +The device to which this port belongs. + +### Module + +The installed module within the assigned device to which this port belongs (optional). + +### Name + +The port's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the port. + +### Type + +The port's termination type. + +### Color + +The port's color (optional). + +### Positions + +The number of [front ports](./frontport.md) to which this rear port can be mapped. For example, an MPO fiber termination cassette might have a single 12-strand rear port mapped to 12 discrete front ports, each terminating a single fiber strand. (For rear ports which map directly to a single front port, set this to `1`.) + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/rearporttemplate.md b/docs/models/dcim/rearporttemplate.md index 01ba02ac0..00cdfa5d2 100644 --- a/docs/models/dcim/rearporttemplate.md +++ b/docs/models/dcim/rearporttemplate.md @@ -1,3 +1,3 @@ -## Rear Port Templates +# Rear Port Templates -A template for a rear-facing pass-through port that will be created on all instantiations of the parent device type. Each rear port may have a physical type and one or more front port templates assigned to it. The number of positions associated with a rear port determines how many front ports can be assigned to it (the maximum is 1024). +A template for a rear-facing pass-through port that will be created on all instantiations of the parent device type. See the [rear port](./rearport.md) documentation for more detail. From 4307f078edf8f94137b451150eeacf932d98f8b6 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 15 Aug 2022 15:16:02 -0400 Subject: [PATCH 25/28] Finish refreshing DCIM models documentation --- docs/models/dcim/cable.md | 36 +++++++++--- docs/models/dcim/consoleserverport.md | 2 +- docs/models/dcim/device.md | 82 ++++++++++++++++++++++++++- docs/models/dcim/devicebay.md | 3 + docs/models/dcim/devicerole.md | 18 ++++++ docs/models/dcim/devicetype.md | 44 +++++++++++--- docs/models/dcim/frontport.md | 3 + docs/models/dcim/interface.md | 3 + docs/models/dcim/inventoryitem.md | 3 + docs/models/dcim/inventoryitemrole.md | 14 +++++ docs/models/dcim/location.md | 27 ++++++++- docs/models/dcim/manufacturer.md | 12 +++- docs/models/dcim/module.md | 32 ++++++++++- docs/models/dcim/modulebay.md | 3 + docs/models/dcim/moduletype.md | 18 +++++- docs/models/dcim/platform.md | 28 ++++++++- docs/models/dcim/powerfeed.md | 58 +++++++++++++++---- docs/models/dcim/poweroutlet.md | 3 + docs/models/dcim/powerpanel.md | 18 +++++- docs/models/dcim/powerport.md | 3 + docs/models/dcim/rack.md | 63 +++++++++++++++++--- docs/models/dcim/rackreservation.md | 20 ++++++- docs/models/dcim/rackrole.md | 16 +++++- docs/models/dcim/rearport.md | 3 + docs/models/dcim/region.md | 16 +++++- docs/models/dcim/site.md | 52 ++++++++++++++--- docs/models/dcim/sitegroup.md | 16 +++++- docs/models/dcim/virtualchassis.md | 21 +++++-- 28 files changed, 547 insertions(+), 70 deletions(-) diff --git a/docs/models/dcim/cable.md b/docs/models/dcim/cable.md index 43c0abfab..20f6c03c7 100644 --- a/docs/models/dcim/cable.md +++ b/docs/models/dcim/cable.md @@ -1,24 +1,42 @@ # Cables -All connections between device components in NetBox are represented using cables. A cable represents a direct physical connection between two termination points, such as between a console port and a patch panel port, or between two network interfaces. +All connections between device components in NetBox are represented using cables. A cable represents a direct physical connection between two sets of endpoints (A and B), such as a console port and a patch panel port, or between two network interfaces. Cables may be connected to the following objects: -Each cable must have two endpoints defined. These endpoints are sometimes referenced as A and B for clarity, however cables are direction-agnostic and the order in which terminations are made has no meaning. Cables may be connected to the following objects: - -* Circuit terminations +* Network interfaces * Console ports * Console server ports -* Interfaces * Pass-through ports (front and rear) -* Power feeds -* Power outlets +* Circuit terminations * Power ports +* Power outlets +* Power feeds -Each cable may be assigned a type, label, length, and color. Each cable is also assigned one of three operational statuses: +## Fields + +### Status + +The cable's operational status. Choices include: * Active (default) * Planned * Decommissioning +### Type + +The cable's physical medium or classification. + +### Label + +An arbitrary label used to identify the cable. + +### Color + +The color of the cable. + +### Length + +The numeric length of the cable, including a unit designation (e.g. 100 meters or 25 feet). + ## Tracing Cables -A cable may be traced from either of its endpoints by clicking the "trace" button. (A REST API endpoint also provides this functionality.) NetBox will follow the path of connected cables from this termination across the directly connected cable to the far-end termination. If the cable connects to a pass-through port, and the peer port has another cable connected, NetBox will continue following the cable path until it encounters a non-pass-through or unconnected termination point. The entire path will be displayed to the user. +A cable may be traced from any of its endpoints by clicking the "trace" button. (A REST API endpoint also provides this functionality.) NetBox will follow the path of connected cables from this termination across the directly connected cable to the far-end termination. If the cable connects to a pass-through port, and the peer port has another cable connected, NetBox will continue following the cable path until it encounters a non-pass-through or unconnected termination point. The entire path will be displayed to the user. diff --git a/docs/models/dcim/consoleserverport.md b/docs/models/dcim/consoleserverport.md index 1fbb653a8..5c45451db 100644 --- a/docs/models/dcim/consoleserverport.md +++ b/docs/models/dcim/consoleserverport.md @@ -33,4 +33,4 @@ Operating speed, in bits per second (bps). ### Mark Connected -If selected, this component will be treated as if a cable has been connected. \ No newline at end of file +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/device.md b/docs/models/dcim/device.md index a99078472..ddf1bfb09 100644 --- a/docs/models/dcim/device.md +++ b/docs/models/dcim/device.md @@ -8,8 +8,86 @@ A device is said to be full-depth if its installation on one rack face prevents Each device must be instantiated from a pre-created device type, and its default components (console ports, power ports, interfaces, etc.) will be created automatically. (The device type associated with a device may be changed after its creation, however its components will not be updated retroactively.) -Each device must be assigned a site, device role, and operational status, and may optionally be assigned to a specific location and/or rack within a site. A platform, serial number, and asset tag may optionally be assigned to each device. - Device names must be unique within a site, unless the device has been assigned to a tenant. Devices may also be unnamed. When a device has one or more interfaces with IP addresses assigned, a primary IP for the device can be designated, for both IPv4 and IPv6. + +## Fields + +### Name + +The device's configured name. This field is optional; devices can be unnamed. However, if set, the name must be unique to the assigned site and tenant. + +### Device Role + +The functional [role](./devicerole.md) assigned to this device. + +### Device Type + +The hardware [device type](./devicetype.md) which defines the device's make & model. Upon creating, all templated components assigned to the device type will be replicated on the new device. + +### Airflow + +The direction in which air circulates through the device chassis for cooling. + +### Serial Number + +The unique physical serial number assigned to this device by its manufacturer. + +### Asset Tag + +A unique, locally-administered label used to identify hardware resources. + +### Site + +The [site](./site.md) in which this device is located. + +### Location + +A specific [location](./location.md) where this device resides within the assigned site (optional). + +### Rack + +The [rack](./rack.md) within which this device is installed (optional). + +### Rack Face + +If installed in a rack, this field denotes the primary face on which the device is mounted. + +### Position + +If installed in a rack, this field indicates the base rack unit in which the device is mounted. + +!!! tip + Devices with a height of more than one rack unit should be set to the lowest-numbered rack unit that they occupy. + +### Status + +The device's operational status. + +!!! tip + Additional statuses may be defined by setting `Device.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Platform + +A device may be associated with a particular [platform](./platform.md) to indicate its operating system. Note that only platforms assigned to the associated manufacturer (or to no manufacturer) will be available for selection. + +### Cluster + +If this device will serve as a host for a virtualization [cluster](../virtualization/cluster.md), it can be assigned here. (Host devices can also be assigned by editing the cluster.) + +### Virtual Chassis + +The [virtual chassis](./virtualchassis.md) of which this device is a member, if any. + +### VC Position + +If assigned to a [virtual chassis](./virtualchassis.md), this field indicates the device's member position. + +### VC Priority + +If assigned to a [virtual chassis](./virtualchassis.md), this field indicates the device's priority for master election. + +### Local Config Context Data + +Any unique [context data](../../features/context-data.md) to be associated with the device. diff --git a/docs/models/dcim/devicebay.md b/docs/models/dcim/devicebay.md index f4f807c4a..5bbb125f8 100644 --- a/docs/models/dcim/devicebay.md +++ b/docs/models/dcim/devicebay.md @@ -7,6 +7,9 @@ Child devices are first-class Devices in their own right: That is, they are full !!! note Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as [modules](./module.md) installed within [module bays](./modulebay.md). +!!! tip + Like most device components, device bays are instantiated automatically from [device bay templates](./devicebaytemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/devicerole.md b/docs/models/dcim/devicerole.md index 13b8f021e..e9bdc0fa6 100644 --- a/docs/models/dcim/devicerole.md +++ b/docs/models/dcim/devicerole.md @@ -1,3 +1,21 @@ # Device Roles Devices can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for core switches, distribution switches, and access switches within your network. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Color + +The color used when displaying the role in the NetBox UI. + +### VM Role + +If selected, this role may be assigned to [virtual machines](../virtualization/virtualmachine.md) diff --git a/docs/models/dcim/devicetype.md b/docs/models/dcim/devicetype.md index cf42185f4..050f93244 100644 --- a/docs/models/dcim/devicetype.md +++ b/docs/models/dcim/devicetype.md @@ -4,13 +4,43 @@ A device type represents a particular make and model of hardware that exists in Device types are instantiated as devices installed within sites and/or equipment racks. For example, you might define a device type to represent a Juniper EX4300-48T network switch with 48 Ethernet interfaces. You can then create multiple _instances_ of this type named "switch1," "switch2," and so on. Each device will automatically inherit the components (such as interfaces) of its device type at the time of creation. However, changes made to a device type will **not** apply to instances of that device type retroactively. -Some devices house child devices which share physical resources, like space and power, but which function independently. A common example of this is blade server chassis. Each device type is designated as one of the following: - -* A parent device (which has device bays) -* A child device (which must be installed within a device bay) -* Neither - !!! note This parent/child relationship is **not** suitable for modeling chassis-based devices, wherein child members share a common control plane. Instead, line cards and similarly non-autonomous hardware should be modeled as modules or inventory items within a device. -A device type may optionally specify an airflow direction, such as front-to-rear, rear-to-front, or passive. Airflow direction may also be set separately per device. If it is not defined for a device at the time of its creation, it will inherit the airflow setting of its device type. +## Fields + +### Manufacturer + +The [manufacturer](./manufacturer.md) which produces this type of device. + +### Model + +The model number assigned to this device type by its manufacturer. Must be unique to the manufacturer. + +### Slug + +A unique URL-friendly representation of the model identifier. (This value can be used for filtering.) + +### Part Number + +An alternative part number to uniquely identify the device type. + +### Height + +The height of the physical device in rack units. (For device types that are not rack-mountable, this should be `0`.) + +### Is Full Depth + +If selected, this device type is considered to occupy both the front and rear faces of a rack, regardless of which face it is assigned. + +### Parent/Child Status + +Indicates whether this is a parent type (capable of housing child devices), a child type (which must be installed within a device bay), or neither. + +### Airflow + +The default direction in which airflow circulates within the device chassis. This may be configured differently for instantiated devices (e.g. because of different fan modules). + +### Front & Rear Images + +Users can upload illustrations of the device's front and rear panels. If present, these will be used to render the device in [rack](./rack.md) elevation diagrams. diff --git a/docs/models/dcim/frontport.md b/docs/models/dcim/frontport.md index 0b291c9ed..7ea617250 100644 --- a/docs/models/dcim/frontport.md +++ b/docs/models/dcim/frontport.md @@ -2,6 +2,9 @@ Front ports are pass-through ports which represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific [rear port](./rearport.md) on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each. +!!! tip + Like most device components, front ports are instantiated automatically from [front port templates](./frontporttemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/interface.md b/docs/models/dcim/interface.md index b69f7c6b1..42b570964 100644 --- a/docs/models/dcim/interface.md +++ b/docs/models/dcim/interface.md @@ -2,6 +2,9 @@ Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. IP addresses and VLANs can be assigned to interfaces. +!!! tip + Like most device components, interfaces are instantiated automatically from [interface templates](./interfacetemplate.md) assigned to the selected device type when a device is created. + !!! note Although both devices and virtual machines both can have interfaces assigned, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa. diff --git a/docs/models/dcim/inventoryitem.md b/docs/models/dcim/inventoryitem.md index 1c2e894ed..f61586eda 100644 --- a/docs/models/dcim/inventoryitem.md +++ b/docs/models/dcim/inventoryitem.md @@ -4,6 +4,9 @@ Inventory items represent hardware components installed within a device, such as Inventory items are hierarchical in nature, such that any individual item may be designated as the parent for other items. For example, an inventory item might be created to represent a line card which houses several SFP optics, each of which exists as a child item within the device. An inventory item may also be associated with a specific component within the same device. For example, you may wish to associate a transceiver with an interface. +!!! tip + Like most device components, inventory items can be instantiated automatically from [templates](./inventoryitemtemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/inventoryitemrole.md b/docs/models/dcim/inventoryitemrole.md index 8ed31481a..50eb61abd 100644 --- a/docs/models/dcim/inventoryitemrole.md +++ b/docs/models/dcim/inventoryitemrole.md @@ -1,3 +1,17 @@ # Inventory Item Roles Inventory items can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for power supplies, fans, interface optics, etc. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Color + +The color used when displaying the role in the NetBox UI. diff --git a/docs/models/dcim/location.md b/docs/models/dcim/location.md index fb72c218d..96ab13039 100644 --- a/docs/models/dcim/location.md +++ b/docs/models/dcim/location.md @@ -1,5 +1,28 @@ # Locations -Racks and devices can be grouped by location within a site. A location may represent a floor, room, cage, or similar organizational unit. Locations can be nested to form a hierarchy. For example, you may have floors within a site, and rooms within a floor. +[Racks](./rack.md) and [devices](./device.md) can be grouped by location within a [site](./site.md). A location may represent a floor, room, cage, or similar organizational unit. Locations can be nested to form a hierarchy. For example, you may have floors within a site, and rooms within a floor. -Each location must have a name that is unique within its parent site and location, if any, and must be assigned an operational status. (The set of available statuses is configurable.) +## Fields + +### Site + +The parent [site](./site.md) to which this location belongs. + +### Parent + +The parent location of which this location is a child (optional). + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Status + +The location's operational status. + +!!! tip + Additional statuses may be defined by setting `Location.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. diff --git a/docs/models/dcim/manufacturer.md b/docs/models/dcim/manufacturer.md index df227ee17..6beee5a90 100644 --- a/docs/models/dcim/manufacturer.md +++ b/docs/models/dcim/manufacturer.md @@ -1,3 +1,13 @@ # Manufacturers -A manufacturer represents the "make" of a device; e.g. Cisco or Dell. Each device type must be assigned to a manufacturer. (Inventory items and platforms may also be associated with manufacturers.) Each manufacturer must have a unique name and may have a description assigned to it. +A manufacturer represents the "make" of a device; e.g. Cisco or Dell. Each [device type](./devicetype.md) must be assigned to a manufacturer. ([Inventory items](./inventoryitem.md) and [platforms](./platform.md) may also be associated with manufacturers.) + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/dcim/module.md b/docs/models/dcim/module.md index bc9753ecc..c90430faa 100644 --- a/docs/models/dcim/module.md +++ b/docs/models/dcim/module.md @@ -2,4 +2,34 @@ A module is a field-replaceable hardware component installed within a device which houses its own child components. The most common example is a chassis-based router or switch. -Similar to devices, modules are instantiated from module types, and any components associated with the module type are automatically instantiated on the new model. Each module must be installed within a module bay on a device, and each module bay may have only one module installed in it. A module may optionally be assigned a serial number and asset tag. +Similar to devices, modules are instantiated from [module types](./moduletype.md), and any components associated with the module type are automatically instantiated on the new model. Each module must be installed within a [module bay](./modulebay.md) on a [device](./device.md), and each module bay may have only one module installed in it. + +## Fields + +### Device + +The parent [device](./device.md) into which the module is installed. + +### Module Bay + +The [module bay](./modulebay.md) into which the module is installed. + +### Module Type + +The [module type](./moduletype.md) which represents the physical make & model of hardware. By default, module components will be instantiated automatically from the module type when creating a new module. + +### Serial Number + +The unique physical serial number assigned to this module by its manufacturer. + +### Asset Tag + +A unique, locally-administered label used to identify hardware resources. + +### Replicate Components + +Controls whether templates module type components are automatically added when creating a new module. + +### Adopt Components + +Controls whether pre-existing components assigned to the device with the same names as components that would be created automatically will be assigned to the new module. diff --git a/docs/models/dcim/modulebay.md b/docs/models/dcim/modulebay.md index 9291ff554..c77909511 100644 --- a/docs/models/dcim/modulebay.md +++ b/docs/models/dcim/modulebay.md @@ -5,6 +5,9 @@ Module bays represent a space or slot within a device in which a field-replaceab !!! note If you need to model child devices rather than modules, use a [device bay](./devicebay.md) instead. +!!! tip + Like most device components, module bays are instantiated automatically from [module bay templates](./modulebaytemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/moduletype.md b/docs/models/dcim/moduletype.md index c1c8c5079..b8ec0ac6e 100644 --- a/docs/models/dcim/moduletype.md +++ b/docs/models/dcim/moduletype.md @@ -1,8 +1,8 @@ # Module Types -A module type represent a specific make and model of hardware component which is installable within a device and has its own child components. For example, consider a chassis-based switch or router with a number of field-replaceable line cards. Each line card has its own model number and includes a certain set of components such as interfaces. Each module type may have a manufacturer, model number, and part number assigned to it. +A module type represents a specific make and model of hardware component which is installable within a device's [module bay](./modulebay.md) and has its own child components. For example, consider a chassis-based switch or router with a number of field-replaceable line cards. Each line card has its own model number and includes a certain set of components such as interfaces. Each module type may have a manufacturer, model number, and part number assigned to it. -Similar to device types, each module type can have any of the following component templates associated with it: +Similar to [device types](./devicetype.md), each module type can have any of the following component templates associated with it: * Interfaces * Console ports @@ -21,3 +21,17 @@ When adding component templates to a module type, the string `{module}` can be u For example, you can create a module type with interface templates named `Gi{module}/0/[1-48]`. When a new module of this type is "installed" to a module bay with a position of "3", NetBox will automatically name these interfaces `Gi3/0/[1-48]`. Automatic renaming is supported for all modular component types (those listed above). + +## Fields + +### Manufacturer + +The [manufacturer](./manufacturer.md) which produces this type of module. + +### Model + +The model number assigned to this module type by its manufacturer. Must be unique to the manufacturer. + +### Part Number + +An alternative part number to uniquely identify the module type. diff --git a/docs/models/dcim/platform.md b/docs/models/dcim/platform.md index 347abc5b8..d080f74a4 100644 --- a/docs/models/dcim/platform.md +++ b/docs/models/dcim/platform.md @@ -1,9 +1,31 @@ # Platforms -A platform defines the type of software running on a device or virtual machine. This can be helpful to model when it is necessary to distinguish between different versions or feature sets. Note that two devices of the same type may be assigned different platforms: For example, one Juniper MX240 might run Junos 14 while another runs Junos 15. +A platform defines the type of software running on a [device](./device.md) or [virtual machine](../virtualization/virtualmachine.md). This can be helpful to model when it is necessary to distinguish between different versions or feature sets. Note that two devices of the same type may be assigned different platforms: For example, one Juniper MX240 might run Junos 14 while another runs Junos 15. -Platforms may optionally be limited by manufacturer: If a platform is assigned to a particular manufacturer, it can only be assigned to devices with a type belonging to that manufacturer. +Platforms may optionally be limited by [manufacturer](./manufacturer.md): If a platform is assigned to a particular manufacturer, it can only be assigned to devices with a type belonging to that manufacturer. -The platform model is also used to indicate which NAPALM driver (if any) and any associated arguments NetBox should use when connecting to a remote device. The name of the driver along with optional parameters are stored with the platform. +The platform model is also used to indicate which [NAPALM driver](../../integrations/napalm.md) (if any) and any associated arguments NetBox should use when connecting to a remote device. The name of the driver along with optional parameters are stored with the platform. The assignment of platforms to devices is an optional feature, and may be disregarded if not desired. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Manufacturer + +If designated, this platform will be available for use only to devices assigned to this [manufacturer](./manufacturer.md). This can be handy e.g. for limiting network operating systems to use on hardware produced by the relevant vendor. However, it should not be used when defining general-purpose software platforms. + +### NAPALM Driver + +The [NAPALM driver](https://napalm.readthedocs.io/en/latest/support/index.html) associated with this platform. + +### NAPALM Arguments + +Any additional arguments to send when invoking the NAPALM driver assigned to this platform. diff --git a/docs/models/dcim/powerfeed.md b/docs/models/dcim/powerfeed.md index bac7214f1..f98c758ff 100644 --- a/docs/models/dcim/powerfeed.md +++ b/docs/models/dcim/powerfeed.md @@ -1,21 +1,55 @@ # Power Feed -A power feed represents the distribution of power from a power panel to a particular device, typically a power distribution unit (PDU). The power port (inlet) on a device can be connected via a cable to a power feed. A power feed may optionally be assigned to a rack to allow more easily tracking the distribution of power among racks. +A power feed represents the distribution of power from a [power panel](./powerpanel.md) to a particular [device](./device.md), typically a power distribution unit (PDU). The [power port](./powerport.md) (inlet) on a device can be connected via a cable to a power feed. A power feed may optionally be assigned to a rack to allow more easily tracking the distribution of power among racks. -Each power feed is assigned an operational type (primary or redundant) and one of the following statuses: +## Fields -* Offline -* Active -* Planned -* Failed +### Power Panel -Each power feed also defines the electrical characteristics of the circuit which it represents. These include the following: +The [power panel](./powerpanel.md) which supplies upstream power to this feed. -* Supply type (AC or DC) -* Phase (single or three-phase) -* Voltage -* Amperage -* Maximum utilization (percentage) +### Rack + +The [rack](./rack.md) within which this feed delivers power (optional). + +### Name + +The feed's name or other identifier. Must be unique to the assigned power panel. + +### Status + +The feed's operational status. + +!!! tip + Additional statuses may be defined by setting `PowerFeed.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Type + +In redundant environments, each power feed can be designated as providing either primary or redundant power. (In environment with only one power source, all power feeds should be designated as primary.) + +### Mark Connected + +If selected, the power feed will be treated as if a cable has been connected. + +### Supply + +Electrical current type (AC or DC). + +### Voltage + +Operating circuit voltage, in volts. + +### Amperage + +Operation circuit amperage, in amperes. + +### Phase + +Indicates whether the circuit provides single- or three-phase power. + +### Max Utilization + +The maximum safe utilization of the feed, expressed as a percentage of the total available power. (Typically this will be set to around 80%, to avoid tripping a breaker during heaving spikes in current draw.) !!! info The power utilization of a rack is calculated when one or more power feeds are assigned to the rack and connected to devices that draw power. diff --git a/docs/models/dcim/poweroutlet.md b/docs/models/dcim/poweroutlet.md index f6ca2c143..5c8bd6ff0 100644 --- a/docs/models/dcim/poweroutlet.md +++ b/docs/models/dcim/poweroutlet.md @@ -4,6 +4,9 @@ Power outlets represent the outlets on a power distribution unit (PDU) or other For example, imagine a PDU with one power port which draws from a three-phase feed and 48 power outlets arranged into three banks of 16 outlets each. Outlets 1-16 would be associated with leg A on the port, and outlets 17-32 and 33-48 would be associated with legs B and C, respectively. +!!! tip + Like most device components, power outlets are instantiated automatically from [power outlet templates](./poweroutlettemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/powerpanel.md b/docs/models/dcim/powerpanel.md index 813321179..dd02a57f0 100644 --- a/docs/models/dcim/powerpanel.md +++ b/docs/models/dcim/powerpanel.md @@ -1,8 +1,20 @@ # Power Panel -A power panel represents the origin point in NetBox for electrical power being disseminated by one or more power feeds. In a data center environment, one power panel often serves a group of racks, with an individual power feed extending to each rack, though this is not always the case. It is common to have two sets of panels and feeds arranged in parallel to provide redundant power to each rack. - -Each power panel must be assigned to a site, and may optionally be assigned to a particular location within that site. +A power panel represents the origin point in NetBox for electrical power being disseminated by one or more [power feeds](./powerfeed.md). In a data center environment, one power panel often serves a group of racks, with an individual power feed extending to each rack, though this is not always the case. It is common to have two sets of panels and feeds arranged in parallel to provide redundant power to each rack. !!! note NetBox does not model the mechanism by which power is delivered to a power panel. Power panels define the root level of the power distribution hierarchy in NetBox. + +## Fields + +### Site + +The [site](./site.md) in which the power panel resides. + +### Location + +A specific [location](./location.md) within the assigned site where the power panel is installed. + +### Name + +The power panel's name. Must be unique to the assigned site. diff --git a/docs/models/dcim/powerport.md b/docs/models/dcim/powerport.md index cfe513fbd..7cc1dd60a 100644 --- a/docs/models/dcim/powerport.md +++ b/docs/models/dcim/powerport.md @@ -2,6 +2,9 @@ A power port is a device component which draws power from some external source (e.g. an upstream [power outlet](./poweroutlet.md)), and generally represents a power supply internal to a device. +!!! tip + Like most device components, power ports are instantiated automatically from [power port templates](./powerporttemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/rack.md b/docs/models/dcim/rack.md index 9465a828c..57e7bec98 100644 --- a/docs/models/dcim/rack.md +++ b/docs/models/dcim/rack.md @@ -1,12 +1,51 @@ # Racks -The rack model represents a physical two- or four-post equipment rack in which devices can be installed. Each rack must be assigned to a site, and may optionally be assigned to a location and/or tenant. Racks can also be organized by user-defined functional roles. The name and facility ID of each rack within a location must be unique. +The rack model represents a physical two- or four-post equipment rack in which [devices](./device.md) can be installed. Each rack must be assigned to a [site](./site.md), and may optionally be assigned to a [location](./location.md) within that site. Racks can also be organized by user-defined functional roles. The name and facility ID of each rack within a location must be unique. Rack height is measured in *rack units* (U); racks are commonly between 42U and 48U tall, but NetBox allows you to define racks of arbitrary height. A toggle is provided to indicate whether rack units are in ascending (from the ground up) or descending order. Each rack is assigned a name and (optionally) a separate facility ID. This is helpful when leasing space in a data center your organization does not own: The facility will often assign a seemingly arbitrary ID to a rack (for example, "M204.313") whereas internally you refer to is simply as "R113." A unique serial number and asset tag may also be associated with each rack. -A rack must be designated as one of the following types: +## Fields + +### Site + +The [site](./site.md) to which the rack is assigned. + +### Location + +The [location](./location.md) within a site where the rack has been installed (optional). + +### Name + +The rack's name or identifier. Must be unique to the rack's location, if assigned. + +### Status + +Operational status. + +!!! tip + Additional statuses may be defined by setting `Rack.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Role + +The functional [role](./rackrole.md) fulfilled by the rack. + +### Facility ID + +An alternative identifier assigned to the rack e.g. by the facility operator. This is helpful for tracking datacenter rack designations in a colocation facility. + +### Serial Number + +The unique physical serial number assigned to this rack. + +### Asset Tag + +A unique, locally-administered label used to identify hardware resources. + +### Type + +A rack can be designated as one of the following types: * 2-post frame * 4-post frame @@ -14,12 +53,18 @@ A rack must be designated as one of the following types: * Wall-mounted frame * Wall-mounted cabinet -Similarly, each rack must be assigned an operational status, which is one of the following: +### Width -* Reserved -* Available -* Planned -* Active -* Deprecated +The canonical distance between the two vertical rails on a face. (This is typically 19 inches, however other standard widths exist.) -Each rack has two faces (front and rear) on which devices can be mounted. Rail-to-rail width may be 10, 19, 21, or 23 inches. The outer width and depth of a rack or cabinet can also be annotated in millimeters or inches. +### Height + +The height of the rack, measured in units. + +### Outer Dimensions + +The external width and depth of the rack can be tracked to aid in floorplan calculations. These measurements must be designated in either millimeters or inches. + +### Descending Units + +If selected, the rack's elevation will display unit 1 at the top of the rack. (Most racks use asceneding numbering, with unit 1 assigned to the bottommost position.) diff --git a/docs/models/dcim/rackreservation.md b/docs/models/dcim/rackreservation.md index 0ed9651a0..32d52c9d7 100644 --- a/docs/models/dcim/rackreservation.md +++ b/docs/models/dcim/rackreservation.md @@ -1,3 +1,21 @@ # Rack Reservations -Users can reserve specific units within a rack for future use. An arbitrary set of units within a rack can be associated with a single reservation, but reservations cannot span multiple racks. A description is required for each reservation, reservations may optionally be associated with a specific tenant. +Users can reserve specific units within a [rack](./rackreservation.md) for future use. An arbitrary set of units within a rack can be associated with a single reservation, but reservations cannot span multiple racks. A description is required for each reservation, reservations may optionally be associated with a specific tenant. + +## Fields + +### Rack + +The [rack](./rack.md) being reserved. + +### Units + +The rack unit or units being reserved. Multiple units can be expressed using commas and/or hyphens. For example, `1,3,5-7` specifies units 1, 3, 5, 6, and 7. + +### User + +The NetBox user account associated with the reservation. Note that users with sufficient permission can make rack reservations for other users. + +### Description + +Every rack reservation must include a description of its purpose. diff --git a/docs/models/dcim/rackrole.md b/docs/models/dcim/rackrole.md index 1375ce692..88f171af8 100644 --- a/docs/models/dcim/rackrole.md +++ b/docs/models/dcim/rackrole.md @@ -1,3 +1,17 @@ # Rack Roles -Each rack can optionally be assigned a user-defined functional role. For example, you might designate a rack for compute or storage resources, or to house colocated customer devices. Rack roles are fully customizable and may be color-coded. +Each rack can optionally be assigned a user-defined functional role. For example, you might designate a rack for compute or storage resources, or to house colocated customer devices. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Color + +The color used when displaying the role in the NetBox UI. diff --git a/docs/models/dcim/rearport.md b/docs/models/dcim/rearport.md index 3d161f65d..b23d4a29b 100644 --- a/docs/models/dcim/rearport.md +++ b/docs/models/dcim/rearport.md @@ -5,6 +5,9 @@ Like [front ports](./frontport.md), rear ports are pass-through ports which repr !!! note Front and rear ports need not necessarily reside on the actual front or rear device face. This terminology is used primarily to distinguish between the two components in a pass-through port pairing. +!!! tip + Like most device components, rear ports are instantiated automatically from [rear port templates](./rearporttemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/region.md b/docs/models/dcim/region.md index bac186264..27673b2df 100644 --- a/docs/models/dcim/region.md +++ b/docs/models/dcim/region.md @@ -1,5 +1,17 @@ # Regions -Sites can be arranged geographically using regions. A region might represent a continent, country, city, campus, or other area depending on your use case. Regions can be nested recursively to construct a hierarchy. For example, you might define several country regions, and within each of those several state or city regions to which sites are assigned. +[Sites](./site.md) can be arranged geographically using regions. A region might represent a continent, country, city, campus, or other area depending on your use case. Regions can be nested recursively to construct a hierarchy. For example, you might define several country regions, and within each of those several state or city regions to which sites are assigned. -Each region must have a name that is unique within its parent region, if any. +## Fields + +### Parent + +The parent region, if any. + +### Name + +The region's name. Must be unique to the parent region, if one is assigned. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/dcim/site.md b/docs/models/dcim/site.md index 6617b950c..c74c209e1 100644 --- a/docs/models/dcim/site.md +++ b/docs/models/dcim/site.md @@ -2,14 +2,50 @@ How you choose to employ sites when modeling your network may vary depending on the nature of your organization, but generally a site will equate to a building or campus. For example, a chain of banks might create a site to represent each of its branches, a site for its corporate headquarters, and two additional sites for its presence in two colocation facilities. -Each site must be assigned a unique name and may optionally be assigned to a region and/or tenant. The following operational statuses are available: +## Fields -* Planned -* Staging -* Active -* Decommissioning -* Retired +### Name -The site model also provides a facility ID field which can be used to annotate a facility ID (such as a datacenter name) associated with the site. Each site may also have an autonomous system (AS) number and time zone associated with it. (Time zones are provided by the [pytz](https://pypi.org/project/pytz/) package.) +The site's unique name. -The site model also includes several fields for storing contact and address information as well as geolocation data (GPS coordinates). +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Status + +The site's operational status. + +!!! tip + Additional statuses may be defined by setting `Site.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Region + +The parent [region](./region.md) to which the site belongs, if any. + +### Facility + +Data center or facility designation for identifying the site. + +### ASNs + +Each site can have multiple [AS numbers](../ipam/asn.md) assigned to it. + +### Time Zone + +The site's local time zone. (Time zones are provided by the [pytz](https://pypi.org/project/pytz/) package.) + +### Physical Address + +The site's physical address, used for mapping. + +### Shipping Address + +The address to use for deliveries destined for the site. + +!!! tip + You can also designate [points of contact](../../features/contacts.md) for each site to provide additional contact details. + +### Latitude & Longitude + +GPS coordinates of the site for geolocation. diff --git a/docs/models/dcim/sitegroup.md b/docs/models/dcim/sitegroup.md index 04ebcc1a5..e1c5215d9 100644 --- a/docs/models/dcim/sitegroup.md +++ b/docs/models/dcim/sitegroup.md @@ -1,5 +1,17 @@ # Site Groups -Like regions, site groups can be used to organize sites. Whereas regions are intended to provide geographic organization, site groups can be used to classify sites by role or function. Also like regions, site groups can be nested to form a hierarchy. Sites which belong to a child group are also considered to be members of any of its parent groups. +Like [regions](./region.md), site groups can be used to organize [sites](./site.md). Whereas regions are intended to provide geographic organization, site groups can be used to classify sites by role or function. Also like regions, site groups can be nested to form a hierarchy. Sites which belong to a child group are also considered to be members of all its parent groups. -Each site group must have a name that is unique within its parent group, if any. +## Fields + +### Parent + +The parent site group, if any. + +### Name + +The site group's name. Must be unique to the parent group, if one is assigned. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/dcim/virtualchassis.md b/docs/models/dcim/virtualchassis.md index 2466b065d..e68b2fda6 100644 --- a/docs/models/dcim/virtualchassis.md +++ b/docs/models/dcim/virtualchassis.md @@ -1,9 +1,22 @@ # Virtual Chassis -A virtual chassis represents a set of devices which share a common control plane. A common example of this is a stack of switches which are connected and configured to operate as a single device. A virtual chassis must be assigned a name and may be assigned a domain. +A virtual chassis represents a set of devices which share a common control plane. A common example of this is a stack of switches which are connected and configured to operate as a single managed device. Each device in the virtual chassis is referred to as a VC member, and assigned a position and (optionally) a priority. VC member devices commonly reside within the same rack, though this is not a requirement. -Each device in the virtual chassis is referred to as a VC member, and assigned a position and (optionally) a priority. VC member devices commonly reside within the same rack, though this is not a requirement. One of the devices may be designated as the VC master: This device will typically be assigned a name, services, virtual interfaces, and other attributes related to managing the VC. -If a VC master is defined, interfaces from all VC members are displayed when navigating to its device interfaces view. This does not include other members interfaces declared as management-only. +One of the member devices may be designated as the VC master: This device will typically be assigned a name, services, virtual interfaces, and other attributes related to managing the VC. If a VC master is defined, interfaces from all VC members are displayed when navigating to its device interfaces view. This does not include management-only interfaces belonging to other members. !!! note - It's important to recognize the distinction between a virtual chassis and a chassis-based device. A virtual chassis is **not** suitable for modeling a chassis-based switch with removable line cards (such as the Juniper EX9208), as its line cards are _not_ physically autonomous devices. + It's important to recognize the distinction between a virtual chassis and a chassis-based device. A virtual chassis is **not** suitable for modeling a chassis-based switch with removable line cards (such as the Juniper EX9208), as its line cards are _not_ physically autonomous devices. Instead, use [modules](./module.md) for these. + +## Fields + +### Name + +The virtual chassis' name. + +### Domain + +The domain assigned for VC member devices. + +### Master + +The member device which has been designated as the chassis master (optional). From d43c98d546aa5f650db520b1bf7ce0f8f0446197 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 16 Aug 2022 15:32:00 -0400 Subject: [PATCH 26/28] Update IPAM models documentation --- docs/models/ipam/aggregate.md | 20 ++++++-- docs/models/ipam/asn.md | 20 +++++--- docs/models/ipam/fhrpgroup.md | 33 +++++++++--- docs/models/ipam/fhrpgroupassignment.md | 16 +++++- docs/models/ipam/ipaddress.md | 68 ++++++++++++++++--------- docs/models/ipam/iprange.md | 28 +++++++--- docs/models/ipam/l2vpn.md | 28 ++++++++-- docs/models/ipam/l2vpntermination.md | 17 ++++--- docs/models/ipam/prefix.md | 45 ++++++++++++---- docs/models/ipam/rir.md | 16 +++++- docs/models/ipam/role.md | 14 +++++ docs/models/ipam/routetarget.md | 6 ++- docs/models/ipam/service.md | 22 +++++++- docs/models/ipam/servicetemplate.md | 16 +++++- docs/models/ipam/vlan.md | 29 ++++++++--- docs/models/ipam/vlangroup.md | 20 +++++++- docs/models/ipam/vrf.md | 22 ++++++-- 17 files changed, 331 insertions(+), 89 deletions(-) diff --git a/docs/models/ipam/aggregate.md b/docs/models/ipam/aggregate.md index ff5a50a39..eadeb813c 100644 --- a/docs/models/ipam/aggregate.md +++ b/docs/models/ipam/aggregate.md @@ -20,9 +20,23 @@ NetBox allows us to specify the portions of IP space that are interesting to us * 192.168.0.0/16 (RFC 1918) * One or more /48s within fd00::/8 (IPv6 unique local addressing) -Each aggregate is assigned to a RIR. For "public" aggregates, this will be the real-world authority which has granted your organization permission to use the specified IP space on the public Internet. For "private" aggregates, this will be a statutory authority, such as RFC 1918. Each aggregate can also annotate that date on which it was allocated, where applicable. +Each aggregate is assigned to a [RIR](./rir.md). For "public" aggregates, this will be the real-world authority which has granted your organization permission to use the specified IP space on the public Internet. For "private" aggregates, this will be a statutory authority, such as RFC 1918. Each aggregate can also annotate that date on which it was allocated, where applicable. -Prefixes are automatically arranged beneath their parent aggregates in NetBox. Typically you'll want to create aggregates only for the prefixes and IP addresses that your organization actually manages: There is no need to define aggregates for provider-assigned space which is only used on Internet circuits, for example. +Prefixes are automatically arranged beneath their parent aggregates in NetBox. Typically, you'll want to create aggregates only for the prefixes and IP addresses that your organization actually manages: There is no need to define aggregates for provider-assigned space which is only used on Internet circuits, for example. !!! note - Because aggregates represent swaths of the global IP space, they cannot overlap with one another: They can only exist side-by-side. For instance, you cannot define both 10.0.0.0/8 and 10.16.0.0/16 as aggregates, because they overlap. 10.16.0.0/16 in this example would be created as a container prefix and automatically grouped under the 10.0.0.0/8 aggregate. Remember, the purpose of aggregates is to establish the root of your IP addressing hierarchy. + Because aggregates represent segments of the global IP space, they cannot overlap with one another: They can only exist side-by-side. For instance, you cannot define both 10.0.0.0/8 and 10.16.0.0/16 as aggregates, because they overlap. 10.16.0.0/16 in this example would be created as a container prefix and automatically grouped under the 10.0.0.0/8 aggregate. Remember, the purpose of aggregates is to establish the root of your IP addressing hierarchy. + +## Fields + +### Prefix + +The IPv4 or IPv6 network this aggregate represents. + +### RIR + +The [Regional Internet Registry](./rir.md) or similar authority which governs allocations of this address space from the global pool. + +### Date Added + +The date on which the address space was allocated or deployed. diff --git a/docs/models/ipam/asn.md b/docs/models/ipam/asn.md index cfef1da29..e34790406 100644 --- a/docs/models/ipam/asn.md +++ b/docs/models/ipam/asn.md @@ -1,15 +1,19 @@ # ASN -ASN is short for Autonomous System Number. This identifier is used in the BGP protocol to identify which "autonomous system" a particular prefix is originating and transiting through. +An Autonomous System Number (ASN) is a numeric identifier used in the BGP protocol to identify which [autonomous system](https://en.wikipedia.org/wiki/Autonomous_system_%28Internet%29) a particular prefix is originating and transiting through. NetBox support both 32- and 64- ASNs. -The AS number model within NetBox allows you to model some of this real-world relationship. +ASNs must be globally unique within NetBox, must each may be assigned to multiple [sites](../dcim/site.md). -Within NetBox: +## Fields -* AS numbers are globally unique -* Each AS number must be associated with a RIR (ARIN, RFC 6996, etc) -* Each AS number can be associated with many different sites -* Each site can have many different AS numbers -* Each AS number can be assigned to a single tenant +### AS Number +The 32- or 64-bit AS number. +### RIR + +The [Regional Internet Registry](./rir.md) or similar authority responsible for the allocation of this particular ASN. + +### Sites + +The [site(s)](../dcim/site.md) to which this ASN is assigned. diff --git a/docs/models/ipam/fhrpgroup.md b/docs/models/ipam/fhrpgroup.md index c5baccd7b..4da390310 100644 --- a/docs/models/ipam/fhrpgroup.md +++ b/docs/models/ipam/fhrpgroup.md @@ -1,10 +1,31 @@ # FHRP Group -A first-hop redundancy protocol (FHRP) enables multiple physical interfaces to present a virtual IP address in a redundant manner. Example of such protocols include: +A first-hop redundancy protocol (FHRP) enables multiple physical interfaces to present a virtual [IP address](./ipaddress.md) (VIP) in a redundant manner. Examples of such protocols include: -* Hot Standby Router Protocol (HSRP) -* Virtual Router Redundancy Protocol (VRRP) -* Common Address Redundancy Protocol (CARP) -* Gateway Load Balancing Protocol (GLBP) +* [Hot Standby Router Protocol](https://en.wikipedia.org/wiki/Hot_Standby_Router_Protocol) (HSRP) +* [Virtual Router Redundancy Protocol](https://en.wikipedia.org/wiki/Virtual_Router_Redundancy_Protocol) (VRRP) +* [Common Address Redundancy Protocol](https://en.wikipedia.org/wiki/Common_Address_Redundancy_Protocol) (CARP) +* [Gateway Load Balancing Protocol](https://en.wikipedia.org/wiki/Gateway_Load_Balancing_Protocol) (GLBP) -NetBox models these redundancy groups by protocol and group ID. Each group may optionally be assigned an authentication type and key. (Note that the authentication key is stored as a plaintext value in NetBox.) Each group may be assigned or more virtual IPv4 and/or IPv6 addresses. +When creating a new FHRP group, the user may optionally create a VIP as well. This IP address will be automatically assigned to the new group. (Virtual IP addresses can also be assigned after the group has been created.) + +## Fields + +### Protocol + +The wire protocol employed by cooperating servers to maintain the virtual [IP address(es)](./ipaddress.md) for the group. + +### Group ID + +The group's numeric identifier. + +### Authentication Type + +The type of authentication employed by group nodes, if any. + +### Authentication Key + +The shared key used for group authentication, if any. + +!!! warning + The authentication key value is stored in plaintext in NetBox's database. Do not utilize this field if you require encryption at rest for shared keys. diff --git a/docs/models/ipam/fhrpgroupassignment.md b/docs/models/ipam/fhrpgroupassignment.md index c3e0bf200..c65217c62 100644 --- a/docs/models/ipam/fhrpgroupassignment.md +++ b/docs/models/ipam/fhrpgroupassignment.md @@ -1,5 +1,19 @@ # FHRP Group Assignments -Member device and VM interfaces can be assigned to FHRP groups, along with a numeric priority value. For instance, three interfaces, each belonging to a different router, may each be assigned to the same FHRP group to serve a common virtual IP address. Each of these assignments would typically receive a different priority. +Member device and VM interfaces can be assigned to [FHRP groups](./fhrpgroup.md) to indicate their participation in maintaining a common virtual IP address (VIP). For instance, three interfaces, each belonging to a different router, may each be assigned to the same FHRP group to serve a shared VIP. Each of these assignments would typically receive a different priority. Interfaces are assigned to FHRP groups under the interface detail view. + +## Fields + +### Group + +The [FHRP group](./fhrpgroup.md) being assigned. + +### Interface + +The device or VM interface to which the group is being assigned. + +### Priority + +A value between 0 and 255 indicating the interface's priority for being elected as the master/primary node in the group. diff --git a/docs/models/ipam/ipaddress.md b/docs/models/ipam/ipaddress.md index 1ea613997..ecfdc4b96 100644 --- a/docs/models/ipam/ipaddress.md +++ b/docs/models/ipam/ipaddress.md @@ -1,30 +1,8 @@ # IP Addresses -An IP address comprises a single host address (either IPv4 or IPv6) and its subnet mask. Its mask should match exactly how the IP address is configured on an interface in the real world. +An IP address object in NetBox comprises a single host address (either IPv4 or IPv6) and its subnet mask, and represents an IP address as configured on a network interface. IP addresses can be assigned to [device](../dcim/device.md) and [virtual machine](../virtualization/virtualmachine.md) interfaces, as well as to [FHRP groups](./fhrpgroup.md). Further, each device and virtual machine may have one of its interface IPs designated as its primary IP per address family (one for IPv4 and one for IPv6). -Like a prefix, an IP address can optionally be assigned to a VRF (otherwise, it will appear in the "global" table). IP addresses are automatically arranged under parent prefixes within their respective VRFs according to the IP hierarchy. - -Each IP address can also be assigned an operational status and a functional role. Statuses are hard-coded in NetBox and include the following: - -* Active -* Reserved -* Deprecated -* DHCP -* SLAAC (IPv6 Stateless Address Autoconfiguration) - -Roles are used to indicate some special attribute of an IP address; for example, use as a loopback or as the the virtual IP for a VRRP group. (Note that functional roles are conceptual in nature, and thus cannot be customized by the user.) Available roles include: - -* Loopback -* Secondary -* Anycast -* VIP -* VRRP -* HSRP -* GLBP - -An IP address can be assigned to any device or virtual machine interface, and an interface may have multiple IP addresses assigned to it. Further, each device and virtual machine may have one of its interface IPs designated as its primary IP per address family (one for IPv4 and one for IPv6). - -!!! note +!!! tip When primary IPs are set for both IPv4 and IPv6, NetBox will prefer IPv6. This can be changed by setting the `PREFER_IPV4` configuration parameter. ## Network Address Translation (NAT) @@ -32,4 +10,44 @@ An IP address can be assigned to any device or virtual machine interface, and an An IP address can be designated as the network address translation (NAT) inside IP address for exactly one other IP address. This is useful primarily to denote a translation between public and private IP addresses. This relationship is followed in both directions: For example, if 10.0.0.1 is assigned as the inside IP for 192.0.2.1, 192.0.2.1 will be displayed as the outside IP for 10.0.0.1. !!! note - NetBox does not support tracking one-to-many NAT relationships (also called port address translation). This type of policy requires additional logic to model and cannot be fully represented by IP address alone. + NetBox does not currently support tracking application-level NAT relationships (also called _port address translation_ or PAT). This type of policy requires additional logic to model and cannot be fully represented by IP address alone. + +## Fields + +### Address + +The IPv4 or IPv6 address and mask, in CIDR notation (e.g. `192.0.2.0/24`). + +### Status + +The operational status of the IP address. + +!!! tip + Additional statuses may be defined by setting `IPAddress.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Role + +The functional role fulfilled by this IP address. Options include: + +* **Loopback:** Configured on a loopback interface +* **Secondary:** One of multiple IP addresses configured on an interface +* **Anycast:** Employed for anycast services +* **VIP:** A general-purpose virtual IP address +* **VRRP:** A virtual IP address managed with the VRRP protocol +* **HSRP:** A virtual IP address managed with the HSRP protocol +* **GLBP:** A virtual IP address managed with the GLBP protocol +* **CARP:** A virtual IP address managed with the CARP protocol + +!!! tip + Virtual IP addresses should be assigned to [FHRP groups](./fhrpgroup.md) rather than to actual interfaces to accurately model their shared nature. + +### VRF + +The [Virtual Routing and Forwarding](./vrf.md) instance in which this IP address exists. + +!!! note + VRF assignment is optional. IP addresses with no VRF assigned are considered to exist in the "global" table. + +### DNS Name + +A DNS A/AAAA record value associated with this IP address. diff --git a/docs/models/ipam/iprange.md b/docs/models/ipam/iprange.md index 7b0457f27..53abf10b8 100644 --- a/docs/models/ipam/iprange.md +++ b/docs/models/ipam/iprange.md @@ -1,14 +1,30 @@ # IP Ranges -This model represents an arbitrary range of individual IPv4 or IPv6 addresses, inclusive of its starting and ending addresses. For instance, the range 192.0.2.10 to 192.0.2.20 has eleven members. (The total member count is available as the `size` property on an IPRange instance.) Like prefixes and IP addresses, each IP range may optionally be assigned to a VRF and/or tenant. +This model represents an arbitrary range of individual IPv4 or IPv6 addresses, inclusive of its starting and ending addresses. For instance, the range 192.0.2.10 to 192.0.2.20 has eleven members. (The total member count is available as the `size` property on an IPRange instance.) Like [prefixes](./prefix.md) and [IP addresses](./ipaddress.md), each IP range may optionally be assigned to a [VRF](./vrf.md). -IP also ranges share the same functional roles as prefixes and VLANs, although the assignment of a role is optional. Each IP range must be assigned an operational status, which is one of the following: +## Fields -* Active - Provisioned and in use -* Reserved - Designated for future use -* Deprecated - No longer in use +### VRF -The status of a range does _not_ have any impact on its member IP addresses, which may have their statuses modified separately. +The [Virtual Routing and Forwarding](./vrf.md) instance in which this IP range exists. + +!!! note + VRF assignment is optional. IP ranges with no VRF assigned are considered to exist in the "global" table. + +### Start & End Address + +The beginning and ending IP addresses (inclusive) which define the boundaries of the range. Both IP addresses must specify the correct mask. !!! note The maximum supported size of an IP range is 2^32 - 1. + +### Role + +The user-defined functional [role](./role.md) assigned to the IP range. + +### Status + +The IP range's operational status. Note that the status of a range does _not_ have any impact on its member IP addresses, which may have their statuses defined independently. + +!!! tip + Additional statuses may be defined by setting `IPRange.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. diff --git a/docs/models/ipam/l2vpn.md b/docs/models/ipam/l2vpn.md index 214b8aab0..86a2eed9d 100644 --- a/docs/models/ipam/l2vpn.md +++ b/docs/models/ipam/l2vpn.md @@ -1,8 +1,20 @@ # L2VPN -A L2VPN object is NetBox is a representation of a layer 2 bridge technology such as VXLAN, VPLS or EPL. Each L2VPN can be identified by name as well as an optional unique identifier (VNI would be an example). +A L2VPN object is NetBox is a representation of a layer 2 bridge technology such as VXLAN, VPLS, or EPL. Each L2VPN can be identified by name as well as by an optional unique identifier (VNI would be an example). Once created, L2VPNs can be terminated to [interfaces](../dcim/interface.md) and [VLANs](./vlan.md). -Each L2VPN instance must have one of the following type associated with it: +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Type + +The technology employed in forming and operating the L2VPN. Choices include: * VPLS * VPWS @@ -13,9 +25,17 @@ Each L2VPN instance must have one of the following type associated with it: * EP-TREE * EVP-TREE * VXLAN -* VXLAN EVPN +* VXLAN-EVPN * MPLS-EVPN * PBB-EVPN !!! note - Choosing VPWS, EPL, EP-LAN, EP-TREE will result in only being able to add two terminations to a given L2VPN. + Designating the type as VPWS, EPL, EP-LAN, EP-TREE will limit the L2VPN instance to two terminations. + +### Identifier + +An optional unique numeric identifier. + +### Import & Export Targets + +The [route targets](./routetarget.md) associated with this L2VPN to control the import and export of forwarding information. diff --git a/docs/models/ipam/l2vpntermination.md b/docs/models/ipam/l2vpntermination.md index e7c6a6810..c3c27b8d2 100644 --- a/docs/models/ipam/l2vpntermination.md +++ b/docs/models/ipam/l2vpntermination.md @@ -1,15 +1,18 @@ # L2VPN Termination -A L2VPN Termination is the termination point of a L2VPN. Certain types of L2VPNs may only have 2 termination points (point-to-point) while others may have many terminations (multipoint). - -Each termination consists of a L2VPN it is a member of as well as the connected endpoint which can be an interface or a VLAN. - -The following types of L2VPNs are considered point-to-point: +A L2VPN termination is the attachment of an [L2VPN](./l2vpn.md) to an [interface](../dcim/interface.md) or [VLAN](./vlan.md). Note that the L2VPNs of the following types may have only two terminations assigned to them: * VPWS * EPL * EP-LAN * EP-TREE -!!! note - Choosing any of the above types will result in only being able to add 2 terminations to a given L2VPN. +## Fields + +### L2VPN + +The [L2VPN](./l2vpn.md) instance. + +### VLAN or Interface + +The [VLAN](./vlan.md), [device interface](../dcim/interface.md), or [virtual machine interface](../virtualization/virtualmachine.md) attached to the L2VPN. diff --git a/docs/models/ipam/prefix.md b/docs/models/ipam/prefix.md index bd5e9695f..2fb01daf0 100644 --- a/docs/models/ipam/prefix.md +++ b/docs/models/ipam/prefix.md @@ -1,18 +1,43 @@ # Prefixes -A prefix is an IPv4 or IPv6 network and mask expressed in CIDR notation (e.g. 192.0.2.0/24). A prefix entails only the "network portion" of an IP address: All bits in the address not covered by the mask must be zero. (In other words, a prefix cannot be a specific IP address.) +A prefix is an IPv4 or IPv6 network and mask expressed in CIDR notation (e.g. 192.0.2.0/24). A prefix entails only the "network portion" of an IP address: All bits in the address not covered by the mask must be zero. (In other words, a prefix cannot be a specific IP address.) Prefixes are automatically organized by their parent [aggregate](./aggregate.md) and assigned [VRF](./vrf.md). -Prefixes are automatically organized by their parent aggregates. Additionally, each prefix can be assigned to a particular site and virtual routing and forwarding instance (VRF). Each VRF represents a separate IP space or routing table. All prefixes not assigned to a VRF are considered to be in the "global" table. +## Fields -Each prefix can be assigned a status and a role. These terms are often used interchangeably so it's important to recognize the difference between them. The **status** defines a prefix's operational state. Statuses are hard-coded in NetBox and can be one of the following: +### Prefix -* Container - A summary of child prefixes -* Active - Provisioned and in use -* Reserved - Designated for future use -* Deprecated - No longer in use +The IPv4 or IPv6 network this prefix represents. -On the other hand, a prefix's **role** defines its function. Role assignment is optional and roles are fully customizable. For example, you might create roles to differentiate between production and development infrastructure. +### Status -A prefix may also be assigned to a VLAN. This association is helpful for associating address space with layer two domains. A VLAN may have multiple prefixes assigned to it. +The prefix's operational status. Note that the status of a prefix does _not_ have any impact on its member [IP addresses](./ipaddress.md), which may have their statuses defined independently. The "container" status indicates that the prefix exists merely as a container for organizing child prefixes. -The prefix model include an "is pool" flag. If enabled, NetBox will treat this prefix as a range (such as a NAT pool) wherein every IP address is valid and assignable. This logic is used when identifying available IP addresses within a prefix. If this flag is disabled, NetBox will assume that the first and last (broadcast) address within an IPv4 prefix are unusable. +!!! tip + Additional statuses may be defined by setting `Prefix.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### VRF + +The [Virtual Routing and Forwarding](./vrf.md) instance in which this prefix exists. + +!!! note + VRF assignment is optional. Prefixes with no VRF assigned are considered to exist in the "global" table. + +### Role + +The user-defined functional [role](./role.md) assigned to the prefix. + +### Is a Pool + +Designates whether the prefix should be treated as a pool. If selected, the first and last IP addresses within the prefix (normally reserved as the network and broadcast addresses, respectively) will be considered usable. This option is ideal for documenting NAT pools. + +### Mark Utilized + +If selected, this prefix will report 100% utilization regardless of how many child objects have been defined within it. + +### Site + +The [site](../dcim/site.md) to which this prefix is assigned (optional). + +### VLAN + +The [VLAN](./vlan.md) to which this prefix is assigned (optional). This mapping is helpful for associating IP space with layer two domains. A VLAN may have multiple prefixes assigned to it. diff --git a/docs/models/ipam/rir.md b/docs/models/ipam/rir.md index 6904381ac..efa5cf0f5 100644 --- a/docs/models/ipam/rir.md +++ b/docs/models/ipam/rir.md @@ -2,6 +2,18 @@ [Regional Internet registries](https://en.wikipedia.org/wiki/Regional_Internet_registry) are responsible for the allocation of globally-routable address space. The five RIRs are ARIN, RIPE, APNIC, LACNIC, and AFRINIC. However, some address space has been set aside for internal use, such as defined in RFCs 1918 and 6598. NetBox considers these RFCs as a sort of RIR as well; that is, an authority which "owns" certain address space. There also exist lower-tier registries which serve particular geographic areas. -Users can create whatever RIRs they like, but each aggregate must be assigned to one RIR. The RIR model includes a boolean flag which indicates whether the RIR allocates only private IP space. +Users can create whatever RIRs they like, but each [aggregate](./aggregate.md) must be assigned to one RIR. For example, suppose your organization has been allocated 104.131.0.0/16 by ARIN. It also makes use of RFC 1918 addressing internally. You would first create RIRs named "ARIN" and "RFC 1918," then create an aggregate for each of these top-level prefixes, assigning it to its respective RIR. -For example, suppose your organization has been allocated 104.131.0.0/16 by ARIN. It also makes use of RFC 1918 addressing internally. You would first create RIRs named "ARIN" and "RFC 1918," then create an aggregate for each of these top-level prefixes, assigning it to its respective RIR. +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Private + +Designates this RIR as an authority for private/local IP space only (e.g. an RFC). diff --git a/docs/models/ipam/role.md b/docs/models/ipam/role.md index 8623e5282..7685f7d85 100644 --- a/docs/models/ipam/role.md +++ b/docs/models/ipam/role.md @@ -1,3 +1,17 @@ # Prefix/VLAN Roles A role indicates the function of a prefix or VLAN. For example, you might define Data, Voice, and Security roles. Generally, a prefix will be assigned the same functional role as the VLAN to which it is assigned (if any). + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Weight + +A numeric weight employed to influence the ordering of roles. Roles with a lower weight will be listed before those with higher weights. diff --git a/docs/models/ipam/routetarget.md b/docs/models/ipam/routetarget.md index b71e96904..298900f88 100644 --- a/docs/models/ipam/routetarget.md +++ b/docs/models/ipam/routetarget.md @@ -2,4 +2,8 @@ A route target is a particular type of [extended BGP community](https://tools.ietf.org/html/rfc4360#section-4) used to control the redistribution of routes among VRF tables in a network. Route targets can be assigned to individual VRFs in NetBox as import or export targets (or both) to model this exchange in an L3VPN. Each route target must be given a unique name, which should be in a format prescribed by [RFC 4364](https://tools.ietf.org/html/rfc4364#section-4.2), similar to a VR route distinguisher. -Each route target can optionally be assigned to a tenant, and may have tags assigned to it. +## Fields + +### Name + +The route target identifier formatted in accordance with [RFC 4360](https://tools.ietf.org/html/rfc4360). diff --git a/docs/models/ipam/service.md b/docs/models/ipam/service.md index 057544a91..316828b61 100644 --- a/docs/models/ipam/service.md +++ b/docs/models/ipam/service.md @@ -1,5 +1,23 @@ # Services -A service represents a layer four TCP or UDP service available on a device or virtual machine. For example, you might want to document that an HTTP service is running on a device. Each service includes a name, protocol, and port number; for example, "SSH (TCP/22)" or "DNS (UDP/53)." +A service represents a layer seven application available on a device or virtual machine. For example, a service might be created in NetBox to represent an HTTP server running on TCP/8000. Each service may optionally be further bound to one or more specific interfaces assigned to the selected device or virtual machine. -A service may optionally be bound to one or more specific IP addresses belonging to its parent device or VM. (If no IP addresses are bound, the service is assumed to be reachable via any assigned IP address.) +To aid in the efficient creation of services, users may opt to first create a [service template](./servicetemplate.md) from which service definitions can be quickly replicated. + +## Fields + +### Name + +A service or protocol name. + +### Protocol + +The wire protocol on which the service runs. Choices include UDP, TCP, and SCTP. + +### Ports + +One or more numeric ports to which the service is bound. Multiple ports can be expressed using commas and/or hyphens. For example, `80,8001-8003` specifies ports 80, 8001, 8002, and 8003. + +### IP Addresses + +The [IP address(es)](./ipaddress.md) to which this service is bound. If no IP addresses are bound, the service is assumed to be reachable via any assigned IP address. diff --git a/docs/models/ipam/servicetemplate.md b/docs/models/ipam/servicetemplate.md index 7fed40211..28c66b648 100644 --- a/docs/models/ipam/servicetemplate.md +++ b/docs/models/ipam/servicetemplate.md @@ -1,3 +1,17 @@ # Service Templates -Service templates can be used to instantiate services on devices and virtual machines. A template defines a name, protocol, and port number(s), and may optionally include a description. Services can be instantiated from templates and applied to devices and/or virtual machines, and may be associated with specific IP addresses. +Service templates can be used to instantiate [services](./service.md) on [devices](../dcim/device.md) and [virtual machines](../virtualization/virtualmachine.md). + +## Fields + +### Name + +A service or protocol name. + +### Protocol + +The wire protocol on which the service runs. Choices include UDP, TCP, and SCTP. + +### Ports + +One or more numeric ports to which the service is bound. Multiple ports can be expressed using commas and/or hyphens. For example, `80,8001-8003` specifies ports 80, 8001, 8002, and 8003. diff --git a/docs/models/ipam/vlan.md b/docs/models/ipam/vlan.md index c7aa0d05f..2dd5ec2d3 100644 --- a/docs/models/ipam/vlan.md +++ b/docs/models/ipam/vlan.md @@ -1,11 +1,28 @@ # VLANs -A VLAN represents an isolated layer two domain, identified by a name and a numeric ID (1-4094) as defined in [IEEE 802.1Q](https://en.wikipedia.org/wiki/IEEE_802.1Q). VLANs are arranged into VLAN groups to define scope and to enforce uniqueness. +A Virtual LAN (VLAN) represents an isolated layer two domain, identified by a name and a numeric ID (1-4094) as defined in [IEEE 802.1Q](https://en.wikipedia.org/wiki/IEEE_802.1Q). VLANs are arranged into [VLAN groups](./vlangroup.md) to define scope and to enforce uniqueness. -Each VLAN must be assigned one of the following operational statuses: +## Fields -* Active -* Reserved -* Deprecated +### ID -As with prefixes, each VLAN may also be assigned a functional role. Prefixes and VLANs share the same set of customizable roles. +A 12-bit numeric ID for the VLAN, 1-4094 (inclusive). + +### Name + +The configured VLAN name. + +### Status + +The VLAN's operational status. + +!!! tip + Additional statuses may be defined by setting `VLAN.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Role + +The user-defined functional [role](./role.md) assigned to the VLAN. + +### VLAN Group or Site + +The [VLAN group](./vlangroup.md) or [site](../dcim/site.md) to which the VLAN is assigned. diff --git a/docs/models/ipam/vlangroup.md b/docs/models/ipam/vlangroup.md index 2840fafed..a2920fb70 100644 --- a/docs/models/ipam/vlangroup.md +++ b/docs/models/ipam/vlangroup.md @@ -1,7 +1,23 @@ # VLAN Groups -VLAN groups can be used to organize VLANs within NetBox. Each VLAN group can be scoped to a particular region, site group, site, location, rack, cluster group, or cluster. Member VLANs will be available for assignment to devices and/or virtual machines within the specified scope. +VLAN groups can be used to organize [VLANs](./vlan.md) within NetBox. Each VLAN group can be scoped to a particular [region](../dcim/region.md), [site group](../dcim/sitegroup.md), [site](../dcim/sitegroup.md), [location](../dcim/location.md), [rack](../dcim/rack.md), [cluster group](../virtualization/clustergroup.md), or [cluster](../virtualization/cluster.md). Member VLANs will be available for assignment to devices and/or virtual machines within the specified scope. + +Groups can also be used to enforce uniqueness: Each VLAN within a group must have a unique ID and name. VLANs which are not assigned to a group may have overlapping names and IDs (including VLANs which belong to a common site). For example, two VLANs with ID 123 may be created, but they cannot both be assigned to the same group. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Minimum & Maximum VLAN IDs A minimum and maximum child VLAN ID must be set for each group. (These default to 1 and 4094 respectively.) VLANs created within a group must have a VID that falls between these values (inclusive). -Groups can also be used to enforce uniqueness: Each VLAN within a group must have a unique ID and name. VLANs which are not assigned to a group may have overlapping names and IDs (including VLANs which belong to a common site). For example, you can create two VLANs with ID 123, but they cannot both be assigned to the same group. +### Scope + +The domain covered by a VLAN group, defined as one of the supported object types. This conveys the context in which a VLAN group applies. diff --git a/docs/models/ipam/vrf.md b/docs/models/ipam/vrf.md index 392141fdd..e45a81daf 100644 --- a/docs/models/ipam/vrf.md +++ b/docs/models/ipam/vrf.md @@ -1,14 +1,26 @@ # Virtual Routing and Forwarding (VRF) -A VRF object in NetBox represents a virtual routing and forwarding (VRF) domain. Each VRF is essentially a separate routing table. VRFs are commonly used to isolate customers or organizations from one another within a network, or to route overlapping address space (e.g. multiple instances of the 10.0.0.0/8 space). Each VRF may be assigned to a specific tenant to aid in organizing the available IP space by customer or internal user. +A VRF object in NetBox represents a Virtual Routing and Forwarding (VRF) domain. Each VRF is essentially an independent routing table. VRFs are commonly used to isolate customers or organizations from one another within a network, or to route overlapping address space (e.g. multiple instances of the 10.0.0.0/8 space). Each VRF may be assigned to a specific tenant to aid in organizing the available IP space by customer or internal user. -Each VRF is assigned a unique name and an optional route distinguisher (RD). The RD is expected to take one of the forms prescribed in [RFC 4364](https://tools.ietf.org/html/rfc4364#section-4.2), however its formatting is not strictly enforced. +Each [prefix](./prefix.md), [IP range](./iprange.md), and [IP address](./ipaddress.md) may be assigned to one (and only one) VRF. If you have a prefix or IP address which exists in multiple VRFs, you will need to create a separate instance of it in NetBox for each VRF. Any such object not assigned to a VRF is said to belong to the "global" table. -Each prefix and IP address may be assigned to one (and only one) VRF. If you have a prefix or IP address which exists in multiple VRFs, you will need to create a separate instance of it in NetBox for each VRF. Any prefix or IP address not assigned to a VRF is said to belong to the "global" table. +## Fields -By default, NetBox will allow duplicate prefixes to be assigned to a VRF. This behavior can be toggled by setting the "enforce unique" flag on the VRF model. +### Name + +The configured or administrative name for the VRF instance. + +### Route Distinguisher + +A route distinguisher is used to map routes to VRFs within a device's routing table e.g. for MPLS/VPN. The assignment of a route distinguisher is optional. If defined, the RD is expected to take one of the forms prescribed in [RFC 4364](https://tools.ietf.org/html/rfc4364#section-4.2), however its formatting is not strictly enforced. + +### Enforce Unique Space + +By default, NetBox will permit duplicate prefixes to be assigned to a VRF. This behavior can be toggled by setting the "enforce unique" flag on the VRF model. !!! note Enforcement of unique IP space can be toggled for global table (non-VRF prefixes) using the `ENFORCE_GLOBAL_UNIQUE` configuration setting. -Each VRF may have one or more import and/or export route targets applied to it. Route targets are used to control the exchange of routes (prefixes) among VRFs in L3VPNs. +### Import & Export Targets + +Each VRF may have one or more import and/or export [route targets](./routetarget.md) applied to it. Route targets are used to control the exchange of routes (prefixes) among VRFs in L3VPNs. From 0ba45caabf9ad26f51d19687ee6108f80eef5d1a Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 16 Aug 2022 15:57:29 -0400 Subject: [PATCH 27/28] Update virtualization models documentation --- docs/models/dcim/device.md | 7 +++ docs/models/virtualization/cluster.md | 27 +++++++++- docs/models/virtualization/clustergroup.md | 12 ++++- docs/models/virtualization/clustertype.md | 12 ++++- docs/models/virtualization/virtualmachine.md | 57 ++++++++++++++++---- docs/models/virtualization/vminterface.md | 54 ++++++++++++++++++- 6 files changed, 154 insertions(+), 15 deletions(-) diff --git a/docs/models/dcim/device.md b/docs/models/dcim/device.md index ddf1bfb09..33d07e07e 100644 --- a/docs/models/dcim/device.md +++ b/docs/models/dcim/device.md @@ -72,6 +72,13 @@ The device's operational status. A device may be associated with a particular [platform](./platform.md) to indicate its operating system. Note that only platforms assigned to the associated manufacturer (or to no manufacturer) will be available for selection. +### Primary IPv4 & IPv6 Addresses + +Each device may designate one primary IPv4 address and/or one primary IPv6 address for management purposes. + +!!! tip + NetBox will prefer IPv6 addresses over IPv4 addresses by default. This can be changed by setting the `PREFER_IPV4` configuration parameter. + ### Cluster If this device will serve as a host for a virtualization [cluster](../virtualization/cluster.md), it can be assigned here. (Host devices can also be assigned by editing the cluster.) diff --git a/docs/models/virtualization/cluster.md b/docs/models/virtualization/cluster.md index 3e3516cd6..50b5dbd1d 100644 --- a/docs/models/virtualization/cluster.md +++ b/docs/models/virtualization/cluster.md @@ -1,5 +1,28 @@ # Clusters -A cluster is a logical grouping of physical resources within which virtual machines run. A cluster must be assigned a type (technological classification) and operational status, and may optionally be assigned to a cluster group, site, and/or tenant. Each cluster must have a unique name within its assigned group and/or site, if any. +A cluster is a logical grouping of physical resources within which [virtual machines](./virtualmachine.md) run. Physical [devices](../dcim/device.md) may be associated with clusters as hosts. This allows users to track on which host(s) a particular virtual machine may reside. -Physical devices may be associated with clusters as hosts. This allows users to track on which host(s) a particular virtual machine may reside. However, NetBox does not support pinning a specific VM within a cluster to a particular host device. +## Fields + +### Name + +A human-friendly name for the cluster. Must be unique within the assigned group and site. + +### Type + +The [cluster type](./clustertype.md) assigned for this cluster. + +### Group + +The [cluster group](./clustergroup.md) to which this cluster belongs. + +### Status + +The cluster's operational status. + +!!! tip + Additional statuses may be defined by setting `Cluster.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Site + +The [site](../dcim/site.md) with which the cluster is associated. diff --git a/docs/models/virtualization/clustergroup.md b/docs/models/virtualization/clustergroup.md index 6dd0f9688..bae177792 100644 --- a/docs/models/virtualization/clustergroup.md +++ b/docs/models/virtualization/clustergroup.md @@ -1,3 +1,13 @@ # Cluster Groups -Cluster groups may be created for the purpose of organizing clusters. The arrangement of clusters into groups is optional. +Cluster groups may be created for the purpose of organizing [clusters](./cluster.md). The arrangement of clusters into groups is optional. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/virtualization/clustertype.md b/docs/models/virtualization/clustertype.md index cee557df3..51eed5ec4 100644 --- a/docs/models/virtualization/clustertype.md +++ b/docs/models/virtualization/clustertype.md @@ -1,3 +1,13 @@ # Cluster Types -A cluster type represents a technology or mechanism by which a cluster is formed. For example, you might create a cluster type named "VMware vSphere" for a locally hosted cluster or "DigitalOcean NYC3" for one hosted by a cloud provider. +A cluster type represents a technology or mechanism by which a [cluster](./cluster.md) is formed. For example, you might create a cluster type named "VMware vSphere" for a locally hosted cluster or "DigitalOcean NYC3" for one hosted by a cloud provider. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/virtualization/virtualmachine.md b/docs/models/virtualization/virtualmachine.md index 4ddffb99a..769d49154 100644 --- a/docs/models/virtualization/virtualmachine.md +++ b/docs/models/virtualization/virtualmachine.md @@ -1,16 +1,53 @@ # Virtual Machines -A virtual machine represents a virtual compute instance hosted within a cluster. Each VM must be assigned to a site and/or cluster, and may optionally be assigned to a particular host device within a cluster. +A virtual machine (VM) represents a virtual compute instance hosted within a [cluster](./cluster.md). Each VM must be assigned to a [site](../dcim/site.md) and/or cluster, and may optionally be assigned to a particular host [device](../dcim/device.md) within a cluster. -Like devices, each VM can be assigned a platform and/or functional role, and must have one of the following operational statuses assigned to it: +Virtual machines may have virtual [interfaces](./vminterface.md) assigned to them, but do not support any physical component. When a VM has one or more interfaces with IP addresses assigned, a primary IP for the device can be designated, for both IPv4 and IPv6. -* Active -* Offline -* Planned -* Staged -* Failed -* Decommissioning +## Fields -Additional fields are available for annotating the vCPU count, memory (GB), and disk (GB) allocated to each VM. A VM may be allocated a partial vCPU count (e.g. 1.5 vCPU). +### Name -Each VM may optionally be assigned to a tenant. Virtual machines may have virtual interfaces assigned to them, but do not support any physical component. +The virtual machine's configured name. Must be unique to the assigned cluster and tenant. + +### Role + +The functional [role](../dcim/devicerole.md) assigned to the VM. + +### Status + +The VM's operational status. + +!!! tip + Additional statuses may be defined by setting `VirtualMachine.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Site & Cluster + +The [site](../dcim/site.md) and/or [cluster](./cluster.md) to which the VM is assigned. + +### Device + +The physical host [device](../dcim/device.md) within the assigned site/cluster on which this VM resides. + +### Platform + +A VM may be associated with a particular [platform](../dcim/platform.md) to indicate its operating system. + +### Primary IPv4 & IPv6 Addresses + +Each VM may designate one primary IPv4 address and/or one primary IPv6 address for management purposes. + +!!! tip + NetBox will prefer IPv6 addresses over IPv4 addresses by default. This can be changed by setting the `PREFER_IPV4` configuration parameter. + +### vCPUs + +The number of virtual CPUs provisioned. A VM may be allocated a partial vCPU count (e.g. 1.5 vCPU). + +### Memory + +The amount of running memory provisioned, in megabytes. + +### Disk + +The amount of disk storage provisioned, in gigabytes. diff --git a/docs/models/virtualization/vminterface.md b/docs/models/virtualization/vminterface.md index 7f1a5082d..264fb95ba 100644 --- a/docs/models/virtualization/vminterface.md +++ b/docs/models/virtualization/vminterface.md @@ -1,3 +1,55 @@ ## Interfaces -Virtual machine interfaces behave similarly to device interfaces, and can be assigned to VRFs, and may have IP addresses, VLANs, and services attached to them. However, given their virtual nature, they lack properties pertaining to physical attributes. For example, VM interfaces do not have a physical type and cannot have cables attached to them. +[Virtual machine](./virtualmachine.md) interfaces behave similarly to device [interfaces](../dcim/interface.md): They can be assigned to VRFs, may have IP addresses, VLANs, and services attached to them, and so on. However, given their virtual nature, they lack properties pertaining to physical attributes. For example, VM interfaces do not have a physical type and cannot have cables attached to them. + +## Fields + +### Virtual Machine + +The [virtual machine](./virtualmachine.md) to which this interface is assigned. + +### Name + +The interface's name. Must be unique to the assigned VM. + +### Parent Interface + +Identifies the parent interface of a subinterface (e.g. used to employ encapsulation). + +### Bridged Interface + +An interface on the same VM with which this interface is bridged. + +### Enabled + +If not selected, this interface will be treated as disabled/inoperative. + +### MAC Address + +The 48-bit MAC address (for Ethernet interfaces). + +### MTU + +The interface's configured maximum transmissible unit (MTU). + +### 802.1Q Mode + +For switched Ethernet interfaces, this identifies the 802.1Q encapsulation strategy in effect. Options include: + +* **Access:** All traffic is assigned to a single VLAN, with no tagging. +* **Tagged:** One untagged "native" VLAN is allowed, as well as any number of tagged VLANs. +* **Tagged (all):** Implies that all VLANs are carried by the interface. One untagged VLAN may be designated. + +This field must be left blank for routed interfaces which do employ 802.1Q encapsulation. + +### Untagged VLAN + +The "native" (untagged) VLAN for the interface. Valid only when one of the above 802.1Q mode is selected. + +### Tagged VLANs + +The tagged VLANs which are configured to be carried by this interface. Valid only for the "tagged" 802.1Q mode above. + +### VRF + +The [virtual routing and forwarding](../ipam/vrf.md) instance to which this interface is assigned. From e6c69127e49c92040d17a1948de011bd20d051b0 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 16 Aug 2022 16:06:48 -0400 Subject: [PATCH 28/28] Add model documentation for JournalEntry --- docs/models/extras/journalentry.md | 16 ++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 17 insertions(+) create mode 100644 docs/models/extras/journalentry.md diff --git a/docs/models/extras/journalentry.md b/docs/models/extras/journalentry.md new file mode 100644 index 000000000..7e9bc986d --- /dev/null +++ b/docs/models/extras/journalentry.md @@ -0,0 +1,16 @@ +# Journal Entries + +Most objects in NetBox support journaling. This is the ability of users to record chronological notes indicating changes to or work performed on resources in NetBox. For example, a data center technician might add a journal entry for a device when swapping out a failed power supply. + +## Fields + +### Kind + +A general classification for the entry type (info, success, warning, or danger.) + +!!! tip + Additional kinds may be defined by setting `JournalEntry.kind` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Comments + +The body of the journal entry. [Markdown](../../reference/markdown.md) rendering is supported. diff --git a/mkdocs.yml b/mkdocs.yml index be9c31651..eef000481 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -196,6 +196,7 @@ nav: - CustomLink: 'models/extras/customlink.md' - ExportTemplate: 'models/extras/exporttemplate.md' - ImageAttachment: 'models/extras/imageattachment.md' + - JournalEntry: 'models/extras/journalentry.md' - Tag: 'models/extras/tag.md' - Webhook: 'models/extras/webhook.md' - IPAM: