Resolves performance issue where prefix deletion with 2000+ children
took 5-10 minutes due to sequential scans in hierarchy depth/children
calculations. Adding PostgreSQL GiST index with inet_ops enables efficient
network containment operators (>>, <<, <<=) in annotate_hierarchy() queries.
Performance impact:
- 30-60x speedup: 5-10 minutes → 10 seconds for large prefix deletions
- Real-world validation: 4s migration time on 1.24M prefix dataset
- Storage cost: 47MB index (11% of table storage, 38 bytes per prefix)
Works in conjunction with existing B-tree indexes on vrf_id for optimal
query performance. Benefits all network containment operations including
hierarchy navigation, aggregate views, and available IP/prefix calculations.
* Closes#20003: Introduce mechanism to register callbacks for webhook context
* Swap ContentType with ObjectType
* Add plugin dev documentation for webhook callbacks
* Fix tests
* Add note about namespacing webhook data
* Fixes#19986: Fix plugin list view button URLs
Plugin list view action buttons (Add, Import, Export) were generating 404
errors because ObjectAction.get_url() was manually constructing viewnames
without the required "plugins:" namespace prefix for plugin models.
Replace manual viewname construction with NetBox's get_viewname() utility
function, which properly handles plugin detection and namespace prefixing
for both core and plugin models.
* Ensure expected URL patterns are registered, ensures tests pass
- Extract script list content into reusable partial template
- Add object-list CSS class for proper embedded table styling
- Hide module headers and management actions in widget context
- Use compact buttons with icon-only labels for widgets
- Add test coverage for embedded parameter handling
The embedded version now renders cleanly in dashboard widgets while
preserving full functionality in the main script list page.
* Fix MAC address pagination duplicates by adding 'pk' to model ordering
Add 'pk' to MACAddress model ordering to ensure deterministic results
when multiple MAC addresses have the same value. This prevents the same
MAC address from appearing on multiple pages during pagination.
The issue occurred because Django's default ordering by 'mac_address'
alone is non-deterministic when multiple records share the same MAC
address value, causing inconsistent pagination results when the same
MAC address is assigned to multiple interfaces on a device.
Added regression test that verifies MAC addresses with identical values
are properly ordered by their primary key, ensuring consistent pagination
behavior across the application.
Fixes netbox-community#19917
* Remove test
* Resolve migration conflict
---------
Co-authored-by: Jad Seifeddine <jseifeddine@macquarietelecom.com>
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
Replace direct string concatenation with URLSearchParams to properly
encode user input in export link URLs, preventing injection of malicious
parameters or scripts through the search functionality.
Resolves CodeQL Alert #63 (js/xss-through-dom)
* Closes#19977: Denormalize site, location, and rack for device components
* Set blank=True on denormalized ForeignKeys
* Populate denormalized field in test data
* Ignore private fields when constructing test GraphQL requests
* Closes#19968: Use multiple selection lists for the assignment of object types when editing a permission
* Remove errant logging statements
* Defer compilation of choices for object_types
* Fix test data
* Convert ObjectType to a concrete child model of ContentType
* Add public flag to ObjectType
* Catch post_migrate signal to update ObjectTypes
* Reference ObjectType records instead of registry for feature support
* Automatically create ObjectTypes
* Introduce has_feature() utility function
* ObjectTypeManager should not inherit from ContentTypeManager
* Misc cleanup
* Don't populate ObjectTypes during migration
* Don't automatically create ObjectTypes when a ContentType is created
* Fix test
* Extend has_feature() to accept a model or OT/CT
* Misc cleanup
* Deprecate get_for_id() on ObjectTypeManager
* Rename contenttypes.py to object_types.py
* Add index to features ArrayField
* Keep FK & M2M fields pointing to ContentType
* Add get_for_models() to ObjectTypeManager
* Add tests for manager methods & utility functions
* Fix migrations for M2M relations to ObjectType
* model_is_public() should return False for non-core & non-plugin models
* Order ObjectType by app_label & model name
* Resolve migrations conflict
* Fixes#18900: introduce/raise QuerySetNotOrdered exception
Defines a new exception, `QuerySetNotOrdered`, and raises it in
`OptionalLimitOffsetPagination.paginate_queryset` in the right
conditions:
- the iterable to be paginated is a QuerySet isinstance
- the `queryset.ordered` flag is not truthy
* Don't try to reapply ordering if ordering is already present
* Add ordering for failing tagged-objects list API endpoint
I chose to implement this here for TaggedItemViewSet, rather than on the
model, because any meaningful ordering is going to be done on the
related Tag instance and I didn't want to introduce potential, not well
understood side-effects by applying a model-wide ordering via a related
model field.
* Add default Token ordering behavior
* Adds basic tests for raising QuerySetNotOrdered
* Note why ordering is not applied in TaggedItem.Meta
* Add message field to ObjectChange model
* Set max length on changelog message
* Enable changelog messages for single object operations
* Fix tests
* Add changelog message support for bulk edit & bulk delete
* Cosmetic improvements to form fields
* Fix bulk operation templates
* Add message support for bulk import/update
* Add REST API support for changelog messages (WIP)
* Fix changelog_message assignment
* Enable changelog message support for bulk deletions
* Add documentation
* Fix changelog message support for VirtualChassis
* Add ChangeLoggingMixin to necesssary model forms
* Introduce get_random_string() utility function for tests
* Incorporate changelog messages for object view tests
* Incorporate changelog messages for object bulk view tests
* Add missing mixins for changelog message support
* Tweak test to generate expected number of change records
* Finish adding tests for changelog message functionality
* Misc cleanup
* Fixes#19956: Prevent duplicate deletion records from cascading deletions
* Tweak bulk deletion test to work around cascading deletions issue
* Correct API URL
* feat(dcim): Add site fields to Cable bulk import form
Introduces `side_a_site` and `side_b_site` fields for the Cable bulk
import form. Limits device choices on both sides to the selected site
for improved input validation and consistency.
* feat(dcim): Enhance test data setup with multiple sites
Refactors tests to create multiple sites and assign devices accordingly.
Updates CSV data to include `side_a_site` and `side_b_site` fields for
scenarios involving multiple sites. This improves test coverage and
alignment with real-world use cases.
* docs(dcim): Update comments explaining indent for CSV import
Improved the inline comments to clarify the rationale behind allowing
devices with duplicate names on different sites during CSV bulk import.
The select list of 'Images and Label', 'Images Only', and 'Label Only'
was broken during recent work while implementing #19823.
This fixes the issue by placing the `rack_elevation` class attribute on
the <div> element that contains the SVG after being loaded by HTMX. In
addition, we needed to slightly modify the selectors in the frontend
code that looked for the elements within the SVG to hide and/or show.
Previously, it was looking inside of a contentDocument embedded in an
<object> element. The simplified version just looks inside of the
SVG containing div.
* Show human-friendly values for file size
* Introduce optional dedicated columns for name & filename
* Add combined dimensions column
* Restore image preview on hover
* Remove object_type from default columns list
* Parent column is not orderable
* Filter/search image attachments by filename
* Correct table column name
* Closes: #18588: Relabel Service model to Application Service
Updates the `verbose_name` of the `Service` and `ServiceTemplate` models to "Application Service" and
"Application Service Template" respectively. This serves as the foundational change for relabeling
the model throughout the user interface to reduce ambiguity.
To preserve backward compatibility for the REST and GraphQL APIs, the test suites have been updated
to assert the stability of the original field and parameter names. This includes:
* Using `filter_name_map` in the filterset test case to ensure API query parameters remain
`service` and `service_id`.
* Employing the GraphQL test suite's aliasing mechanism to ensure the public schema remains
unchanged despite the underlying `verbose_name` modification.
Subsequent commits will address UI-specific labels in navigation, tables, forms, and templates.
* Rename to Application Services/Application Service Templates in nav menu
* Rename ~service to ~'Application Service' in templates
This was done for both the Service model and Service Template model
appearances in templates where the word was hardcoded.
* Change ~service to ~'application service' hardcoded strings in Python files
* Update ~service to ~'application service' in docs
* Add background_job toggle to BulkEditForm
* Account for bug fix in v4.3.4
* Enable background jobs for bulk edit & bulk delete
* Move background_job field to a mixin
* Cosmetic improvements
* Misc cleanup
* Fix BackgroundJobMixin
Replaced manual rendering of custom fields in the filter tab with the
`render_custom_fields` template tag. This change ensures that custom fields are
properly grouped, addressing the issue where they were previously displayed
without their associated groups.
* Fixes#19800: ModuleType import supports associating ModuleTypeProfile
* Fixes up ModuleTypeTestCase to include bulk import testing
Also includes an additional regression assertion.
* Address PR feedback
I ultimately left the extra asserts in for test_bulk_import_objects_with_permissionsince
since the parent test is currently only testing against number of
objects successfully imported. Will file a follow up FR to improve that
test.
* Support menu items that are callables
* Fix quote on add button
* Clarify docstring to differentiate link and url
* Back out support for callables but keep alternate prerendered url param
* Make url a property on MenuItem/PluginMenuItem etc, overridable via a setter
* Use reverse_lazy instead of reverse
* Use reverse_lazy instead of reverse
* Initial work on #19589
* Add tooling for handling background requests
* UI notification should link to enqueued job
* Use an informative name for the job
* Disable background jobs for file uploads
* Closes#19231: Add bulk renaming support for all models
* Introduce a template filter for getattr()
* Extend BulkRenameView to support arbitrary field names
* Address bulk renaming support for remaining models
* Bulk rename URL resolution should fail silently
* Update documentation
* Fix bulk button rendering for HTMX requests
* Initial work on #19735
* Work in progress
* Remove ClusterRemoveDevicesView (anti-pattern)
* Misc cleanup
* Fix has_bulk_actions
* Fix has_bulk_actions for ObjectChildrenView
* Restore clone button
* Misc cleanup
* Clean up custom bulk actions
* Rename individual object actions
* Collapse into a single template tag
* Fix support for legacy action dicts
* Rename bulk attr to multi
* clone_button tag should fail silently if view name is invalid
* Clean up action buttons
* Fix export button label
* Replace clone_button with an ObjectAction
* Create object actions for adding device/VM components
* Move core_sync.html to core app
* Remove extra_bulk_buttons from template doc
- Expands the logic in ServiceImportForm.clean() to handle properly
validation of FHRPGroup assignments and maintain the existing
[VM]Interface validation checks.
- Includes an extension to ServiceTestCase.csv_data to act as a
regression test for this behavior.
* 19644 set atomic transactions to appropriate database
* 19644 set atomic transactions for Job Script run
* 19644 set atomic transactions to appropriate database
* 19644 set atomic transactions to appropriate database
* 19644 fix review comments
* 19644 fix review comments
* Add condition to ScriptResultView.get function to generate a download
file of job output if job is completed
* Update template script_result.html adding a download button to trigger
output download in ScriptResultView.get
* Simplify conditional logic; tweak timestamp format
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
The collector we use to notify users about dependent object that will be
deleted does handle GFKs. However, a GenericRelation must be set up on
the other end.
Ensures the `queryset.none()` method is called properly with
parentheses. This fixes a potential issue where the method would not
execute as intended, improving the stability and correctness of the
filter logic.
Fixes the reference from `interface_a` to `interface_b` in the
validation error message for WirelessLink. Ensures the correct field is
indicated during validation errors.
* Update values to ensure consistency when referencing values see\t
* Update required-parameters.md For Updated Django Link
* Update required-parameters.md to fix Django link
* Update error-reporting.md Remove Number Formatting
* Update docs/configuration/error-reporting.md
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* feat(project): Add project metadata to pyproject.toml
Introduces project metadata, including name, version, authors, and
description, to `pyproject.toml` for enhanced package definition.
Also includes URLs for source code, documentation, and issue tracking.
* docs(release): Add checklist item for Python versions in pyproject.toml
Include step to update minimum and supported Python versions
in the project metadata file as part of the release process.
* docs(release): Update checklist to include pyproject.toml versioning
Add a step to update the version in `pyproject.toml` alongside
`release.yaml`.
* feat(project): Update pyproject.toml for best practices
Refreshes metadata to resolve deprecations and follow packaging best
practices. Updates include description, license, Python versions,
classifiers, maintainers, and repository URLs for improved compliance.
* fix(project): Update repository URL key in pyproject.toml
Replaces the 'Repository' key with 'Source' in accordance with updated
metadata conventions. This ensures compliance with modern best
practices for project metadata.
* fix(project): Specify Python 3 :: Only in classifiers
Updates the Python version classifier in `pyproject.toml` to indicate
support exclusively for Python 3. This change ensures clarity in the
supported Python versions for the project metadata.
* Fixes#19487: make CircuitTermination.termination GFK not orderable
* Add test to ensure no more broken sorting for CircuitTerminationTable
* Fix CircuitTerminationTable.site_group accessor
* Make TunnelTerminationTable.termination GFK field non-orderable
Provides instructions for removing stale Content Types and related
Permissions after uninstalling a plugin. Includes steps for identifying
and safely deleting stale entries to prevent issues in the permissions
management UI.
The ability to render nested templates was accidentally removed with the
implementation of #17653, which normalized the behavior of various Jinja2
template rendering actions.
This fix restores that behavior while retaining the normalized behavior.
This fix also includes regression tests to ensure this behavior is not
removed accidentally again in the future.
* Fixes#19415: Increased Circuit/WirelessLink absolute distance upper limit
Also adds form validation that provides a useful message to the user
rather than a 500 error with potentially little information.
* Include forgotten migration files
* Remove unnecessary comments
* Remove more unnecessary comments
* Addresses PR feedback
* Gah, remove django migration header comment
* Clean up new has_field_errors mechanism, fix issue with ObjectAttribute
* Address PR feedback, revert changes to render_fieldset template tag
Extend `InterfaceSpeedChoices` to include 2.5 Gbps and 5 Gbps values.
This improves support for modern interface speeds and enhances API data
validation.
Introduces a search index for the Tag model to enable global search for
Tags. Includes fields for name, slug, and description with corresponding
weight values. Display attributes are limited to the description field.
Fixes#17073
Hat tip to @pheus. Thanks!
I did end up leaving the filter function arguments as the Sass
processor complains when you try calling a filter function without
an argument. :/
* On delete signal handling, manually save the related object in a ManyToOneRel to trigger a change record
* Only set remote field to None if null=True on the relation
Refactors the 'type' column to use ColoredLabelColumn for improved
visual distinction, aligning it with the rack roles display.
Removes the now redundant 'linkify' attribute from the column
definition.
* feat(dcim): Add VLAN Translation Policy to Filter Form
Introduces support for VLAN Translation Policies in the Interface
Filter Form.
* feat(virtualization): Add VLAN Translation Policy to Filter Form
Introduces support for VLAN Translation Policies in the Interface
Filter Form.
* feat(dcim): Add VLAN mode filter to CommonInterface
Introduces a new FilterSet for VLAN mode in CommonInterfaceFilterSet.
This allows filtering interfaces based on their VLAN mode using defined
choices.
* feat(dcim): Add VLAN mode filter to Interface FilterForm
Add a field to InterfaceFilterSet to filter interfaces by 802.1Q VLAN
mode.
* feat(virtualization): Add VLAN mode filter to VMInterface
Add a field to VMInterfaceFilterSet to filter interfaces by 802.1Q VLAN
mode.
* fix(dcim): Correct mode filter parameter type in tests
Updates the `mode` filter parameter to accept a list instead of a single
value in `test_filtersets.py`. Ensures proper count assertion for
accurate test behavior.
* feat(virtualization): Add tests for VLAN mode filtering
Introduces tests to validate filtering by `mode` for VMInterface.
Ensures correct filtering for 802.1Q VLAN mode.
* refactor(virtualization): Reorganize FieldSets in FilterSets
Splits the 'Attributes' FieldSet into two distinct FieldSets for better
clarity: 'Attributes' and 'Addressing'. This improves form organization
and makes it more intuitive for users.
* feat(dcim): Add filter by location slug for Device
Introduces a TreeNodeMultipleChoiceFilter for filtering locations by
slug. Enhances filtering flexibility in the Device model by supporting
both ID and slug lookups.
Fixes#19056
* feat(dcim): Add Device filtering by location slug in tests
Extend test cases to include filtering by location slug. Ensures the
FilterSet works correctly with slug-based queries for locations.
Fixes#19056
* feat(ipam): Add VLAN group filters to IPAM FilterSet
Introduces filters for VLAN groups using both ID and slug fields.
* feat(ipam): Add VLAN group filter in IPAM FilterForm
Introduces a `vlan_group_id` filter to IPAM forms for filtering based on
VLAN groups.
* feat(ipam): Add VLAN group filtering to tests
Introduces tests for VLAN group filtering in FilterSets. This ensures
correct validation and behavior when filtering by VLAN group.
* Add SavedTableConfig
* Update table configuration logic to support TableConfigs
* Update table config link when updating table
* Correct docstring
* Misc cleanup
* Use multi-select widgets for column selection
* Return null config params for tables with no model
* Fix auto-selection of selected columns
* Update migration
* Clean up template
* Enforce enabled/shared flags
* Search/filter by table name
* Misc cleanup
* Fix population of selected columns
* Ordering field should not be required
* Enable cloning for TableConfig
* Misc cleanup
* Add model documentation for TableConfig
* Drop slug field from TableConfig
* Improve TableConfig validation
* Remove add button from TableConfig list view
* Fix ordering validation to account for leading hyphens
* 19073 allow plugins to be marked as hidden or disabled in plugins table
* 19073 allow plugins to be marked as hidden or disabled in plugins table
* 19073 allow plugins to be marked as hidden or disabled in plugins table
* 19073 review changes
* Rename 'unlinked' to 'static' & update docs
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
Add steps to update the dependency requirements matrix for each minor
release in the release checklist. Clarify how to document changes for
system requirements and linked installation guides.
Fixes#18733
* fix(forms): Call super().clean() in clean methods
Adds a call to super().clean() in the clean methods of object creation
forms. This ensures base class validation logic is executed properly
before custom logic is applied.
Fixes#19041
* test(forms): Add tests for front port form validation
Introduces unit tests for validating FrontPortCreateForm behavior.
Tests include scenarios for matching and mismatched name-label pairs
to ensure proper form validation logic.
Fixes#19041
* Omit errant print statement
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* Move Module & ModuleType models to a separate file
* Add ModuleTypeProfile & related fields
* Initial work on JSON schema validation
* Add attributes property on ModuleType
* Introduce MultipleOfValidator
* Introduce JSONSchemaProperty
* Enable dynamic form field rendering
* Misc cleanup
* Fix migration conflict
* Ensure deterministic ordering of attriubte fields
* Support choices & default values
* Include module type attributes on module view
* Enable modifying individual attributes via REST API
* Enable filtering by attribute values
* Add documentation & tests
* Schema should be optional
* Include attributes column for profiles
* Profile is nullable
* Include some initial profiles to be installed via migration
* Fix migrations conflict
* Fix filterset test
* Misc cleanup
* Fixes#19023: get_field_value() should respect null values in bound forms (#19024)
* Skip filters which do not specify a JSON-serializable value
* Fix handling of array item types
* Fix initial data in schema field during bulk edit
* Implement sanity checking for JSON schema definitions
* Fall back to filtering by string value
Adds a dependency matrix to the upgrade guide, detailing supported
Python, PostgreSQL, and Redis versions for each NetBox release. This
helps users verify compatibility before upgrading.
Fixes#18733
Made DeviceRoles hierarchical, had to also change the filtersets for Device, ConfigContext and VirtualMachine to use the TreeNodeMultipleChoiceFilter.
Note: The model was changed to use NestedGroupModel, a side-effect of this is it also adds comments field, but I thought that was better then doing a one-off just for DeviceRole and having to define the fields, validators, etc.. - keeps everything DRY / consistent.
* 18981 Make Device Roles Hierarchical
* 18981 forms, serializer
* 18981 fix tests
* 18981 fix tests
* 18981 fix tests
* 18981 fix tests
* 18981 fix tests
* 18981 fix migration merge
* 18981 fix tests
* 18981 fix filtersets
* 18981 fix tests
* 18981 comments
* 18981 review changes
* Employ native PostgreSQL functions for updating object JSON data when adding/removing custom fields
* Optimize rename_object_data()
* remove_stale_data() should validate model class
* Add fhrpgroup to IPAddressImportForm
* Change fhrpgroup accessor to name
* rename fhrpgroup to fhrp_group
* Add fhrp_group to IPAddressTestCase csv_data
* Fixes#17443: Adds ExportTemplate.file_name field
* Addresses PR feedback
- Adds `file_name` to `ExportTemplateBulkEditForm.nullable_fields`
- Shortens max length of `ExportTemplate.file_name` to 200 chars
- Adds tests for `ExportTemplateFilterSet.file_extension`
* Fixes migration conflict caused by fix for #17841
Closes: #15842
Branched from #18145 by @tobiasge
Provides a new LOGIN_FORM_HIDDEN setting which allows the administrator to hide the local login form, intended only to be used when SSO is used exclusively for authentication. Note that this means local login will be impossible in the event of SSO provider issues, and can be remedied only through a change to the application config and a restart of the service.
* #15842 - Hide login form
This doesn't implement the full solution proposed in #15842 but enables
administrators to hide the login form when users should only login with a SSO
provider. To prevent a complete lockout when the SSO provider is having
issues the GET parameter `skipsso` can be added to the login URL to show
the form regardless.
* Remove skipsso backdoor
* Add warning
---------
Co-authored-by: Tobias Genannt <tobias.genannt@qbeyond.de>
- [x] 1. Add the field to the model class
- [x] 2. Generate and run database migrations
- [NA] 3. Add validation logic to clean()
- [NA] 4. Update relevant querysets
- [x] 5. Update API serializer
- [x] 6. Add fields to forms
- [x] dcim.forms.model_forms.LocationForm, create/edit (e.g. model_forms.py)
- [x] dcim.forms.buld_edit.LocationBulkEditForm, bulk edit
- [x] dcim.dorms.bulk_import.LocationImportForm, CSV import
- [x] filter (UI and API)
- [NA] UI
- Note: could not find any comments related things in filtersets
- [x] API
- [x] 7. Extend object filter set
- [x] 8. Add column to object table
- [x] 9. Update the SearchIndex
- [x] 10. Update the UI templates
- [x] 11. Create/extend test cases
- [NA] models
- [x] views
- [NA] forms
- [x] filtersets
- [x] api
- [NA] 12. Update the model's documentation
* Fixes#18845: restores sort behavior for DeviceTable.name column
* Remove accessor/order_by and modify DEVICE_LINK template
Thanks to @alehaa for the suggestion.
This also includes an additional `.select_related()` operation on
`DeviceListView.queryset` to avoid extra queries. Thanks to
@renatoalmeidaoliveira and @jeremystretch for pointing out the need for
this.
* Fixes: #18568 Update mkdocstrings and adapt config
* Fixed some output formatting errors
When trying to compare the output from "mkdocstrings[python-legacy]==0.27.0" and
"mkdocstrings[python]==0.28.2" I encountered some HTML errors:
- <div> inside a <p>
- unescaped non-tags <pk>
* Skip incompatible plugins during startup and remove from PLUGINS
* Handle exceptions on request processors in incompatible plugins, and display status in Plugins page
* Revert "Handle exceptions on request processors in incompatible plugins, and display status in Plugins page"
This reverts commit d97bf2ab146114cc13d751878a17a383de0fd5f8.
* Resolve merge conflicts
* Skip incompatible plugins during startup and remove from PLUGINS
* Rename Installed column to Active, and add custom PluginActiveColumn with tooltip
* Fix is_installed
* Simplify plugin_config.validate syntax
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* Merge feature
* Revert "Merge feature"
This reverts commit d1ea60f082.
* Undo simplification
* Add failed_to_load logic
* Use a TemplateColumn for is_installed
* Remove custom column class
* Remove merge vestige
* Simplify plugin attributes for is_installed column
* Use placeholders for false values to increase legibility of the plugins table
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* Add Contact filter to Services
* Add ContactModelFilterForm to ProviderAccountFilterForm
* Add Contact filter support for Aggregate
* Add Contact filter support for Prefix
* Add Contact filter to IPRange
* Add Contact filter to IPAddress
* Add Contact filter to L2VPN
* Add Contact filter to TunnelGroup
* Add Contact filter to Tunnel
* Add ContactModelFilterSet to ProviderAccountFilterSet
* Fixes classes inheritance order
Setup NetBoxModelFilterSetForm as the last inherited class
Co-authored-by: Jason Novinger <jnovinger@gmail.com>
---------
Co-authored-by: Jason Novinger <jnovinger@gmail.com>
* Add sync_interval to DataSource
* Enqueue a SyncDataSourceJob when needed after saving a DataSource
* Fix logic for clearing pending jobs on interval change
* Fix lingering background tasks after modifying DataSource
* Fixes: #15924 - Prevent API payload from allowing tagged_vlans while interface mode is set to taged-all
* Prevent cleanup of tagged_vlans when no tagged_vlans set on interface
* Fix test errors
* Remove accidental debug statements
* Update validation to model clean method instead of serializer
* Remove clearing of tagged vlans from `save()`
* Make changes to validation to account for M2M not being available under model in addition to not being able to check incoming vlans under same model.
* Optimize untagged vlan check
* Re-ordering statements in validators
* Forgot to call super().clean()
* Adjust logic for form and serializer. Add tests
* Fix test failure
* Fix ruff errors
* Fix test by removing now invalid test
* Update serializer, form and tests
* Optimize API test for vlan fields
* Optimize API serializer logic
---------
Co-authored-by: Daniel Sheppard <dans@dansheps.com>
Adds:
- dcim.choices.PowerOutletStatusChoices
- dcim.models.device_components.PowerOutlet.status field with `choices`
set to PowerOutletStatusChoices
- adds migration for PowerOutlet.status field
- updates breaking view tests
* Add SPB in L2VPN
* Change category as Other
Co-authored-by: Daniel Sheppard <dans@dansheps.com>
---------
Co-authored-by: Daniel Sheppard <dans@dansheps.com>
* 18296 add tenant to vlan groups
* 18296 add tenant to vlan groups
* 18296 add tenant to vlan groups
* 18296 add tenant to vlan groups
* 18296 review changes
During serialization, custom fields may be available to a model due to
multi-table inheritance, but might not be available in serialized data
because only direct fields of the model are covered. Now this attribute
is only used if available in serialized data. Models using multi-table
inheritance must modify their serialize_object() method to cover parent
serialization.
* Fixes#18585: filtering circuits by location
This also fixes a related issue where selected filter is not shown in
the filter form.
Changes:
- Adds `CircuitFilterSet.location_id` field to enable filtering with
incoming GET params
- Adds `CirciotFilterForm.location_id` field to enable filtering from
list form
- Adds `location_id` to the Location fieldset on `CircuitFilterForm`
* Adds test for new CircuitFilterset.location_id filter
* Fix model URL generator for plugins
* Fix reverse accessor warning
* Revert "Fix reverse accessor warning"
This reverts commit f07642bb99.
* Add URL test case for regular models
* Split dummy models
Instead of using a single model for testing, one is used for testing the
plugin API and a dedicated one is used for testing the NetBox plugin
model features.
* Fix filterset test case error
* Rename test module
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* Add racktype_count annotation to list view queryset, create the LinkedCountColumn in ManufacturerTable
* Add Manufacturer field to RackTypeFilterForm
* Setup ObjectChangeFilterForm __init__ to add query_param to filter_id
* code lint, move __init__ to end of class
* Move filter_id widget setup to SavedFiltersMixin, and add model attributes to Models FilterForms
* Add missing model declarations for filter forms
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* Changed LogLevelChoices order; Changed ScriptResultView to select LogLevelChoices to LOG_DEFAULT and setup the html template to put (All) in the last one
* Change LogLevelChoices in ScriptResultView get_table method
* Remove default option, add Default string to INFO
* Fix scripts.py and reports.py to reflect removing DEFAULT level
* fix linting
* Disable sorting by `mac_address` for legacy `mac_address` field for Device and VM Interfaces
* Ensure `primary_mac_address` field is included in field list for Device and VM Interfaces
* Remove the json filter for protection rules
* Configure PROTECTION_RULE config attribute to use ConfigJSONEncoder as serializer
* Tweak getattr()
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* Remove 'site' and 'provider_network' from CircuitTerminationIndex.display_attrs
* Use '_site' and '_provider_network' in display_attrs
* Replace private fields with 'termination'
* Iterate through a freshly queried set of CableTerminations to find endpoints in update_connected_endpoints
* Add defensive break if q_filter has not been populated
* Rename circuit to member on CircuitGroupAssignment
* Support group assignment for virtual circuits
* Update release notes
* Introduce separate nav menu heading for circuit groups
* Add generic relations for group assignments
* Remove obsolete code
* Clean up bulk import & extend tests
* Validate that a scope has been selected if a scope_type is specified, on CachedScopeMixin models
* Cleaner logic
* Call super().clean() after validating scope_type/scope
* Suppress adding the RSS feed widget to the dashboard if ISOLATED_DEPLOYMENT is set
* Add config option on RSSFeedWidget to specify requires_internet and to display a more appropriate error if ISOLATED_DEPLOYMENT is set
* Remove skipping behavior from utils.py
* Add required=False
* Extend register_model_view() to enable registering list views
* Register circuits list views with register_model_view()
* Register core list views with register_model_view()
* Fix bulk_edit & bulk_delete URL paths
* Register dcim list views with register_model_view() (WIP)
* Register dcim list views with register_model_view()
* Register extras list views with register_model_view()
* Register ipam list views with register_model_view()
* Register tenancy list views with register_model_view()
* Register users list views with register_model_view()
* Register virtualization list views with register_model_view()
* Register vpn list views with register_model_view()
* Register wireless list views with register_model_view()
* Add change note for register_model_view()
* Create MACAddress model and migrations to convert existing .mac_address fields to standalone objects
* Add migrations
* All views/filtering working and documentation done; no unit tests yet
* Redo migrations following VLAN Translation
* Remove mac_address filter fields and add table columns for device/vm
* Remove unnecessary "bulk rename"
* Fix filterset tests for Device
* Fix filterset tests for Interface
* Fix tests on single-object forms
* Fix serializer tests
* Fix filterset tests for VMInterface
* Fix filterset tests for Device and VirtualMachine
* Move new field check into lookup_map iteration
* Fix general MACAddress filter tests
* Add GraphQL types/filters/schema
* Fix bulk edit/create tests (bulk editing Interfaces will be unsupported because of inheritance from ComponentBulkEditForm)
* Make mac_address read_only on InterfaceSerializer/VMInterfaceSerializer
* Undo unrelated work
* Cleanup unused IPAddress derived stuff
* API endpoints
* Add serializer objects to interface serializers
* Clean up unnecessary bulk create forms/views/routes
* Add SearchIndex and adjust indexable fields for Interface and VMInterface
* Reorganize MACAddress classes out of association with DeviceComponents
* Move MACAddressSerializer
* Enforce saving only a single is_primary MACAddress per interface/vminterface
* Perform is_primary validation on MACAddress model and just check if one already exists for the interface
* Remove form-level validation
* Fix check for current is_primary setting when reassigning
* Model cleanup
* Documentation notes and cleanup
* Simplify serializer and add ip_addresses
* Add to VMInterfaceSerializer too
* Style cleanup
* Standardize "MAC Address" instead of "MAC"
* Remove unused views
* Add is_primary field for bulk edit
* HTML cleanup and add copy-to-clipboard button
* Remove mac_address from Interface and VMInterface bulk-edit forms
* Add device and VM filtering
* Use combined assigned_object_parent in table to match structure of IPAddressTable
* Add GFK fields to MACAddressSerializer
* Reorganize "Addressing" sections to remove from proximity to "Device Components" and related groupings
* Clean up migrations
* Misc cleanup
* Add filterset test
* Remove mac_address field from interface forms
* Designate primary MAC address via a ForeignKey on the interface models
* Add serializer fields for primary_mac_address
* Update docs
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* 12596 Add Allocated Resources to Cluster API
* 12596 Add Allocated Resources to Cluster API
* 12596 Add Allocated Resources to Cluster API
* 12596 Add Allocated Resources to Cluster API
* 12596 review changes
* 12596 review changes
* Fix check for existing jobs
If a job is to be enqueued once and no specific scheduled time is
specified, any scheduled time of existing jobs will be valid. Only if a
specific scheduled time is specified for 'enqueue_once()' can it be
evaluated.
* Allow system jobs to be registered
A new registry key allows background system jobs to be registered and
automatically scheduled when rqworker starts.
* Test scheduling of system jobs
* Fix plugins scheduled job documentation
The documentation reflected a non-production state of the JobRunner
framework left over from development. Now a more practical example
demonstrates the usage.
* Allow plugins to register system jobs
* Rename system job metadata
To clarify which meta-attributes belong to system jobs, each of them is
now prefixed with 'system_'.
* Add predefined job interval choices
* Remove 'system_enabled' JobRunner attribute
Previously, the 'system_enabled' attribute was used to control whether a
job should run or not. However, this can also be accomplished by
evaluating the job's interval.
* Fix test
* Use a decorator to register system jobs
* Specify interval when registering system job
* Update documentation
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* VLANTranslationPolicy and VLANTranslationRule models and all associated UI classes
* Change VLANTranslationPolicy to a PrimaryModel and make name unique
* Add serializer classes to InterfaceSerializer
* Remake migrations
* Add GraphQL typing
* Skip tagged models in test
* Missing migration
* Remove get_absolute_url methods
* Remove package-lock.json
* Rebuild migration and add constraints and field options
* Rebuild migrations
* Use DynamicModelChoiceField for policy field
* Make vlan_translation_policy fields on filtersets more consistent with existing __name convention
* Add vlan_translation_table to VMInterface detail page
* Add vlan_translation_policy to VMInterfaceSerializer
* Move vlan_translation_policy fields to model and filterset mixins
* Protect in-use policies against deletion
* Add vlan_translation_policy to fields in VMInterfaceSerializer
* Cleanup indentation
* Remove unnecessary ordering column
* Rebuild migrations
* Search methods and registration
* Ensure 'id' column is present by default
* Add graphql types/filters/schema for VLANTranslationRule
* Filterset tests
* View tests
* API and viewset tests (incomplete)
* Add tags to VLANTranslationRuleForm
* Complete viewset tests for VLANTranslationRule
* Make VLANTranslationRule.policy nullable (but still required)
* Revert "Make VLANTranslationRule.policy nullable (but still required)"
This reverts commit 4c1bb437ef.
* Revert nullability
* Explicitly prefetch policy in graphql
* Documentation of new and affected models
* Add note about select_related in graphql
* Rework policy/rule documentation
* Move vlan_translation_policy into 802.1Q Switching fieldset
* Remove redundant InterfaceVLANTranslationTable
* Conditionally include vlan_translation_table in interface.html and vminterface.html
* Add description field to VLANTranslationRule
* Define vlan_translation_table conditionally
* Add policy (name) filter to VLANTranslationRuleFilterSet
* Revert changes to adding-models.md (moved to another PR)
* Dynamic table for linked rules in vlantranslationpolicy.html
* Misc cleanup
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* Replace site FK on Prefix with scope GFK
* Add denormalized relations
* Update prefix filters
* Add generic relations for Prefix
* Update GraphQL type for Prefix model
* Fix tests; misc cleanup
* Remove prefix_count from SiteSerializer
* Remove site field from PrefixBulkEditForm
* Restore scope filters for prefixes
* Fix scope population on PrefixForm init
* Show scope type
* Assign scope during bulk import of prefixes
* Correct handling of GenericForeignKey in PrefixForm
* Add prefix counts to all scoped objects
* Fix migration; linter fix
* Add limit_choices_to on scope_type
* Clean up cache_related_objects()
* Enable bulk editing prefix scope
* 17195 Add color to PowerOutlet
* 17195 Add color to PowerOutlet
* Reorder serializer fields
* Misc cleanup
---------
Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
* It's very important that you not submit a pull request until a relevant issue has been opened **and** assigned to you. Otherwise, you risk wasting time on work that may ultimately not be needed.
* New pull requests should generally be based off of the `develop` branch, rather than `master`. The `develop` branch is used for ongoing development, while `master` is used for tracking stable releases. (If you're developing for an upcoming minor release, use `feature` instead.)
* New pull requests should generally be based off of the `main` branch. This branch, in keeping with the [trunk-based development](https://trunkbaseddevelopment.com/) approach, is used for ongoing development and bug fixes and always represents the newest stable code, from which releases are periodically branched. (If you're developing for an upcoming minor release, use `feature` instead.)
* In most cases, it is not necessary to add a changelog entry: A maintainer will take care of this when the PR is merged. (This helps avoid merge conflicts resulting from multiple PRs being submitted simultaneously.)
@@ -109,21 +109,9 @@ Do you have an idea for something you'd like to build in NetBox, but might not b
Check out our [plugin development tutorial](https://github.com/netbox-community/netbox-plugin-tutorial) to get started!
## :rescue_worker_helmet: Become a Maintainer
## :briefcase: Looking for a Job?
We're always looking for motivated individuals to join the maintainers team and help drive NetBox's long-term development. Some of our most sought-after skills include:
* Python development with a strong focus on the [Django](https://www.djangoproject.com/) framework
* Expertise working with PostgreSQL databases
* Javascript & TypeScript proficiency
* A knack for web application design (HTML & CSS)
* Familiarity with git and software development best practices
* Excellent attention to detail
* Working experience in the field of network operations & engineering
We generally ask that maintainers dedicate around four hours of work to the project each week on average, which includes both hands-on development and project management tasks such as issue triage. Maintainers are also encouraged (but not required) to attend our bi-weekly Zoom call to catch up on recent items.
Interested? You can contact our lead maintainer, Jeremy Stretch, at jeremy@netbox.dev or on the [NetDev Community Slack](https://netdev.chat/). We'd love to have you on the team!
At [NetBox Labs](https://netboxlabs.com/), we're always looking for highly skilled and motivated people to join our team. While NetBox is a core part of our product lineup, we have an ever-expanding suite of solutions serving the network automation space. Check out our [current openings](https://netboxlabs.com/careers/) to see if you might be a fit!
@@ -14,6 +14,12 @@ Administrators are encouraged to adhere to industry best practices concerning th
* Prohibit access to your database from clients other than the NetBox application
* Keep your deployment updated to the most recent stable release
## Compliance Reporting
Please note that security compliance reports (e.g. SOC 2) are provided by NetBox Labs only to customers using NetBox Cloud or NetBox Enterprise. They are not available to users of self-hosted NetBox Community Edition.
If you would like to consider upgrading to NetBox Cloud or Enterprise, please contact `sales@netboxlabs.com`.
## Reporting a Suspected Vulnerability
If you believe you've uncovered a security vulnerability and wish to report it confidentially, you may do so by emailing `security@netboxlabs.com`. Please ensure that your report meets all the following conditions:
NetBox supports native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this functionality, set `SENTRY_ENABLED` to True and define your unique [data source name (DSN)](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/) in `configuration.py`.
NetBox supports native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this functionality, set `SENTRY_ENABLED` to `True` and define your unique [data source name (DSN)](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/) in `configuration.py`.
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/miscellaneous.md#changelog_retention)
* Deleting job result records older than the configured [retention time](../configuration/miscellaneous.md#job_retention)
* Check for new NetBox releases (if [`RELEASE_CHECK_URL`](../configuration/miscellaneous.md#release_check_url) is set)
This command can be invoked directly, or by using the shell script provided at `/opt/netbox/contrib/netbox-housekeeping.sh`.
## Scheduling
### Using Cron
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.
On Debian-based systems, be sure to omit the `.sh` file extension when linking to the script from within a cron directory. Otherwise, the task may not run.
### Using Systemd
First, create symbolic links for the systemd service and timer files. Link the existing service and timer files from the `/opt/netbox/contrib/` directory to the `/etc/systemd/system/` directory:
You may need to change the username, host, and/or database in the command above to match your installation.
When replicating a production database for development purposes, you may find it convenient to exclude changelog data, which can easily account for the bulk of a database's size. To do this, exclude the `extras_objectchange` table data from the export. The table will still be included in the output file, but will not be populated with any data.
When replicating a production database for development purposes, you may find it convenient to exclude changelog data, which can easily account for the bulk of a database's size. To do this, exclude the `core_objectchange` table data from the export. The table will still be included in the output file, but will not be populated with any data.
By default, NetBox stores uploaded files (such as image attachments) in its media directory. To fully replicate an instance of NetBox, you'll need to copy both the database and the media files.
!!! note
These operations are not necessary if your installation is utilizing a [remote storage backend](../configuration/system.md#storage_backend).
These operations are not necessary if your installation is utilizing a [remote storage backend](../configuration/system.md#storages).
@@ -69,7 +69,7 @@ For a complete list of available preferences, log into NetBox and navigate to `/
!!! tip "Dynamic Configuration Parameter"
Default: 50
Default: `50`
The default maximum number of objects to display per page within each list of objects.
@@ -79,7 +79,7 @@ The default maximum number of objects to display per page within each list of ob
!!! tip "Dynamic Configuration Parameter"
Default: 15
Default: `15`
The default value for the `amperage` field when creating new power feeds.
@@ -89,7 +89,7 @@ The default value for the `amperage` field when creating new power feeds.
!!! tip "Dynamic Configuration Parameter"
Default: 80
Default: `80`
The default value (percentage) for the `max_utilization` field when creating new power feeds.
@@ -99,7 +99,7 @@ The default value (percentage) for the `max_utilization` field when creating new
!!! tip "Dynamic Configuration Parameter"
Default: 120
Default: `120`
The default value for the `voltage` field when creating new power feeds.
@@ -109,7 +109,7 @@ The default value for the `voltage` field when creating new power feeds.
!!! tip "Dynamic Configuration Parameter"
Default: 22
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`.
@@ -119,6 +119,6 @@ Default height (in pixels) of a unit within a rack elevation. For best results,
!!! tip "Dynamic Configuration Parameter"
Default: 220
Default: `220`
Default width (in pixels) of a unit within a rack elevation.
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](./system.md#internal_ips) will see debugging tools in the user
@@ -16,6 +16,6 @@ interface.
## DEVELOPER
Default: False
Default: `False`
This parameter serves as a safeguard to prevent some potentially dangerous behavior, such as generating new database schema migrations. Additionally, enabling this setting disables the debug warning banner in the UI. Set this to `True`**only** if you are actively developing the NetBox code base.
Set to True to enable automatic error reporting via [Sentry](https://sentry.io/).
Set to `True` to enable automatic error reporting via [Sentry](https://sentry.io/).
!!! note
The `sentry-sdk` Python package is required to enable Sentry integration.
@@ -25,7 +25,7 @@ Set to True to enable automatic error reporting via [Sentry](https://sentry.io/)
## SENTRY_SAMPLE_RATE
Default: 1.0 (all)
Default: `1.0` (all)
The sampling rate for errors. Must be a value between 0 (disabled) and 1.0 (report on all errors).
@@ -33,7 +33,7 @@ The sampling rate for errors. Must be a value between 0 (disabled) and 1.0 (repo
## SENTRY_SEND_DEFAULT_PII
Default: False
Default: `False`
Maps to the Sentry SDK's [`send_default_pii`](https://docs.sentry.io/platforms/python/configuration/options/#send-default-pii) parameter. If enabled, certain personally identifiable information (PII) is added.
@@ -60,7 +60,7 @@ SENTRY_TAGS = {
## SENTRY_TRACES_SAMPLE_RATE
Default: 0 (disabled)
Default: `0` (disabled)
The sampling rate for transactions. Must be a value between 0 (disabled) and 1.0 (report on all transactions).
@@ -55,9 +55,9 @@ Sets content for the top banner in the user interface.
## CENSUS_REPORTING_ENABLED
Default: True
Default: `True`
Enables anonymous census reporting. To opt out of census reporting, set this to False.
Enables anonymous census reporting. To opt out of census reporting, set this to `False`.
This data enables the project maintainers to estimate how many NetBox deployments exist and track the adoption of new versions over time. Census reporting effects a single HTTP request each time a worker starts. The only data reported by this function are the NetBox version, Python version, and a pseudorandom unique identifier.
@@ -67,7 +67,7 @@ This data enables the project maintainers to estimate how many NetBox deployment
!!! tip "Dynamic Configuration Parameter"
Default: 90
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.
@@ -79,7 +79,7 @@ changes in the database indefinitely.
## CHANGELOG_SKIP_EMPTY_CHANGES
Default: True
Default: `True`
If enabled, a change log record will not be created when an object is updated without any changes to its existing field values.
@@ -96,21 +96,21 @@ The maximum size (in bytes) of an incoming HTTP request (i.e. `GET` or `POST` da
---
## DJANGO_ADMIN_ENABLED
Default: False
Setting this to True installs the `django.contrib.admin` app and enables the [Django admin UI](https://docs.djangoproject.com/en/5.0/ref/contrib/admin/). This may be necessary to support older plugins which do not integrate with the native NetBox interface.
---
## ENFORCE_GLOBAL_UNIQUE
!!! tip "Dynamic Configuration Parameter"
Default: True
Default: `True`
By default, NetBox will prevent the creation of duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This validation can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to False.
By default, NetBox will prevent the creation of duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This validation can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to `False`.
---
## EVENTS_PIPELINE
Default: `['extras.events.process_event_queue',]`
NetBox will call dotted paths to the functions listed here for events (create, update, delete) on models as well as when custom EventRules are fired.
---
@@ -126,7 +126,7 @@ The maximum amount (in bytes) of uploaded data that will be held in memory befor
!!! tip "Dynamic Configuration Parameter"
Default: 90
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.
@@ -139,9 +139,9 @@ The number of days to retain job results (scripts and reports). Set this to `0`
!!! tip "Dynamic Configuration Parameter"
Default: False
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.
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.
---
@@ -159,7 +159,7 @@ This specifies the URL to use when presenting a map of a physical location by st
!!! tip "Dynamic Configuration Parameter"
Default: 1000
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`.
@@ -167,7 +167,7 @@ A web user or API consumer can request an arbitrary number of objects by appendi
## METRICS_ENABLED
Default: False
Default: `False`
Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../integrations/prometheus-metrics.md) documentation for more details.
@@ -177,9 +177,9 @@ Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Pr
!!! tip "Dynamic Configuration Parameter"
Default: False
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.
When determining the primary IP address for a device, IPv6 is preferred over IPv4 by default. Set this to `True` to prefer IPv4 instead.
---
@@ -201,7 +201,7 @@ If no queue is defined the queue named `default` will be used.
## RELEASE_CHECK_URL
Default: None (disabled)
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.
@@ -231,3 +231,15 @@ This parameter controls how frequently a failed job is retried, up to the maximu
Default: `0` (retries disabled)
The maximum number of times a background task will be retried before being marked as failed.
## DISK_BASE_UNIT
Default: `1000`
The base unit for disk sizes. Set this to `1024` to use binary prefixes (MiB, GiB, etc.) instead of decimal prefixes (MB, GB, etc.).
## RAM_BASE_UNIT
Default: `1000`
The base unit for RAM sizes. Set this to `1024` to use binary prefixes (MiB, GiB, etc.) instead of decimal prefixes (MB, GB, etc.).
A list of installed [NetBox plugins](../plugins/index.md) to enable. Plugins will not take effect unless they are listed here.
@@ -13,7 +13,7 @@ A list of installed [NetBox plugins](../plugins/index.md) to enable. Plugins wil
## PLUGINS_CONFIG
Default: Empty
Default: `[]`
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:
@@ -33,3 +33,21 @@ Note that a plugin must be listed in `PLUGINS` for its configuration to take eff
---
## PLUGINS_CATALOG_CONFIG
Default: `{}` (Empty)
This parameter controls how individual plugins are displayed in the plugins catalog under Admin > System > Plugins. Adding a plugin to the `hidden` list will omit that plugin from the catalog. Adding a plugin to the `static` list will display the plugin, but not link to the plugin details or upgrade instructions.
The configuration parameters listed here control remote authentication for NetBox. Note that `REMOTE_AUTH_ENABLED` must be true in order for these settings to take effect.
The configuration parameters listed here control remote authentication for NetBox. Note that `REMOTE_AUTH_ENABLED` must be `True` in order for these settings to take effect.
---
@@ -8,7 +8,7 @@ The configuration parameters listed here control remote authentication for NetBo
Default: `False`
If true, NetBox will automatically create groups specified in the `REMOTE_AUTH_GROUP_HEADER` header if they don't already exist. (Requires `REMOTE_AUTH_ENABLED`.)
If `True`, NetBox will automatically create groups specified in the `REMOTE_AUTH_GROUP_HEADER` header if they don't already exist. (Requires `REMOTE_AUTH_ENABLED`.)
---
@@ -16,7 +16,7 @@ If true, NetBox will automatically create groups specified in the `REMOTE_AUTH_G
Default: `False`
If true, NetBox will automatically create local accounts for users authenticated via a remote service. (Requires `REMOTE_AUTH_ENABLED`.)
If `True`, NetBox will automatically create local accounts for users authenticated via a remote service. (Requires `REMOTE_AUTH_ENABLED`.)
---
@@ -43,7 +43,7 @@ The list of groups to assign a new user account when created using remote authen
Default: `{}` (Empty dictionary)
A mapping of permissions to assign a new user account when created using remote authentication. Each key in the dictionary should be set to a dictionary of the attributes to be applied to the permission, or `None` to allow all objects. (Requires `REMOTE_AUTH_ENABLED` as True and `REMOTE_AUTH_GROUP_SYNC_ENABLED` as False.)
A mapping of permissions to assign a new user account when created using remote authentication. Each key in the dictionary should be set to a dictionary of the attributes to be applied to the permission, or `None` to allow all objects. (Requires `REMOTE_AUTH_ENABLED` as `True` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` as `False`.)
This is a list of valid fully-qualified domain names (FQDNs) and/or IP addresses that can be used to reach the NetBox service. Usually this is the same as the hostname for the NetBox server, but can also be different; for example, when using a reverse proxy serving the NetBox website under a different FQDN than the hostname of the NetBox server. To help guard against [HTTP Host header attackes](https://docs.djangoproject.com/en/3.0/topics/security/#host-headers-virtual-hosting), NetBox will not permit access to the server via any other hostnames (or IPs).
This is a list of valid fully-qualified domain names (FQDNs) and/or IP addresses that can be used to reach the NetBox service. Usually this is the same as the hostname for the NetBox server, but can also be different; for example, when using a reverse proxy serving the NetBox website under a different FQDN than the hostname of the NetBox server. To help guard against [HTTP Host header attacks](https://docs.djangoproject.com/en/stable/topics/security/#host-headers-virtual-hosting), NetBox will not permit access to the server via any other hostnames (or IPs).
!!! note
This parameter must always be defined as a list or tuple, even if only a single value is provided.
The value of this option is also used to set `CSRF_TRUSTED_ORIGINS`, which restricts POST requests to the same set of hosts (more about this [here](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-CSRF_TRUSTED_ORIGINS)). Keep in mind that NetBox, by default, sets `USE_X_FORWARDED_HOST` to true, which means that if you're using a reverse proxy, it's the FQDN used to reach that reverse proxy which needs to be in this list (more about this [here](https://docs.djangoproject.com/en/stable/ref/settings/#allowed-hosts)).
The value of this option is also used to set `CSRF_TRUSTED_ORIGINS`, which restricts POST requests to the same set of hosts (more about this [here](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-CSRF_TRUSTED_ORIGINS)). Keep in mind that NetBox, by default, sets `USE_X_FORWARDED_HOST` to `True`, which means that if you're using a reverse proxy, it's the FQDN used to reach that reverse proxy which needs to be in this list (more about this [here](https://docs.djangoproject.com/en/stable/ref/settings/#allowed-hosts)).
Example:
@@ -25,7 +25,28 @@ ALLOWED_HOSTS = ['*']
## DATABASE
NetBox requires access to a PostgreSQL 12 or later database service to store data. This service can run locally on the NetBox server or on a remote system. The following parameters must be defined within the `DATABASE` dictionary:
!!! warning "Legacy Configuration Parameter"
The `DATABASE` configuration parameter is deprecated and will be removed in a future release. Users are advised to adopt the new `DATABASES` (plural) parameter, which allows for the configuration of multiple databases.
See the [`DATABASES`](#databases) configuration below for usage.
---
## DATABASES
NetBox requires access to a PostgreSQL 14 or later database service to store data. This service can run locally on the NetBox server or on a remote system. Databases are defined as named dictionaries:
```python
DATABASES={
'default':{...},
'external1':{...},
'external2':{...},
}
```
NetBox itself requires only that a `default` database is defined. However, certain plugins may require the configuration of additional databases. (Consider also configuring the [`DATABASE_ROUTERS`](./system.md#database_routers) parameter when multiple databases are in use.)
The following parameters must be defined for each database:
*`NAME` - Database name
*`USER` - PostgreSQL username
@@ -38,14 +59,16 @@ NetBox requires access to a PostgreSQL 12 or later database service to store dat
'PORT':'',# Database port (leave blank for default)
'CONN_MAX_AGE':300,# Max database connection age
}
}
```
@@ -53,7 +76,7 @@ DATABASE = {
NetBox supports all PostgreSQL database options supported by the underlying Django framework. For a complete list of available parameters, please see [the Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#databases).
!!! warning
Make sure to use a PostgreSQL-compatible backend for the ENGINE setting. If you don't specify an ENGINE, the default will be django.db.backends.postgresql.
The `ENGINE` parameter must specify a PostgreSQL-compatible database backend. If not defined, the default engine `django.db.backends.postgresql` will be used.
The default value of this parameter changed from `True` to `False` in NetBox v4.3.0.
If disabled, the values of API tokens will not be displayed after each token's initial creation. A user **must** record the value of a token prior to its creation, or it will be lost. Note that this affects _all_ users, regardless of assigned permissions.
@@ -47,9 +50,9 @@ Although it is not recommended, the default validation rules can be disabled by
## CORS_ORIGIN_ALLOW_ALL
Default: False
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).
If `True`, cross-origin resource sharing (CORS) requests will be accepted from all origins. If False, a whitelist will be used (see below).
---
@@ -59,7 +62,7 @@ If True, cross-origin resource sharing (CORS) requests will be accepted from all
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:
expressions. (These settings have no effect if `CORS_ORIGIN_ALLOW_ALL` is `True`.) For example:
```python
CORS_ORIGIN_WHITELIST=[
@@ -79,9 +82,9 @@ The name of the cookie to use for the cross-site request forgery (CSRF) authenti
## CSRF_COOKIE_SECURE
Default: False
Default: `False`
If true, the cookie employed for cross-site request forgery (CSRF) protection will be marked as secure, meaning that it can only be sent across an HTTPS connection.
If `True`, the cookie employed for cross-site request forgery (CSRF) protection will be marked as secure, meaning that it can only be sent across an HTTPS connection.
---
@@ -89,7 +92,7 @@ If true, the cookie employed for cross-site request forgery (CSRF) protection wi
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://).
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/stable/ref/settings/#csrf-trusted-origins) setting. Note that each host listed must specify a scheme (e.g. `http://` or `https://).
```python
CSRF_TRUSTED_ORIGINS = (
@@ -132,7 +135,7 @@ DEFAULT_PERMISSIONS = {
## EXEMPT_VIEW_PERMISSIONS
Default: Empty list
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.
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.
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.
@@ -169,7 +172,7 @@ Note that enabling this setting causes NetBox to update a user's session in the
## LOGIN_REQUIRED
Default: True
Default: `True`
When enabled, only authenticated users are permitted to access any part of NetBox. Disabling this will allow unauthenticated users to access most areas of NetBox (but not make any changes).
@@ -180,12 +183,23 @@ When enabled, only authenticated users are permitted to access any part of NetBo
## LOGIN_TIMEOUT
Default: 1209600 seconds (14 days)
Default: `1209600` seconds (14 days)
The lifetime (in seconds) of the authentication cookie issued to a NetBox user upon login.
---
## LOGIN_FORM_HIDDEN
Default: `False`
Option to hide the login form when only SSO authentication is in use.
!!! warning
If the SSO provider is unreachable, login to NetBox will be impossible if this option is enabled. The only recourse is to disable it in the local configuration and restart the NetBox service.
---
## LOGOUT_REDIRECT_URL
Default: `'home'`
@@ -196,23 +210,23 @@ The view name or URL to which a user is redirected after logging out.
## SECURE_HSTS_INCLUDE_SUBDOMAINS
Default: False
Default: `False`
If true, the `includeSubDomains` directive will be included in the HTTP Strict Transport Security (HSTS) header. This directive instructs the browser to apply the HSTS policy to all subdomains of the current domain.
If `True`, the `includeSubDomains` directive will be included in the HTTP Strict Transport Security (HSTS) header. This directive instructs the browser to apply the HSTS policy to all subdomains of the current domain.
---
## SECURE_HSTS_PRELOAD
Default: False
Default: `False`
If true, the `preload` directive will be included in the HTTP Strict Transport Security (HSTS) header. This directive instructs the browser to preload the site in HTTPS. Browsers that use the HSTS preload list will force the site to be accessed via HTTPS even if the user types HTTP in the address bar.
If `True`, the `preload` directive will be included in the HTTP Strict Transport Security (HSTS) header. This directive instructs the browser to preload the site in HTTPS. Browsers that use the HSTS preload list will force the site to be accessed via HTTPS even if the user types HTTP in the address bar.
---
## SECURE_HSTS_SECONDS
Default: 0
Default: `0`
If set to a non-zero integer value, the SecurityMiddleware sets the HTTP Strict Transport Security (HSTS) header on all responses that do not already have it. This will instruct the browser that the website must be accessed via HTTPS, blocking any HTTP request.
@@ -220,9 +234,9 @@ If set to a non-zero integer value, the SecurityMiddleware sets the HTTP Strict
## SECURE_SSL_REDIRECT
Default: False
Default: `False`
If true, all non-HTTPS requests will be automatically redirected to use HTTPS.
If `True`, all non-HTTPS requests will be automatically redirected to use HTTPS.
!!! warning
Ensure that your frontend HTTP daemon has been configured to forward the HTTP scheme correctly before enabling this option. An incorrectly configured frontend may result in a looping redirect.
@@ -239,14 +253,14 @@ The name used for the session cookie. See the [Django documentation](https://doc
## SESSION_COOKIE_SECURE
Default: False
Default: `False`
If true, the cookie employed for session authentication will be marked as secure, meaning that it can only be sent across an HTTPS connection.
If `True`, the cookie employed for session authentication will be marked as secure, meaning that it can only be sent across an HTTPS connection.
---
## SESSION_FILE_PATH
Default: None
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.
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:
@@ -12,6 +12,14 @@ BASE_PATH = 'netbox/'
---
## DATABASE_ROUTERS
Default: `[]` (empty list)
An iterable of [database routers](https://docs.djangoproject.com/en/stable/topics/db/multi-db/) to use for automatically selecting the appropriate database(s) for a query. This is useful only when [multiple databases](./required-parameters.md#databases) have been configured.
---
## DEFAULT_LANGUAGE
Default: `en-us` (US English)
@@ -62,9 +70,19 @@ Email is sent from NetBox only for critical events or if configured for [logging
---
## HOSTNAME
!!! info "This parameter was introduced in NetBox v4.4."
Default: System hostname
The hostname displayed in the user interface identifying the system on which NetBox is running. If not defined, this defaults to the system hostname as reported by Python's `platform.node()`.
---
## HTTP_PROXIES
Default: None
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://requests.readthedocs.io/en/latest/user/advanced/#proxies). For example:
@@ -75,6 +93,8 @@ HTTP_PROXIES = {
}
```
If more flexibility is needed in determining which proxy to use for a given request, consider implementing one or more custom proxy routers via the [`PROXY_ROUTERS`](#proxy_routers) parameter.
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`](./development.md#debug) is true).
addresses (and [`DEBUG`](./development.md#debug) is `True`).
---
## ISOLATED_DEPLOYMENT
!!! info "This feature was introduced in NetBox v4.1."
Default: `False`
Default: False
Set this configuration parameter to True for NetBox deployments which do not have Internet access. This will disable miscellaneous functionality which depends on access to the Internet.
Set this configuration parameter to `True` for NetBox deployments which do not have Internet access. This will disable miscellaneous functionality which depends on access to the Internet.
!!! note
If Internet access is available via a proxy, set [`HTTP_PROXIES`](#http_proxies) instead.
@@ -104,7 +122,7 @@ Set this configuration parameter to True for NetBox deployments which do not hav
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:
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):
@@ -148,6 +166,8 @@ LOGGING = {
* `netbox.<app>.<model>` - Generic form for model-specific log messages
* `netbox.auth.*` - Authentication events
* `netbox.api.views.*` - Views which handle business logic for the REST API
* `netbox.views.*` - Views which handle business logic for the web UI
@@ -162,6 +182,16 @@ The file path to the location where media files (such as image attachments) are
---
## PROXY_ROUTERS
Default: `["utilities.proxy.DefaultProxyRouter"]`
A list of Python classes responsible for determining which proxy server(s) to use for outbound HTTP requests. Each item in the list can be the class itself or the dotted path to the class.
The `route()` method on each class must return a dictionary of candidate proxies arranged by protocol (e.g. `http` and/or `https`), or None if no viable proxy can be determined. The default class, `DefaultProxyRouter`, simply returns the content of [`HTTP_PROXIES`](#http_proxies).
---
## REPORTS_ROOT
Default: `$INSTALL_ROOT/netbox/reports/`
@@ -186,29 +216,52 @@ The dotted path to the desired search backend class. `CachedValueSearchBackend`
---
## STORAGE_BACKEND
## STORAGES
Default: None (local storage)
The backend storage engine for handling uploaded files such as [image attachments](../models/extras/imageattachment.md) and [custom scripts](../customization/custom-scripts.md). NetBox integrates with the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) and [`django-storage-swift`](https://github.com/dennisv/django-storage-swift) libraries, which provide backends for several popular file storage services. If not configured, local filesystem storage will be used.
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/) and [`django-storage-swift`](https://github.com/dennisv/django-storage-swift) packages, which provide backends for several popular file storage services. If not configured, local filesystem storage will be used.
By default, the following configuration is used:
The configuration parameters for the specified storage backend are defined under the `STORAGE_CONFIG` setting.
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 documentation for your selected backend ([`django-storages`](https://django-storages.readthedocs.io/en/stable/) or [`django-storage-swift`](https://github.com/dennisv/django-storage-swift)) for more detail.
The specific configuration settings for each storage backend can be found in the [django-storages documentation](https://django-storages.readthedocs.io/en/latest/index.html).
If `STORAGE_BACKEND` is not defined, this setting will be ignored.
!!! note
Any keys defined in the `STORAGES` configuration parameter replace those in the default configuration. It is only necessary to define keys within the `STORAGES` for the specific backend(s) you wish to configure.
---
## TIME_ZONE
Default: UTC
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).
@@ -216,6 +269,6 @@ The time zone NetBox will use when dealing with dates and times. It is recommend
## TRANSLATION_ENABLED
Default: True
Default: `True`
Enables language translation for the user interface. (This parameter maps to Django's [USE_I18N](https://docs.djangoproject.com/en/stable/ref/settings/#std-setting-USE_I18N) setting.)
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 `object`, and custom fields through `object.cf`.
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 [Jinja template code](https://jinja.palletsprojects.com/en/stable/) through the variable `object`, and custom fields through `object.cf`.
@@ -140,6 +140,8 @@ The Script class provides two convenience methods for reading data from files:
These two methods will load data in YAML or JSON format, respectively, from files within the local path (i.e. `SCRIPTS_ROOT`).
**Note:** These convenience methods are deprecated and will be removed in NetBox v4.4. These only work if running scripts within the local path, they will not work if using a storage other than ScriptFileSystemStorage.
## Logging
The Script object provides a set of convenient functions for recording messages at different severity levels:
@@ -273,6 +275,15 @@ Stores a numeric integer. Options include:
*`min_value` - Minimum value
*`max_value` - Maximum value
### DecimalVar
Stores a numeric decimal. Options include:
*`min_value` - Minimum value
*`max_value` - Maximum value
*`max_digits` - Maximum number of digits, including decimal places
*`decimal_places` - Number of decimal places
### BooleanVar
A true/false flag. This field has no options beyond the defaults listed above.
@@ -308,6 +319,7 @@ A particular object within NetBox. Each ObjectVar must specify a particular mode
*`query_params` - A dictionary of query parameters to use when retrieving available options (optional)
*`context` - A custom dictionary mapping template context variables to fields, used when rendering `<option>` elements within the dropdown menu (optional; see below)
*`null_option` - A label representing a "null" or empty choice (optional)
*`selector` - A boolean that, when True, includes an advanced object selection widget to assist the user in identifying the desired object (optional; False by default)
To limit the selections available within the list, additional query parameters can be passed as the `query_params` dictionary. For example, to show only devices with an "active" status:
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:
@@ -8,7 +8,7 @@ Each model should define, at a minimum:
* A `Meta` class specifying a deterministic ordering (if ordered by fields other than the primary ID)
* A `__str__()` method returning a user-friendly string representation of the instance
* A `get_absolute_url()` method returning an instance's direct URL (using `reverse()`)
* A `get_absolute_url()` method if necessary; a standard version of the method is defined in the `NetBoxFeatureSet` base class, but you will need to provide your own (returning an instance's direct URL using `reverse()`) if not subclassing that base class
## 2. Define field choices
@@ -76,9 +76,13 @@ Create the following for each model:
## 13. GraphQL API components
Create a GraphQL object type for the model in `graphql/types.py` by subclassing the appropriate class from `netbox.graphql.types`.
Create the following for each model:
Also extend the schema class defined in `graphql/schema.py` with the individual object and object list fields per the established convention.
* GraphQL object type for the model in `graphql/types.py` (subclass the appropriate class from `netbox.graphql.types`)
* Add a GraphQL filter for the model in `graphql/filters.py`
* Extend the query class for the app in `graphql/schema.py` with the individual object and object list fields
**Note:** GraphQL unit tests may fail citing null values on a non-nullable field if related objects are prefetched. You may need to fix this by setting the type annotation to be `= strawberry_django.field(select_related=["foo"])` or similar.
@@ -22,24 +22,9 @@ Stores registration made using `netbox.denormalized.register()`. For each model,
### `model_features`
A dictionary of particular features (e.g. custom fields) mapped to the NetBox models which support them, arranged by app. For example:
A dictionary of model features (e.g. custom fields, tags, etc.) mapped to the functions used to qualify a model as supporting each feature. Model features are registered using the `register_model_feature()` function in `netbox.utils`.
```python
{
'custom_fields':{
'circuits':['provider','circuit'],
'dcim':['site','rack','devicetype',...],
...
},
'event_rules':{
'extras':['configcontext','tag',...],
'dcim':['site','rack','devicetype',...],
},
...
}
```
Supported model features are listed in the [features matrix](./models.md#features-matrix).
Core model features are listed in the [features matrix](./models.md#features-matrix).
@@ -6,7 +6,7 @@ Below is a list of tasks to consider when adding a new field to a core model.
Add the field to the model, taking care to address any of the following conditions.
* When adding a GenericForeignKey field, also add an index under `Meta` for its two concrete fields. For example:
* When adding a GenericForeignKey field, you may need add an index under `Meta` for its two concrete fields. (This is required only for non-unique GFK relationships, as the unique constraint introduces its own index.) For example:
The NetBox project utilizes three persistent git branches to track work:
The NetBox project utilizes two persistent git branches to track work:
* `master` - Serves as a snapshot of the current stable release
* `develop` - All development on the upcoming stable (patch) release occurs here
* `feature` - Tracks work on an upcoming minor release
* `main` - All development on the upcoming stable (patch) release occurs here. Releases are published from this branch.
* `feature` - All work planned for the upcoming minor release is done here.
Typically, you'll base pull requests off of the `develop` branch, or off of `feature` if you're working on a new major release. For example, assume that the current NetBox release is v3.3.5. Work applied to the `develop` branch will appear in v3.3.6, and work done under the `feature` branch will be included in the next minor release (v3.4.0).
!!! warning
**Never** merge pull requests into the `master` branch: This branch only ever merges pull requests from the `develop` branch, to effect a new release.
Typically, you'll base pull requests off of the `main` branch, or off of `feature` if you're working on the upcoming minor or major release. For example, assume that the current NetBox release is v4.2.3. Work applied to the `main` branch will appear in v4.2.4, and work done under the `feature` branch will be included in the next minor release (v4.3.0).
To create a new branch, first ensure that you've checked out the desired base branch, then run:
@@ -119,7 +115,7 @@ You may also need to set up the yarn packages as shown in the [Web UI Developmen
Within the `netbox/netbox/` directory, copy `configuration_example.py` to `configuration.py` and update the following parameters:
* `ALLOWED_HOSTS`: This can be set to `['*']` for development purposes
* `REDIS`: Redis configuration (if different from the defaults)
* `SECRET_KEY`: Set to a random string (use `generate_secret_key.py` in the parent directory to generate a suitable key)
* `DEBUG`: Set to `True`
@@ -151,7 +147,7 @@ For UI development you will need to review the [Web UI Development Guide](web-ui
## Populating Demo Data
Once you have your development environment up and running, it might be helpful to populate some "dummy" data to make interacting with the UI and APIs more convenient. Check out the [netbox-demo-data](https://github.com/netbox-community/netbox-demo-data) repo on GitHub, which houses a collection of sample data that can be easily imported to any new NetBox deployment. (This sample data is used to populate the public demo instance at <https://demo.netbox.dev>.)
Once you have your development environment up and running, it might be helpful to populate some "dummy" data to make interacting with the UI and APIs more convenient. Check out the [netbox-demo-data](https://github.com/netbox-community/netbox-demo-data) repo on GitHub, which houses a collection of sample data that can be easily imported to any new NetBox deployment. This sample data is used to populate the [public demo instance](https://demo.netbox.dev).
The demo data is provided in JSON format and loaded into an empty database using Django's `loaddata` management command. Consult the demo data repo's `README` file for complete instructions on populating the data.
You generally want to avoid merging branches that exist on the remote (upstream) repository, such as `develop` and `feature`: Merges into these branches should be done via a pull request on GitHub. Only merge branches when it is necessary to consolidate work you've done locally.
You generally want to avoid merging branches that exist on the remote (upstream) repository, namely `main` and `feature`: Merges into these branches should be done via a pull request on GitHub. Only merge branches when it is necessary to consolidate work you've done locally.
### Show Pending Changes
@@ -196,7 +196,7 @@ index 93e125079..4344fb514 100644
@@ -8,11 +8,10 @@ NetBox and many of its related projects are maintained on [GitHub](https://githu
There are three permanent branches in the repository:
There are two permanent branches in the repository:
*`master` - The current stable release. Individual changes should never be pushed directly to this branch, but rather merged from `develop`.
*`develop` - Active development for the upcoming patch release. Pull requests will typically be based on this branch unless they introduce breaking changes that must be deferred until the next minor release.
*`feature` - New feature work to be introduced in the next minor release (e.g. from v3.3 to v3.4).
*`main` - Active development for the upcoming patch release. Pull requests will typically be based on this branch unless they introduce breaking changes that must be deferred until the next minor release.
*`feature` - New feature work to be introduced in the next minor release (e.g. from v4.2 to v4.3).
NetBox components are arranged into Django apps. Each app holds the models, views, and other resources relevant to a particular function:
@@ -57,4 +56,4 @@ NetBox follows the [benevolent dictator](http://oss-watch.ac.uk/resources/benevo
## Licensing
The entire NetBox project is licensed as open source under the [Apache 2.0 license](https://github.com/netbox-community/netbox/blob/master/LICENSE.txt). This is a very permissive license which allows unlimited redistribution of all code within the project. Note that all submissions to the project are subject to the same license.
The entire NetBox project is licensed as open source under the [Apache 2.0 license](https://github.com/netbox-community/netbox/blob/main/LICENSE.txt). This is a very permissive license which allows unlimited redistribution of all code within the project. Note that all submissions to the project are subject to the same license.
@@ -10,19 +10,26 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
Depending on its classification, each NetBox model may support various features which enhance its operation. Each feature is enabled by inheriting from its designated mixin class, and some features also make use of the [application registry](./application-registry.md#model_features).
| [Change logging](../features/change-logging.md) | `ChangeLoggingMixin` | - | Changes to these objects are automatically recorded in the change log |
| Cloning | `CloningMixin` | - | Provides the `clone()` method to prepare a copy |
| [Custom fields](../customization/custom-fields.md) | `CustomFieldsMixin`| `custom_fields` | These models support the addition of user-defined fields |
| [Custom links](../customization/custom-links.md) | `CustomLinksMixin` | `custom_links` | These models support the assignment of custom links |
| [Custom validation](../customization/custom-validation.md) | `CustomValidationMixin`| - | Supports the enforcement of custom validation rules |
| [Export templates](../customization/export-templates.md) | `ExportTemplatesMixin` | `export_templates` | Users can create custom export templates for these models |
| [Job results](../features/background-jobs.md) | `JobsMixin`| `jobs` | Background jobs can be scheduled for these models |
| [Journaling](../features/journaling.md) | `JournalingMixin` | `journaling` | These models support persistent historical commentary |
| [Synchronized data](../integrations/synchronized-data.md) | `SyncedDataMixin` | `synced_data` | Certain model data can be automatically synchronized from a remote data source |
| [Tagging](../models/extras/tag.md) | `TagsMixin` | `tags` | The models can be tagged with user-defined tags |
| [Event rules](../features/event-rules.md) | `EventRulesMixin`| `event_rules` | Event rules can send webhooks or run custom scripts automatically in response to events |
| [Bookmarks](../features/customization.md#bookmarks) | `BookmarksMixin` | `bookmarks` | These models can be bookmarked natively in the user interface |
| [Change logging](../features/change-logging.md) | `ChangeLoggingMixin`| `change_logging` | Changes to these objects are automatically recorded in the change log |
| Cloning | `CloningMixin` | `cloning` | Provides the `clone()` method to prepare a copy |
| [Contacts](../features/contacts.md) | `ContactsMixin` | `contacts` | Contacts can be associated with these models |
| [Custom fields](../customization/custom-fields.md) | `CustomFieldsMixin`| `custom_fields` | These models support the addition of user-defined fields |
| [Custom links](../customization/custom-links.md) | `CustomLinksMixin` | `custom_links` | These models support the assignment of custom links |
| [Custom validation](../customization/custom-validation.md) | `CustomValidationMixin`| - | Supports the enforcement of custom validation rules |
| [Event rules](../features/event-rules.md) | `EventRulesMixin` | `event_rules` | Event rules can send webhooks or run custom scripts automatically in response to events |
| [Export templates](../customization/export-templates.md) | `ExportTemplatesMixin` | `export_templates` | Users can create custom export templates for these models |
| [Image attachments](../models/extras/imageattachment.md) | `ImageAttachmentsMixin` | `image_attachments` | Image uploads can be attached to these models |
| [Jobs](../features/background-jobs.md) | `JobsMixin` | `jobs` | Background jobs can be scheduled for these models |
| [Journaling](../features/journaling.md) | `JournalingMixin` | `journaling` | These models support persistent historical commentary |
| [Notifications](../features/notifications.md) | `NotificationsMixin` | `notifications` | These models support user notifications |
| [Synchronized data](../integrations/synchronized-data.md) | `SyncedDataMixin` | `synced_data` | Certain model data can be automatically synchronized from a remote data source |
| [Tagging](../models/extras/tag.md) | `TagsMixin` | `tags` | The models can be tagged with user-defined tags |
!!! note
The above listed features are supported natively by NetBox. Beginning with NetBox v4.4.0, plugins can register their own model features as well.
This documentation describes the process of packaging and publishing a new NetBox release. There are three types of release:
This documentation describes the process of packaging and publishing a new NetBox release. There are three types of releases:
* Major release (e.g. v3.7.8 to v4.0.0)
* Minor release (e.g. v4.0.10 to v4.1.0)
* Patch release (e.g. v4.1.0 to v4.1.1)
While major releases generally introduce some very substantial change to the application, they are typically treated the same as minor version increments for the purpose of release packaging.
While major releases generally introduce some very substantial changes to the application, they are typically treated the same as minor version increments for the purpose of release packaging.
For patch releases (e.g. upgrading from v4.2.2 to v4.2.3), begin at the [patch releases](#patch-releases) heading below. For minor or major releases, complete the entire checklist.
## Minor Version Releases
@@ -29,6 +31,17 @@ Close the [release milestone](https://github.com/netbox-community/netbox/milesto
Check that a link to the release notes for the new version is present in the navigation menu (defined in `mkdocs.yml`), and that a summary of all major new features has been added to `docs/index.md`.
### Update System Requirements
If a new Django release is adopted or other major dependencies (Python, PostgreSQL, Redis) change:
* Update the installation guide (`docs/installation/index.md`) with the new minimum versions.
* Update the upgrade guide (`docs/installation/upgrading.md`) for the current version.
* Update the minimum versions for each dependency.
* Add a new row to the release history table. Bold any version changes for clarity.
* Update the minimum PostgreSQL version in the programming error template (`netbox/templates/exceptions/programming_error.html`).
* Update the minimum and supported Python versions in the project metadata file (`pyproject.toml`)
### Manually Perform a New Install
Start the documentation server and navigate to the current version of the installation docs:
@@ -37,15 +50,25 @@ Start the documentation server and navigate to the current version of the instal
mkdocs serve
```
Follow these instructions to perform a new installation of NetBox in a temporary environment. This process must not be automated: The goal of this step is to catch any errors or omissions in the documentation, and ensure that it is kept up-to-date for each release. Make any necessary changes to the documentation before proceeding with the release.
Follow these instructions to perform a new installation of NetBox in a temporary environment. This process must not be automated: The goal of this step is to catch any errors or omissions in the documentation and ensure that it is kept uptodate for each release. Make any necessary changes to the documentation before proceeding with the release.
### Test Upgrade Paths
Upgrading from a previous version typically involves database migrations, which must work without errors. Supported upgrade paths include from one minor version to another within the same major version (i.e. 4.0 to 4.1), as well as from the latest patch version of the previous minor version (i.e. 3.7 to 4.0 or to 4.1). Prior to release, test all these supported paths by loading demo data from the source version and performing a `./manage.py migrate`.
Upgrading from a previous version typically involves database migrations, which must work without errors.
Test the following supported upgrade paths:
### Merge the Release Branch
- From one minor version to another within the same major version (e.g. 4.0 to 4.1).
- From the latest patch version of the previous minor version (e.g. 3.7 to 4.0 or 4.1).
Submit a pull request to merge the `feature` branch into the `develop` branch in preparation for its release. Once it has been merged, continue with the section for patch releases below.
Prior to release, test all these supported paths by loading demo data from the source version and performing:
```no-highlight
./manage.py migrate
```
### Merge the `feature` Branch
Submit a pull request to merge the `feature` branch into the `main` branch in preparation for its release. Once it has been merged, continue with the section for the patch releases below.
### Rebuild Demo Data (After Release)
@@ -55,6 +78,15 @@ After the release of a new minor version, generate a new demo data snapshot comp
## Patch Releases
### Create a Release Branch
Begin by creating a new branch (based on `main`) to effect the release. This will comprise the changes listed below.
```
git checkout main
git checkout -B release-vX.Y.Z
```
### Notify netbox-docker Project of Any Relevant Changes
Notify the [`netbox-docker`](https://github.com/netbox-community/netbox-docker) maintainers (in **#netbox-docker**) of any changes that may be relevant to their build process, including:
@@ -76,7 +108,20 @@ In cases where upgrading a dependency to its most recent release is breaking, it
### Update UI Dependencies
Check whether any UI dependencies (JavaScript packages, fonts, etc.) need to be updated by running `yarn outdated` from within the `project-static/` directory. [Upgrade these dependencies](./web-ui.md#updating-dependencies) as necessary, then run `yarn bundle` to generate the necessary files for distribution.
Check whether any UI dependencies (JavaScript packages, fonts, etc.) need to be updated by running `yarn outdated` from within the `project-static/` directory. [Upgrade these dependencies](./web-ui.md#updating-dependencies) as necessary, then run `yarn bundle` to generate the necessary files for distribution:
```
$ yarn bundle
yarn run v1.22.19
$ node bundle.js
✅ Bundled source file 'styles/external.scss' to 'netbox-external.css'
✅ Bundled source file 'styles/netbox.scss' to 'netbox.css'
✅ Bundled source file 'styles/svg/rack_elevation.scss' to 'rack_elevation.css'
✅ Bundled source file 'styles/svg/cable_trace.scss' to 'cable_trace.css'
✅ Bundled source file 'index.ts' to 'netbox.js'
✅ Copied graphiql files
Done in 1.00s.
```
### Rebuild the Device Type Definition Schema
@@ -93,7 +138,7 @@ This will automatically update the schema file at `contrib/generated_schema.json
Updated language translations should be pulled from [Transifex](https://app.transifex.com/netbox-community/netbox/dashboard/) and re-compiled for each new release. First, retrieve any updated translation files using the Transifex CLI client:
```no-highlight
tx pull
tx pull --force
```
Then, compile these portable (`.po`) files for use in the application:
@@ -107,41 +152,30 @@ Then, compile these portable (`.po`) files for use in the application:
### Update Version and Changelog
* Update the version and published date in `release.yaml` with the current version & date. Add a designation (e.g.g `beta1`) if applicable.
* Update the version number and published date in `netbox/release.yaml`. Add or remove the designation (e.g. `beta1`) if applicable.
* Copy the version number from `release.yaml` to `pyproject.toml` in the project root.
* Update the example version numbers in the feature request and bug report templates under `.github/ISSUE_TEMPLATES/`.
* Replace the "FUTURE" placeholder in the releasenotes with the current date.
* Add a section for this release at the top of the changelog page for the minor version (e.g. `docs/release-notes/version-4.2.md`) listing all relevant changes made in this release.
Commit these changes to the `develop` branch and push upstream.
### Verify CI Build Status
Ensure that continuous integration testing on the `develop` branch is completing successfully. If it fails, take action to correct the failure before proceeding with the release.
!!! tip
Put yourself in the shoes of the user when recording change notes. Focus on the effect that each change has for the end user, rather than the specific bits of code that were modified in a PR. Ensure that each message conveys meaning absent context of the initial feature request or bug report. Remember to include keywords or phrases (such as exception names) that can be easily searched.
### Submit a Pull Request
Submit a pull request titled **"Release vX.Y.Z"** to merge the `develop` branch into `master`. Copy the documented release notes into the pull request's body.
Commit the above changes and submit a pull request titled **"Release vX.Y.Z"** to merge the current release branch (e.g. `release-vX.Y.Z`) into `main`. Copy the documented release notes into the pull request's body.
Once CI has completed on the PR, merge it. This effects a new release in the `master` branch.
Once CI has completed and a colleague has reviewed the PR, merge it. This effects a new release in the `main` branch.
!!! warning
To ensure a streamlined review process, the pull request for a release **must** be limited to the changes outlined in this document. A release PR must never include functional changes to the application: Any unrelated "cleanup" needs to be captured in a separate PR prior to the release being shipped.
### Create a New Release
Create a [new release](https://github.com/netbox-community/netbox/releases/new) on GitHub with the following parameters.
* **Tag:** Current version (e.g. `v3.3.1`)
* **Target:** `master`
* **Title:** Version and date (e.g. `v3.3.1 - 2022-08-25`)
* **Tag:** Current version (e.g. `v4.2.1`)
* **Target:** `main`
* **Title:** Version and date (e.g. `v4.2.1 - 2025-01-17`)
* **Description:** Copy from the pull request body, then promote the `###` headers to `##` ones
Once created, the release will become available for users to install.
### Update the Public Documentation
After a release has been published, the public NetBox documentation needs to be updated. This is accomplished by running two actions on the [netboxlabs-docs](https://github.com/netboxlabs/netboxlabs-docs) repository.
First, run the `build-site` action, by navigating to Actions > build-site > Run workflow. This process compiles the documentation along with an overlay for integration with the documentation portal at <https://netboxlabs.com/docs>. The job should take about two minutes.
Once the documentation files have been compiled, they must be published by running the `deploy-kinsta` action. Select the desired deployment environment (staging or production) and specify `latest` as the deploy tag.
Clear the CDN cache from the [Kinsta](https://my.kinsta.com/) portal. Navigate to _Sites_ / _NetBox Labs_ / _Live_, select _Cache_ in the left-nav, click the _Clear Cache_ button, and confirm the clear operation.
Finally, verify that the documentation at <https://netboxlabs.com/docs/netbox/en/stable/> has been updated.
@@ -22,7 +22,7 @@ NetBox generally follows the [Django style guide](https://docs.djangoproject.com
### Linting
The [ruff](https://docs.astral.sh/ruff/) linter is used to enforce code style. A [pre-commit hook](./getting-started.md#3-enable-pre-commit-hooks) which runs this automatically is included with NetBox. To invoke `ruff` manually, run:
The [ruff](https://docs.astral.sh/ruff/) linter is used to enforce code style, and is run automatically by [pre-commit](./getting-started.md#5-install-pre-commit). To invoke `ruff` manually, run:
@@ -14,10 +14,10 @@ To update the English `.po` file from which all translations are derived, use th
./manage.py makemessages -l en -i "project-static/*"
```
Then, commit the change and push to the `develop` branch on GitHub. Any new strings will appear for translation on Transifex automatically.
Then, commit the change and push to the `main` branch on GitHub. Any new strings will appear for translation on Transifex automatically.
!!! note
It is typically not necessary to update source strings manually, as this is done nightly by a [GitHub action](https://github.com/netbox-community/netbox/blob/develop/.github/workflows/update-translation-strings.yml).
It is typically not necessary to update source strings manually, as this is done nightly by a [GitHub action](https://github.com/netbox-community/netbox/blob/main/.github/workflows/update-translation-strings.yml).
## Updating Translated Strings
@@ -30,13 +30,13 @@ To download translated strings automatically, you'll need to:
1. Install the [Transifex CLI client](https://github.com/transifex/cli)
2. Generate a [Transifex API token](https://app.transifex.com/user/settings/api/)
Once you have the client set up, run the following command:
Once you have the client set up, run the following command from the project root (e.g. `/opt/netbox/`):
```no-highlight
TX_TOKEN=$TOKEN tx pull
TX_TOKEN=$TOKEN tx pull --force
```
This will download all portable (`.po`) translation files from Transifex, updating them locally as needed.
This will download all portable (`.po`) translation files from Transifex, updating them locally as needed. (The `--force` argument instructs the client to disregard the timestamps of local translation files.)
Once retrieved, the updated strings need to be compiled into new `.mo` files so they can be used by the application. Run Django's [`compilemessages`](https://docs.djangoproject.com/en/stable/ref/django-admin/#django-admin-compilemessages) management command to compile them:
@@ -46,6 +46,9 @@ Once retrieved, the updated strings need to be compiled into new `.mo` files so
Once any new `.mo` files have been generated, they need to be committed and pushed back up to GitHub. (Again, this is typically done as part of publishing a new NetBox release.)
!!! tip
Run `git status` to check that both `*.mo` & `*.po` files have been updated as expected.
## Proposing New Languages
If you'd like to add support for a new language to NetBox, the first step is to [submit a GitHub issue](https://github.com/netbox-community/netbox/issues/new?assignees=&labels=type%3A+translation&projects=&template=translation.yaml) to capture the proposal. While we'd like to add as many languages as possible, we do need to limit the rate at which new languages are added. New languages will be selected according to community interest and the number of volunteers who sign up as translators.
* Synchronization of [remote data sources](../integrations/synchronized-data.md)
* Housekeeping tasks
Additionally, NetBox plugins can enqueue their own background tasks. This is accomplished using the [Job model](../models/core/job.md). Background tasks are executed by the `rqworker` process(es).
@@ -8,6 +8,12 @@ When a request is made, a UUID is generated and attached to any change records r
Change records are exposed in the API via the read-only endpoint `/api/extras/object-changes/`. They may also be exported via the web UI in CSV format.
## User Messages
!!! info "This feature was introduced in NetBox v4.4."
When creating, modifying, or deleting an object in NetBox, a user has the option of recording an arbitrary message that will appear in the change record. This can be helpful to capture additional context, such as the reason for the change.
## Correlating Changes by Request
Every request made to NetBox is assigned a random unique ID that can be used to correlate change records. For example, if you change the status of three sites using the UI's bulk edit feature, you will see three new change records (one for each site) all referencing the same request ID. This shows that all three changes were made as part of the same request.
@@ -46,7 +46,7 @@ Regions will always be listed alphabetically by name within each parent, and the
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.
The use of both regions and site groups affords two independent but complementary dimensions across which sites can be organized.
@@ -62,8 +62,8 @@ VRF modeling in NetBox very closely follows what you find in real-world network
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
## Application 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.
To model application services in NetBox, begin by creating an application 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 application services by hand, without a template, however this approach can be tedious.
!!! info "This feature was introduced in NetBox v4.1."
NetBox includes a system for generating user notifications, which can be marked as read or deleted by individual users. There are two built-in mechanisms for generating a notification:
* A user can subscribe to an object. When that object is modified, a notification is created to inform the user of the change.
@@ -9,7 +9,7 @@ NetBox is the leading solution for modeling and documenting modern networks. By
## :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 infrastructure design and documentation. These cover all facets of network technology, from IP address managements to cabling to overlays and more:
Unlike general-purpose configuration management databases (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:
This section entails the installation and configuration of a local PostgreSQL database. If you already have a PostgreSQL database service in place, skip to [the next section](2-redis.md).
!!! warning "PostgreSQL 12 or later required"
NetBox requires PostgreSQL 12 or later. Please note that MySQL and other relational databases are **not** supported.
!!! warning "PostgreSQL 14 or later required"
NetBox requires PostgreSQL 14 or later. Please note that MySQL and other relational databases are **not** supported.
## Installation
=== "Ubuntu"
```no-highlight
sudo apt update
sudo apt install -y postgresql
```
```no-highlight
sudo apt update
sudo apt install -y postgresql
```
=== "CentOS"
```no-highlight
sudo yum install -y postgresql-server
sudo postgresql-setup --initdb
```
CentOS configures ident host-based authentication for PostgreSQL by default. Because NetBox will need to authenticate using a username and password, modify `/var/lib/pgsql/data/pg_hba.conf` to support MD5 authentication by changing `ident` to `md5` for the lines below:
```no-highlight
host all all 127.0.0.1/32 md5
host all all ::1/128 md5
```
Once PostgreSQL has been installed, start the service and enable it to run at boot:
```no-highlight
sudo systemctl enable --now postgresql
```
Before continuing, verify that you have installed PostgreSQL 12 or later:
Before continuing, verify that you have installed PostgreSQL 14 or later:
```no-highlight
psql -V
@@ -62,6 +40,9 @@ GRANT CREATE ON SCHEMA public TO netbox;
!!! danger "Use a strong password"
**Do not use the password from the example.** Choose a strong, random password to ensure secure database authentication for your NetBox installation.
!!! danger "Use UTF8 encoding"
Make sure that your database uses `UTF8` encoding (the default for new installations). Especially do not use `SQL_ASCII` encoding, as it can lead to unpredictable and unrecoverable errors. Enter `\l` to check your encoding.
Once complete, enter `\q` to exit the PostgreSQL shell.
[Redis](https://redis.io/) is an in-memory key-value store which NetBox employs for caching and queuing. This section entails the installation and configuration of a local Redis instance. If you already have a Redis service in place, skip to [the next section](3-netbox.md).
=== "Ubuntu"
```no-highlight
sudo apt install -y redis-server
```
=== "CentOS"
```no-highlight
sudo yum install -y redis
sudo systemctl enable --now redis
```
```no-highlight
sudo apt install -y redis-server
```
Before continuing, verify that your installed version of Redis is at least v4.0:
Before continuing, check that your installed Python version is at least 3.10:
@@ -29,7 +23,7 @@ python3 -V
## Download NetBox
This documentation provides two options for installing NetBox: from a downloadable archive, or from the git repository. Installing from a package (option A below) requires manually fetching and extracting the archive for every future update, whereas installation via git (option B) allows for seamless upgrades by re-pulling the `master` branch.
This documentation provides two options for installing NetBox: from a downloadable archive, or from the git repository. Installing from a package (option A below) requires manually fetching and extracting the archive for every future update, whereas installation via git (option B) allows for seamless upgrades by checking out the latest release tag.
### Option A: Download a Release Archive
@@ -55,28 +49,17 @@ cd /opt/netbox/
If `git` is not already installed, install it:
=== "Ubuntu"
```no-highlight
sudo apt install -y git
```
=== "CentOS"
```no-highlight
sudo yum install -y git
```
Next, clone the **master** branch of the NetBox GitHub repository into the current directory. (This branch always holds the current stable release.)
The `git clone` command above utilizes a "shallow clone" to retrieve only the most recent commit. If you need to download the entire history, omit the `--depth 1` argument.
Next, clone the git repository:
The `git clone` command should generate output similar to the following:
Installation via git also allows you to easily try out different versions of NetBox. To check out a [specific NetBox release](https://github.com/netbox-community/netbox/releases), use the `git checkout` command with the desired release tag. For example, `git checkout v3.0.8`.
Finally, check out the tag for the desired release. You can find these on our [releases page](https://github.com/netbox-community/netbox/releases). Replace `vX.Y.Z` with your selected release tag below.
```
sudo git checkout vX.Y.Z
```
Using this installation method enables easy upgrades in the future by simply checking out the latest release tag.
## Create the NetBox System User
Create a system user account named `netbox`. We'll configure the WSGI and HTTP services to run under this account. We'll also assign this user ownership of the media directory. This ensures that NetBox will be able to save uploaded files.
Open `configuration.py` with your preferred editor to begin configuring NetBox. NetBox offers [many configuration parameters](../configuration/index.md), but only the following four are required for new installations:
* `ALLOWED_HOSTS`
* `DATABASE`
* `DATABASES` (or `DATABASE`)
* `REDIS`
* `SECRET_KEY`
### ALLOWED_HOSTS
This is a list of the valid hostnames and IP addresses by which this server can be reached. You must specify at least one name or IP address. (Note that this does not restrict the locations from which NetBox may be accessed: It is merely for [HTTP host header validation](https://docs.djangoproject.com/en/3.0/topics/security/#host-headers-virtual-hosting).)
This is a list of the valid hostnames and IP addresses by which this server can be reached. You must specify at least one name or IP address. (Note that this does not restrict the locations from which NetBox may be accessed: It is merely for [HTTP host header validation](https://docs.djangoproject.com/en/stable/topics/security/#host-headers-virtual-hosting).)
@@ -144,18 +120,22 @@ If you are not yet sure what the domain name and/or IP address of the NetBox ins
ALLOWED_HOSTS = ['*']
```
### DATABASE
### DATABASES
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.
This parameter holds the PostgreSQL database configuration details. The default database must be defined; additional databases may be defined as needed e.g. by plugins.
A username and password must be defined for the default database. If the service is running on a remote host, update the `HOST` and `PORT` parameters accordingly. See the [configuration documentation](../configuration/required-parameters.md#databases) for more detail on individual parameters.
'PORT': '', # Database port (leave blank for default)
'CONN_MAX_AGE': 300, # Max database connection age (seconds)
}
}
```
@@ -205,7 +185,7 @@ All Python packages required by NetBox are listed in `requirements.txt` and will
### 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/system.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#storages) in `configuration.py`.
```no-highlight
sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt"
@@ -244,7 +224,7 @@ Once NetBox has been configured, we're ready to proceed with the actual installa
* Create a Python virtual environment
* Installs all required Python packages
* Run database schema migrations
* Run database schema migrations (skip with `--readonly`)
* Builds the documentation locally (for offline use)
Upon completion, the upgrade script may warn that no existing virtual environment was detected. As this is a new installation, this warning can be safely ignored.
!!! note
To run the script on a node connected to a database in read-only mode, include the `--readonly` parameter. This will skip the application of any database migrations.
## Create a Super User
NetBox does not come with any predefined user accounts. You'll need to create a super user (administrative account) to be able to log into NetBox. First, enter the Python virtual environment created by the upgrade script:
@@ -281,18 +264,6 @@ cd /opt/netbox/netbox
python3 manage.py createsuperuser
```
## Schedule the Housekeeping Task
NetBox includes a `housekeeping` management command that handles some recurring cleanup tasks, such as clearing out old sessions and expired change records. Although this command may be run manually, it is recommended to configure a scheduled job using the system's `cron` daemon or a similar utility.
A shell script which invokes this command is included at `contrib/netbox-housekeeping.sh`. It can be copied to or linked from your system's daily cron task directory, or included within the crontab directly. (If installing NetBox into a nonstandard path, be sure to update the system paths within this script first.)
See the [housekeeping documentation](../administration/housekeeping.md) for further details.
## Test the Application
At this point, we should be able to run NetBox's development server for testing. We can check by starting a development instance locally.
@@ -319,13 +290,6 @@ Quit the server with CONTROL-C.
Next, connect to the name or IP of the server (as defined in `ALLOWED_HOSTS`) on port 8000; for example, <http://127.0.0.1:8000/>. You should be greeted with the NetBox home page. Try logging in using the username and password specified when creating a superuser.
!!! note
By default RHEL based distros will likely block your testing attempts with firewalld. The development server port can be opened with `firewall-cmd` (add `--permanent` if you want the rule to survive server restarts):
```no-highlight
firewall-cmd --zone=public --add-port=8000/tcp
```
!!! danger "Not for production use"
The development server is for development and testing purposes only. It is neither performant nor secure enough for production use. **Do not use it in production.**
While the provided configuration should suffice for most initial installations, you may wish to edit this file to change the bound IP address and/or port number, or to make performance-related adjustments. See [the uWSGI documentation](https://uwsgi-docs-additions.readthedocs.io/en/latest/Options.html) for the available configuration parameters and take a minute to review the [Things to know](https://uwsgi-docs.readthedocs.io/en/latest/ThingsToKnow.html) page. Django also provides [additional documentation](https://docs.djangoproject.com/en/5.0/howto/deployment/wsgi/uwsgi/) on configuring uWSGI with a Django app.
While the provided configuration should suffice for most initial installations, you may wish to edit this file to change the bound IP address and/or port number, or to make performance-related adjustments. See [the uWSGI documentation](https://uwsgi-docs-additions.readthedocs.io/en/latest/Options.html) for the available configuration parameters and take a minute to review the [Things to know](https://uwsgi-docs.readthedocs.io/en/latest/ThingsToKnow.html) page. Django also provides [additional documentation](https://docs.djangoproject.com/en/stable/howto/deployment/wsgi/uwsgi/) on configuring uWSGI with a Django app.
The instructions below are for installing NetBox as a standalone, self-hosted application. For a Cloud-delivered solution, check out [NetBox Cloud](https://netboxlabs.com/netbox-cloud/) by NetBox Labs.
<div class="grid cards" markdown>
The installation instructions provided here have been tested to work on Ubuntu 22.04 and CentOS 8.3. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.
- :material-clock-fast:{ .lg .middle } __Eager to Get Started?__
Check out the [NetBox Cloud Free Plan](https://netboxlabs.com/free-netbox-cloud/)! Skip the installation process and grab your own NetBox Cloud instance, preconfigured and ready to go in minutes. Completely free!
The installation instructions provided here have been tested to work on Ubuntu 22.04. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.
The following sections detail how to set up a new instance of NetBox:
@@ -21,7 +28,7 @@ The following sections detail how to set up a new instance of NetBox:
| Dependency | Supported Versions |
|------------|--------------------|
| Python | 3.10, 3.11, 3.12 |
| PostgreSQL | 12+ |
| PostgreSQL | 14+ |
| Redis | 4.0+ |
Below is a simplified overview of the NetBox application stack for reference:
As with the initial installation, you can upgrade NetBox by either downloading the latest release package or by cloning the `master` branch of the git repository.
As with the initial installation, you can upgrade NetBox by either downloading the latest release package or by checking out the latest production release from the git repository.
!!! warning
Use the same method as you used to install NetBox originally
Use the same method as you used to install NetBox originally.
If you are not sure how NetBox was installed originally, check with this command:
@@ -36,10 +54,7 @@ If you are not sure how NetBox was installed originally, check with this command
ls -ld /opt/netbox /opt/netbox/.git
```
If NetBox was installed from a release package, then `/opt/netbox` will be a
symlink pointing to the current version, and `/opt/netbox/.git` will not
exist. If it was installed from git, then `/opt/netbox` and
`/opt/netbox/.git` will both exist as normal directories.
If NetBox was installed from a release package, then `/opt/netbox` will be a symlink pointing to the current version, and `/opt/netbox/.git` will not exist. If it was installed from git, then `/opt/netbox` and `/opt/netbox/.git` will both exist as normal directories.
### Option A: Download a Release
@@ -84,20 +99,24 @@ If you followed the original installation guide to set up gunicorn, be sure to c
This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most recent iteration of the master branch:
This guide assumes that NetBox is installed in `/opt/netbox`. First, determine the latest release either by visiting our [releases page](https://github.com/netbox-community/netbox/releases) or by running the following command:
If you need to upgrade to an older version rather than the current stable release, you can check out any valid [git tag](https://github.com/netbox-community/netbox/tags), each of which represents a release. For example, to checkout the code for NetBox v2.11.11, do:
Check out the desired release by specifying its tag. For example:
sudo git checkout v2.11.11
```
cd /opt/netbox && \
sudo git fetch --tags && \
sudo git checkout v4.2.7
```
## 4. Run the Upgrade Script
@@ -114,6 +133,9 @@ sudo ./upgrade.sh
sudo PYTHON=/usr/bin/python3.10 ./upgrade.sh
```
!!! note
To run the script on a node connected to a database in read-only mode, include the `--readonly` parameter. This will skip the application of any database migrations.
This script performs the following actions:
* Destroys and rebuilds the Python virtual environment
@@ -140,13 +162,3 @@ Finally, restart the gunicorn and RQ services:
```no-highlight
sudo systemctl restart netbox netbox-rq
```
## 6. Verify Housekeeping Scheduling
If upgrading from a release prior to NetBox v3.0, check that a cron task (or similar scheduled process) has been configured to run NetBox's nightly housekeeping command. A shell script which invokes this command is included at `contrib/netbox-housekeeping.sh`. It can be linked from your system's daily cron task directory, or included within the crontab directly. (If NetBox has been installed in a nonstandard path, be sure to update the system paths within this script first.)
NetBox provides a read-only [GraphQL](https://graphql.org/) API to complement its REST API. This API is powered by [Strawberry Django](https://strawberry-graphql.github.io/strawberry-django/).
NetBox provides a read-only [GraphQL](https://graphql.org/) API to complement its REST API. This API is powered by [Strawberry Django](https://strawberry.rocks/).
The response will include the requested data formatted as JSON:
@@ -47,23 +47,52 @@ NetBox provides both a singular and plural query field for each object type:
For example, query `device(id:123)` to fetch a specific device (identified by its unique ID), and query `device_list` (with an optional set of filters) to fetch all devices.
For more detail on constructing GraphQL queries, see the [GraphQL queries documentation](https://graphql.org/learn/queries/). For filtering and lookup syntax, please refer to the [Strawberry Django documentation](https://strawberry-graphql.github.io/strawberry-django/guide/filters/).
For more detail on constructing GraphQL queries, see the [GraphQL queries documentation](https://graphql.org/learn/queries/). For filtering and lookup syntax, please refer to the [Strawberry Django documentation](https://strawberry.rocks/docs/django/guide/filters).
## Filtering
The GraphQL API employs the same filtering logic as the UI and REST API. Filters can be specified as key-value pairs within parentheses immediately following the query name. For example, the following will return only sites within the North Carolina region with a status of active:
!!! note "Changed in NetBox v4.3"
The filtering syntax fo the GraphQL API has changed substantially in NetBox v4.3.
Filters can be specified as key-value pairs within parentheses immediately following the query name. For example, the following will return only active sites:
In addition, filtering can be done on list of related objects as shown in the following query:
Filters can be combined with logical operators, such as `OR` and `NOT`. For example, the following will return every site that is planned _or_ assigned to a tenant named Foo:
```
{
query {
site_list(
filters: {
status: STATUS_PLANNED,
OR: {
tenant: {
name: {
exact: "Foo"
}
}
}
}
) {
name
}
}
```
Filtering can also be applied to related objects. For example, the following query will return only enabled interfaces for each device:
```
query {
device_list {
id
name
@@ -98,9 +127,21 @@ Certain queries can return multiple types of objects, for example cable terminat
}
}
}
```
The field "class_type" is an easy way to distinguish what type of object it is when viewing the returned data, or when filtering. It contains the class name, for example "CircuitTermination" or "ConsoleServerPort".
## Pagination
Queries can be paginated by specifying pagination in the query and supplying an offset and optionaly a limit in the query. If no limit is given, a default of 100 is used. Queries are not paginated unless requested in the query. An example paginated query is shown below:
```
The field "class_type" is an easy way to distinguish what type of object it is when viewing the returned data, or when filtering. It contains the class name, for example "CircuitTermination" or "ConsoleServerPort".
REST stands for [representational state transfer](https://en.wikipedia.org/wiki/Representational_state_transfer). It's a particular type of API which employs HTTP requests and [JavaScript Object Notation (JSON)](https://www.json.org/) to facilitate create, retrieve, update, and delete (CRUD) operations on objects within an application. Each type of operation is associated with a particular HTTP verb:
REST stands for [representational state transfer](https://en.wikipedia.org/wiki/REST). It's a particular type of API which employs HTTP requests and [JavaScript Object Notation (JSON)](https://www.json.org/) to facilitate create, retrieve, update, and delete (CRUD) operations on objects within an application. Each type of operation is associated with a particular HTTP verb:
*`GET`: Retrieve an object or list of objects
*`POST`: Create an object
@@ -217,26 +217,34 @@ If we wanted to assign this IP address to a virtual machine interface instead, w
### Brief Format
Most API endpoints support an optional "brief" format, which returns only a minimal representation of each object in the response. This is useful when you need only a list of available objects without any related data, such as when populating a drop-down list in a form. As an example, the default (complete) format of an IP address looks like this:
Most API endpoints support an optional "brief" format, which returns only a minimal representation of each object in the response. This is useful when you need only a list of available objects without any related data, such as when populating a drop-down list in a form. As an example, the default (complete) format of a prefix looks like this:
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.
## Changelog Messages
!!! info "This feature was introduced in NetBox v4.4."
Most objects in NetBox support [change logging](../features/change-logging.md), which generates a detailed record each time an object is created, modified, or deleted. Beginning in NetBox v4.4, users can attach a message to the change record as well. This is accomplished via the REST API by including a `changelog_message` field in the object representation.
For example, the following API request will create a new site and record a message in the resulting changelog entry:
```no-highlight
curl -s -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/dcim/sites/ \
--data '{
"name": "Site A",
"slug": "site-a",
"changelog_message": "Adding a site for ticket #4137"
}'
```
This approach works when creating, modifying, or deleting objects, either individually or in bulk.
## Uploading Files
As JSON does not support the inclusion of binary data, files cannot be uploaded using JSON-formatted API requests. Instead, we can use form data encoding to attach a local file.
For example, we can upload an image attachment using the `curl` command shown below. Note that the `@` signifies a local file on disk to be uploaded.
```no-highlight
curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
-F "object_type=dcim.site" \
-F "object_id=2" \
-F "name=attachment1.png" \
-F "image=@local_file.png" \
http://netbox/api/extras/image-attachments/
```
## Authentication
The NetBox REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browsable API.
@@ -653,6 +732,7 @@ Note that we are _not_ passing an existing REST API token with this request. If
@@ -36,6 +36,10 @@ The operational status of the circuit. By default, the following statuses are av
!!! 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.
### Distance
The distance between the circuit's two endpoints, including a unit designation (e.g. 100 meters or 25 feet).
@@ -21,13 +21,11 @@ Designates the termination as forming either the A or Z end of the circuit.
If selected, the circuit termination will be considered "connected" even if no cable has been connected to it in NetBox.
### Site
### Termination
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).
!!! info "This field replaced the `site` and `provider_network` fields in NetBox v4.2."
### 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).
The [region](../dcim/region.md), [site group](../dcim/sitegroup.md), [site](../dcim/site.md), [location](../dcim/location.md) or [provider network](./providernetwork.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).
A virtual circuit can connect two or more interfaces atop a set of decoupled physical connections. For example, it's very common to form a virtual connection between two virtual interfaces, each of which is bound to a physical interface on its respective device and physically connected to a [provider network](./providernetwork.md) via an independent [physical circuit](./circuit.md).
## Fields
### Provider Network
The [provider network](./providernetwork.md) across which the virtual circuit is formed.
### Provider Account
The [provider account](./provideraccount.md) with which the virtual circuit is associated (if any).
### Circuit ID
The unique identifier assigned to the virtual circuit by its [provider](./provider.md).
### Type
The assigned [virtual circuit type](./virtualcircuittype.md).
### Status
The operational status of the virtual 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.
This model represents the connection of a virtual [interface](../dcim/interface.md) to a [virtual circuit](./virtualcircuit.md).
## Fields
### Virtual Circuit
The [virtual circuit](./virtualcircuit.md) to which the interface is connected.
### Interface
The [interface](../dcim/interface.md) connected to the virtual circuit.
### Role
The functional role of the termination. This depends on the virtual circuit's topology, which is typically either peer-to-peer or hub-and-spoke (multipoint). Valid choices include:
Like physical [circuits](./circuit.md), [virtual circuits](./virtualcircuit.md) are classified by functional type. These types are completely customizable, and can help categorize circuits by function or technology.
## Fields
### Name
A unique human-friendly name.
### Slug
A unique URL-friendly identifier. (This value can be used for filtering.)
@@ -45,9 +45,12 @@ The operation duplex (full, half, or auto).
The [virtual routing and forwarding](../ipam/vrf.md) instance to which this interface is assigned.
### MAC Address
### Primary MAC Address
The 48-bit MAC address (for Ethernet interfaces).
The [MAC address](./macaddress.md) assigned to this interface which is designated as its primary.
!!! note "Changed in NetBox v4.2"
The MAC address of an interface (formerly a concrete database field) is available as a property, `mac_address`, which reflects the value of the primary linked [MAC address](./macaddress.md) object.
### WWN
@@ -109,6 +112,7 @@ For switched Ethernet interfaces, this identifies the 802.1Q encapsulation strat
* **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.
* **Q-in-Q:** Q-in-Q (IEEE 802.1ad) encapsulation is performed using the assigned SVLAN.
This field must be left blank for routed interfaces which do employ 802.1Q encapsulation.
@@ -120,6 +124,10 @@ The "native" (untagged) VLAN for the interface. Valid only when one of the above
The tagged VLANs which are configured to be carried by this interface. Valid only for the "tagged" 802.1Q mode above.
### Q-in-Q SVLAN
The assigned service VLAN (for Q-in-Q/802.1ad interfaces).
### Wireless Role
Indicates the configured role for wireless interfaces (access point or station).
@@ -142,3 +150,7 @@ The configured channel width of a wireless interface, in MHz. This is typically
### Wireless LANs
The [wireless LANs](../wireless/wirelesslan.md) for which this interface carries traffic. (Valid for wireless interfaces only.)
### VLAN Translation Policy
The [VLAN translation policy](../ipam/vlantranslationpolicy.md) that applies to this interface (optional).
Beginning in NetBox v4.3, the use of inventory items has been deprecated. They are planned for removal in a future NetBox release. Users are strongly encouraged to begin using [modules](./module.md) and [module types](./moduletype.md) in place of inventory items. Modules provide enhanced functionality and can be configured with user-defined attributes.
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.
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.
@@ -25,6 +28,10 @@ The inventory item's name. If the inventory item is assigned to a parent item, i
An alternative physical label identifying the inventory item.
### Status
The inventory item's operational status.
### Role
The functional [role](./inventoryitemrole.md) assigned to this inventory item.
Beginning in NetBox v4.3, the use of inventory items has been deprecated. They are planned for removal in a future NetBox release. Users are strongly encouraged to begin using [modules](./module.md) and [module types](./moduletype.md) in place of inventory items. Modules provide enhanced functionality and can be configured with user-defined attributes.
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.
Beginning in NetBox v4.3, the use of inventory items has been deprecated. They are planned for removal in a future NetBox release. Users are strongly encouraged to begin using [modules](./module.md) and [module types](./moduletype.md) in place of inventory items. Modules provide enhanced functionality and can be configured with user-defined attributes.
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.
A MAC address object in NetBox comprises a single Ethernet link layer address, and represents a MAC address as reported by or assigned to a network interface. MAC addresses can be assigned to [device](../dcim/device.md) and [virtual machine](../virtualization/virtualmachine.md) interfaces. A MAC address can be specified as the primary MAC address for a given device or VM interface.
Most interfaces have only a single MAC address, hard-coded at the factory. However, on some devices (particularly virtual interfaces) it is possible to assign additional MAC addresses or change existing ones. For this reason NetBox allows multiple MACAddress objects to be assigned to a single interface.
## Fields
### MAC Address
The 48-bit MAC address, in colon-hexadecimal notation (e.g. `aa:bb:cc:11:22:33`).
@@ -42,6 +42,12 @@ The numeric weight of the module, including a unit designation (e.g. 3 kilograms
### Airflow
!!! info "The `airflow` field was introduced in NetBox v4.1."
The direction in which air circulates through the device chassis for cooling.
### Profile
The assigned [profile](./moduletypeprofile.md) for the type of module. Profiles can be used to classify module types by function (e.g. power supply, hard disk, etc.), and they support the addition of user-configurable attributes on module types. The assignment of a module type to a profile is optional.
### Attributes
Depending on the module type's assigned [profile](./moduletypeprofile.md) (if any), one or more user-defined attributes may be available to configure.
Each [module type](./moduletype.md) may optionally be assigned a profile according to its classification. A profile can extend module types with user-configured attributes. For example, you might want to specify the input current and voltage of a power supply, or the clock speed and number of cores for a processor.
Module type attributes are managed via the configuration of a [JSON schema](https://json-schema.org/) on the profile. For example, the following schema introduces three module type attributes, two of which are designated as required attributes.
```json
{
"properties":{
"type":{
"type":"string",
"title":"Disk type",
"enum":["HD","SSD","NVME"],
"default":"HD"
},
"capacity":{
"type":"integer",
"title":"Capacity (GB)",
"description":"Gross disk size"
},
"speed":{
"type":"integer",
"title":"Speed (RPM)"
}
},
"required":[
"type","capacity"
]
}
```
The assignment of module types to a profile is optional. The designation of a schema for a profile is also optional: A profile can be used simply as a mechanism for classifying module types if the addition of custom attributes is not needed.
## Fields
### Schema
This field holds the [JSON schema](https://json-schema.org/) for the profile. The configured JSON schema must be valid (or the field must be null).
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 be nested under parents to form a hierarchy. For example, platforms named "Debian" and "RHEL" might both be created under a generic "Linux" parent.
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 assignment of platforms to devices is an optional feature, and may be disregarded if not desired.
The assignment of platforms to devices and virtual machines is optional.
## Fields
## Parent
!!! "This field was introduced in NetBox v4.4."
The parent platform class to which this platform belongs (optional).
### Name
A unique human-friendly name.
A human-friendly name for the platform. Must be unique per manufacturer.
### Slug
A unique URL-friendly identifier. (This value can be used for filtering.)
A URL-friendly identifier; must be unique per manufacturer. (This value can be used for filtering.)
@@ -29,6 +29,21 @@ An alternative physical label identifying the power outlet.
The type of power outlet.
### Status
The operational status of the power outlet. By default, the following statuses are available:
* Enabled
* Disabled
* Faulty
!!! tip "Custom power outlet statuses"
Additional power outlet statuses may be defined by setting `PowerOutlet.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter.
### Color
The power outlet's color (optional).
### 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.
@@ -12,6 +12,13 @@ The [rack](./rack.md) being reserved.
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.
### Status
The current status of the reservation. (This is for documentation only: The status of a reservation has no impact on the installation of devices within a reserved rack unit.)
!!! tip
Additional statuses may be defined by setting `RackReservation.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter.
### User
The NetBox user account associated with the reservation. Note that users with sufficient permission can make rack reservations for other users.
!!! info "This feature was introduced in NetBox v4.1."
A rack type defines the physical characteristics of a particular model of [rack](./rack.md).
## Fields
@@ -42,7 +40,7 @@ The number of the numerically lowest unit in the rack. This value defaults to on
### 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.
The external width, height and depth of the rack can be tracked to aid in floorplan calculations. These measurements must be designated in either millimeters or inches.
A branch is a collection of related [staged changes](./stagedchange.md) that have been prepared for merging into the active database. A branch can be merged by executing its `commit()` method. Deleting a branch will delete all its related changes.
Profiles can be used to organize [configuration contexts](./configcontext.md) and to enforce a desired structure for their data. The later is achieved by defining a [JSON schema](https://json-schema.org/) to which all config context with this profile assigned must comply.
For example, the following schema defines two keys, `size` and `priority`, of which the former is required:
```json
{
"properties":{
"size":{
"type":"integer"
},
"priority":{
"type":"string",
"enum":["high","medium","low"],
"default":"medium"
}
},
"required":[
"size"
]
}
```
## Fields
### Name
A unique human-friendly name.
### Schema
The JSON schema to be enforced for all assigned config contexts (optional).
@@ -12,10 +12,6 @@ See the [configuration rendering documentation](../../features/configuration-ren
A unique human-friendly name.
### Weight
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.
### Data File
Template code may optionally be sourced from a remote [data file](../core/datafile.md), which is synchronized from a remote data source. When designating a data file, there is no need to specify template code: It will be populated automatically from the data file.
@@ -27,3 +23,26 @@ Jinja2 template code, if being defined locally rather than replicated from a dat
### Environment Parameters
A dictionary of any additional parameters to pass when instantiating the [Jinja2 environment](https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment). Jinja2 supports various optional parameters which can be used to modify its default behavior.
The `undefined` and `finalize` Jinja environment parameters, which must reference a Python class or function, can define a dotted path to the desired resource. For example:
```json
{
"undefined":"jinja2.StrictUndefined"
}
```
### MIME Type
The MIME type to indicate in the response when rendering the configuration template (optional). Defaults to `text/plain`.
### File Name
The file name to give to the rendered export file (optional).
### File Extension
The file extension to append to the file name in the response (optional).
### As Attachment
If selected, the rendered content will be returned as a file attachment, rather than displayed directly in-browser (where supported).
@@ -44,8 +44,6 @@ For object and multiple-object fields only. Designates the type of NetBox object
### Related Object Filter
!!! info "This field was introduced in NetBox v4.1."
For object and multi-object custom fields, a filter may be defined to limit the available objects when populating a field value. This filter maps object attributes to values. For example, `{"status": "active"}` will include only objects with a status of "active."
@@ -10,7 +10,7 @@ See the [event rules documentation](../../features/event-rules.md) for more inf
A unique human-friendly name.
### Content Types
### Object Types
The type(s) of object in NetBox that will trigger the rule.
@@ -38,3 +38,15 @@ The event types which will trigger the rule. At least one event type must be sel
### Conditions
A set of [prescribed conditions](../../reference/conditions.md) against which the triggering object will be evaluated. If the conditions are defined but not met by the object, no action will be taken. An event rule that does not define any conditions will _always_ trigger.
### Action Type
The type of action to take when the rule triggers. This must be one of the following choices:
* Webhook
* Custom script
* Notification
### Action Data
An optional dictionary of JSON data to pass when executing the rule. This can be useful to include additional context data, e.g. when transmitting a webhook.
@@ -20,10 +20,26 @@ Template code may optionally be sourced from a remote [data file](../core/datafi
Jinja2 template code for rendering the exported data.
### Environment Parameters
A dictionary of any additional parameters to pass when instantiating the [Jinja2 environment](https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment). Jinja2 supports various optional parameters which can be used to modify its default behavior.
The `undefined` and `finalize` Jinja environment parameters, which must reference a Python class or function, can define a dotted path to the desired resource. For example:
```json
{
"undefined":"jinja2.StrictUndefined"
}
```
### MIME Type
The MIME type to indicate in the response when rendering the export template (optional). Defaults to `text/plain`.
### File Name
The file name to give to the rendered export file (optional).
### File Extension
The file extension to append to the file name in the response (optional).
A staged change represents the creation of a new object or the modification or deletion of an existing object to be performed at some future point. Each change must be assigned to a [branch](./branch.md).
Changes can be applied individually via the `apply()` method, however it is recommended to apply changes in bulk using the parent branch's `commit()` method.
## Fields
!!! warning
Staged changes are not typically created or manipulated directly, but rather effected through the use of the [`checkout()`](../../plugins/development/staged-changes.md) context manager.
### Branch
The [branch](./branch.md) to which this change belongs.
### Action
The type of action this change represents: `create`, `update`, or `delete`.
### Object
A generic foreign key referencing the existing object to which this change applies.
### Data
JSON representation of the changes being made to the object (not applicable for deletions).
This object represents the saved configuration of an object table in NetBox. Table configs can be crafted, saved, and shared among users to apply specific views within object lists. Each table config can specify which table columns to display, the order in which to display them, and which columns are used for sorting.
For example, you might wish to create a table config for the devices list to assist in inventory tasks. This view might show the device name, location, serial number, and asset tag, but omit operational details like IP addresses. Once applied, this table config can be saved for reuse in future audits.
## Fields
### Name
A human-friendly name for the table config.
### User
The user to which this filter belongs. The current user will be assigned automatically when saving a table config via the UI, and cannot be changed.
### Object Type
The type of NetBox object to which the table config pertains.
### Table
The name of the specific table to which the table config pertains. (Some NetBox object use multiple tables.)
### Weight
A numeric weight used to influence the order in which table configs are listed. Table configs with a lower weight will be listed before those with a higher weight. Table configs having the same weight will be ordered alphabetically.
### Enabled
Determines whether this table config can be used. Disabled table configs will not appear as options in the UI, however they will be included in API results.
### Shared
Determines whether this table config is intended for use by all users or only its owner. Note that deselecting this option does **not** hide the table config from other users; it is merely excluded from the list of available table configs in UI object list views.
### Ordering
A list of column names by which the table is to be ordered. If left blank, the table's default ordering will be used.
### Columns
A list of columns to be displayed in the table. The table will render these columns in the order they appear in the list. At least one column must be selected.
@@ -16,6 +16,10 @@ A unique URL-friendly identifier. (This value will be used for filtering.) This
The color to use when displaying the tag in the NetBox UI.
### Weight
A numeric weight employed to influence the ordering of tags. Tags with a lower weight will be listed before those with higher weights. Values must be within the range **0** to **32767**.
### Object Types
The assignment of a tag may be limited to a prescribed set of objects. For example, it may be desirable to limit the application of a specific tag to only devices and virtual machines.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
