From 03535ce50b7063414dea71f753305d27506a646a Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 8 Apr 2022 16:00:33 -0400 Subject: [PATCH 001/245] Closes #8995: Enable arbitrary ordering of REST API results --- docs/release-notes/version-3.3.md | 7 ++++ docs/rest-api/filtering.md | 20 +++++++++++ netbox/netbox/settings.py | 3 +- netbox/utilities/tests/test_api.py | 58 ++++++++++++++++++++++++++++++ 4 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 docs/release-notes/version-3.3.md diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md new file mode 100644 index 000000000..de59d0327 --- /dev/null +++ b/docs/release-notes/version-3.3.md @@ -0,0 +1,7 @@ +# NetBox v3.3 + +## v3.3.0 (FUTURE) + +### Enhancements + +* [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results diff --git a/docs/rest-api/filtering.md b/docs/rest-api/filtering.md index 45dfcfa36..7ddda6f3c 100644 --- a/docs/rest-api/filtering.md +++ b/docs/rest-api/filtering.md @@ -106,3 +106,23 @@ expression: `n`. Here is an example of a lookup expression on a foreign key, it ```no-highlight GET /api/ipam/vlans/?group_id__n=3203 ``` + +## Ordering Objects + +To order results by a particular field, include the `ordering` query parameter. For example, order the list of sites according to their facility values: + +```no-highlight +GET /api/dcim/sites/?ordering=facility +``` + +To invert the ordering, prepend a hyphen to the field name: + +```no-highlight +GET /api/dcim/sites/?ordering=-facility +``` + +Multiple fields can be specified by separating the field names with a comma. For example: + +```no-highlight +GET /api/dcim/sites/?ordering=facility,-name +``` diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index 04c0e9c3d..0db41373f 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -26,7 +26,7 @@ django.utils.encoding.force_text = force_str # Environment setup # -VERSION = '3.2.1-dev' +VERSION = '3.3.0-dev' # Hostname HOSTNAME = platform.node() @@ -469,6 +469,7 @@ REST_FRAMEWORK = { ), 'DEFAULT_FILTER_BACKENDS': ( 'django_filters.rest_framework.DjangoFilterBackend', + 'rest_framework.filters.OrderingFilter', ), 'DEFAULT_METADATA_CLASS': 'netbox.api.metadata.BulkOperationMetadata', 'DEFAULT_PAGINATION_CLASS': 'netbox.api.pagination.OptionalLimitOffsetPagination', diff --git a/netbox/utilities/tests/test_api.py b/netbox/utilities/tests/test_api.py index 1171bd496..e341442be 100644 --- a/netbox/utilities/tests/test_api.py +++ b/netbox/utilities/tests/test_api.py @@ -176,6 +176,64 @@ class APIPaginationTestCase(APITestCase): self.assertEqual(len(response.data['results']), 100) +class APIOrderingTestCase(APITestCase): + user_permissions = ('dcim.view_site',) + + @classmethod + def setUpTestData(cls): + cls.url = reverse('dcim-api:site-list') + + sites = ( + Site(name='Site 1', slug='site-1', facility='C', description='Z'), + Site(name='Site 2', slug='site-2', facility='C', description='Y'), + Site(name='Site 3', slug='site-3', facility='B', description='X'), + Site(name='Site 4', slug='site-4', facility='B', description='W'), + Site(name='Site 5', slug='site-5', facility='A', description='V'), + Site(name='Site 6', slug='site-6', facility='A', description='U'), + ) + Site.objects.bulk_create(sites) + + def test_default_order(self): + response = self.client.get(self.url, format='json', **self.header) + + self.assertHttpStatus(response, status.HTTP_200_OK) + self.assertEqual(response.data['count'], 6) + self.assertListEqual( + [s['name'] for s in response.data['results']], + ['Site 1', 'Site 2', 'Site 3', 'Site 4', 'Site 5', 'Site 6'] + ) + + def test_order_single_field(self): + response = self.client.get(f'{self.url}?ordering=description', format='json', **self.header) + + self.assertHttpStatus(response, status.HTTP_200_OK) + self.assertEqual(response.data['count'], 6) + self.assertListEqual( + [s['name'] for s in response.data['results']], + ['Site 6', 'Site 5', 'Site 4', 'Site 3', 'Site 2', 'Site 1'] + ) + + def test_order_reversed(self): + response = self.client.get(f'{self.url}?ordering=-name', format='json', **self.header) + + self.assertHttpStatus(response, status.HTTP_200_OK) + self.assertEqual(response.data['count'], 6) + self.assertListEqual( + [s['name'] for s in response.data['results']], + ['Site 6', 'Site 5', 'Site 4', 'Site 3', 'Site 2', 'Site 1'] + ) + + def test_order_multiple_fields(self): + response = self.client.get(f'{self.url}?ordering=facility,name', format='json', **self.header) + + self.assertHttpStatus(response, status.HTTP_200_OK) + self.assertEqual(response.data['count'], 6) + self.assertListEqual( + [s['name'] for s in response.data['results']], + ['Site 5', 'Site 6', 'Site 3', 'Site 4', 'Site 1', 'Site 2'] + ) + + class APIDocsTestCase(TestCase): def setUp(self): From 17df8a5c4394785cb2e176788e468bd508c5a169 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 15 Apr 2022 14:45:28 -0400 Subject: [PATCH 002/245] Closes #8495: Enable custom field grouping --- docs/release-notes/version-3.3.md | 6 ++ netbox/extras/api/serializers.py | 4 +- netbox/extras/filtersets.py | 3 +- netbox/extras/forms/bulk_edit.py | 5 +- netbox/extras/forms/bulk_import.py | 4 +- netbox/extras/forms/filtersets.py | 5 +- netbox/extras/forms/models.py | 4 +- .../migrations/0074_customfield_group_name.py | 22 +++++ netbox/extras/models/customfields.py | 7 +- netbox/extras/tables/tables.py | 4 +- netbox/netbox/models/features.py | 12 +++ netbox/templates/extras/customfield.html | 4 + .../templates/inc/panels/custom_fields.html | 95 ++++++++++--------- 13 files changed, 119 insertions(+), 56 deletions(-) create mode 100644 netbox/extras/migrations/0074_customfield_group_name.py diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index de59d0327..1dd19a5c0 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -4,4 +4,10 @@ ### Enhancements +* [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results + +### REST API Changes + +* extras.CustomField + * Added `group_name` field diff --git a/netbox/extras/api/serializers.py b/netbox/extras/api/serializers.py index e05d4083c..eed7f7603 100644 --- a/netbox/extras/api/serializers.py +++ b/netbox/extras/api/serializers.py @@ -88,8 +88,8 @@ class CustomFieldSerializer(ValidatedModelSerializer): class Meta: model = CustomField fields = [ - 'id', 'url', 'display', 'content_types', 'type', 'object_type', 'data_type', 'name', 'label', 'description', - 'required', 'filter_logic', 'default', 'weight', 'validation_minimum', 'validation_maximum', + 'id', 'url', 'display', 'content_types', 'type', 'object_type', 'data_type', 'name', 'label', 'group_name', + 'description', 'required', 'filter_logic', 'default', 'weight', 'validation_minimum', 'validation_maximum', 'validation_regex', 'choices', 'created', 'last_updated', ] diff --git a/netbox/extras/filtersets.py b/netbox/extras/filtersets.py index 25477fbda..467ae23af 100644 --- a/netbox/extras/filtersets.py +++ b/netbox/extras/filtersets.py @@ -62,7 +62,7 @@ class CustomFieldFilterSet(BaseFilterSet): class Meta: model = CustomField - fields = ['id', 'content_types', 'name', 'required', 'filter_logic', 'weight', 'description'] + fields = ['id', 'content_types', 'name', 'group_name', 'required', 'filter_logic', 'weight', 'description'] def search(self, queryset, name, value): if not value.strip(): @@ -70,6 +70,7 @@ class CustomFieldFilterSet(BaseFilterSet): return queryset.filter( Q(name__icontains=value) | Q(label__icontains=value) | + Q(group_name__icontains=value) | Q(description__icontains=value) ) diff --git a/netbox/extras/forms/bulk_edit.py b/netbox/extras/forms/bulk_edit.py index e16f8aeac..b722bd751 100644 --- a/netbox/extras/forms/bulk_edit.py +++ b/netbox/extras/forms/bulk_edit.py @@ -24,6 +24,9 @@ class CustomFieldBulkEditForm(BulkEditForm): queryset=CustomField.objects.all(), widget=forms.MultipleHiddenInput ) + group_name = forms.CharField( + required=False + ) description = forms.CharField( required=False ) @@ -35,7 +38,7 @@ class CustomFieldBulkEditForm(BulkEditForm): required=False ) - nullable_fields = ('description',) + nullable_fields = ('group_name', 'description',) class CustomLinkBulkEditForm(BulkEditForm): diff --git a/netbox/extras/forms/bulk_import.py b/netbox/extras/forms/bulk_import.py index fa6d8af55..dabf2f811 100644 --- a/netbox/extras/forms/bulk_import.py +++ b/netbox/extras/forms/bulk_import.py @@ -36,8 +36,8 @@ class CustomFieldCSVForm(CSVModelForm): class Meta: model = CustomField fields = ( - 'name', 'label', 'type', 'content_types', 'required', 'description', 'weight', 'filter_logic', 'default', - 'choices', 'weight', 'validation_minimum', 'validation_maximum', 'validation_regex', + 'name', 'label', 'group_name', 'type', 'content_types', 'required', 'description', 'weight', 'filter_logic', + 'default', 'choices', 'weight', 'validation_minimum', 'validation_maximum', 'validation_regex', ) diff --git a/netbox/extras/forms/filtersets.py b/netbox/extras/forms/filtersets.py index 5d66c8be8..1710ecb89 100644 --- a/netbox/extras/forms/filtersets.py +++ b/netbox/extras/forms/filtersets.py @@ -32,7 +32,7 @@ __all__ = ( class CustomFieldFilterForm(FilterForm): fieldsets = ( (None, ('q',)), - ('Attributes', ('type', 'content_types', 'weight', 'required')), + ('Attributes', ('content_types', 'type', 'group_name', 'weight', 'required')), ) content_types = ContentTypeMultipleChoiceField( queryset=ContentType.objects.all(), @@ -44,6 +44,9 @@ class CustomFieldFilterForm(FilterForm): required=False, label=_('Field type') ) + group_name = forms.CharField( + required=False + ) weight = forms.IntegerField( required=False ) diff --git a/netbox/extras/forms/models.py b/netbox/extras/forms/models.py index 112911f42..b07853f86 100644 --- a/netbox/extras/forms/models.py +++ b/netbox/extras/forms/models.py @@ -40,7 +40,9 @@ class CustomFieldForm(BootstrapMixin, forms.ModelForm): ) fieldsets = ( - ('Custom Field', ('content_types', 'name', 'label', 'type', 'object_type', 'weight', 'required', 'description')), + ('Custom Field', ( + 'content_types', 'name', 'label', 'group_name', 'type', 'object_type', 'weight', 'required', 'description', + )), ('Behavior', ('filter_logic',)), ('Values', ('default', 'choices')), ('Validation', ('validation_minimum', 'validation_maximum', 'validation_regex')), diff --git a/netbox/extras/migrations/0074_customfield_group_name.py b/netbox/extras/migrations/0074_customfield_group_name.py new file mode 100644 index 000000000..e1be76b1f --- /dev/null +++ b/netbox/extras/migrations/0074_customfield_group_name.py @@ -0,0 +1,22 @@ +# Generated by Django 4.0.4 on 2022-04-15 17:13 + +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('extras', '0073_journalentry_tags_custom_fields'), + ] + + operations = [ + migrations.AlterModelOptions( + name='customfield', + options={'ordering': ['group_name', 'weight', 'name']}, + ), + migrations.AddField( + model_name='customfield', + name='group_name', + field=models.CharField(blank=True, max_length=50), + ), + ] diff --git a/netbox/extras/models/customfields.py b/netbox/extras/models/customfields.py index 49afe1bba..55caa4a70 100644 --- a/netbox/extras/models/customfields.py +++ b/netbox/extras/models/customfields.py @@ -79,6 +79,11 @@ class CustomField(ExportTemplatesMixin, WebhooksMixin, ChangeLoggedModel): help_text='Name of the field as displayed to users (if not provided, ' 'the field\'s name will be used)' ) + group_name = models.CharField( + max_length=50, + blank=True, + help_text="Custom fields within the same group will be displayed together" + ) description = models.CharField( max_length=200, blank=True @@ -134,7 +139,7 @@ class CustomField(ExportTemplatesMixin, WebhooksMixin, ChangeLoggedModel): objects = CustomFieldManager() class Meta: - ordering = ['weight', 'name'] + ordering = ['group_name', 'weight', 'name'] def __str__(self): return self.label or self.name.replace('_', ' ').capitalize() diff --git a/netbox/extras/tables/tables.py b/netbox/extras/tables/tables.py index a13054d56..1a0f5d58a 100644 --- a/netbox/extras/tables/tables.py +++ b/netbox/extras/tables/tables.py @@ -32,10 +32,10 @@ class CustomFieldTable(NetBoxTable): class Meta(NetBoxTable.Meta): model = CustomField fields = ( - 'pk', 'id', 'name', 'content_types', 'label', 'type', 'required', 'weight', 'default', + 'pk', 'id', 'name', 'content_types', 'label', 'type', 'group_name', 'required', 'weight', 'default', 'description', 'filter_logic', 'choices', 'created', 'last_updated', ) - default_columns = ('pk', 'name', 'content_types', 'label', 'type', 'required', 'description') + default_columns = ('pk', 'name', 'content_types', 'label', 'group_name', 'type', 'required', 'description') # diff --git a/netbox/netbox/models/features.py b/netbox/netbox/models/features.py index e443dde5f..4bd1b0e9c 100644 --- a/netbox/netbox/models/features.py +++ b/netbox/netbox/models/features.py @@ -1,3 +1,5 @@ +from collections import defaultdict + from django.contrib.contenttypes.fields import GenericRelation from django.db.models.signals import class_prepared from django.dispatch import receiver @@ -117,6 +119,16 @@ class CustomFieldsMixin(models.Model): return data + def get_custom_fields_by_group(self): + """ + Return a dictionary of custom field/value mappings organized by group. + """ + grouped_custom_fields = defaultdict(dict) + for cf, value in self.get_custom_fields().items(): + grouped_custom_fields[cf.group_name][cf] = value + + return dict(grouped_custom_fields) + def clean(self): super().clean() from extras.models import CustomField diff --git a/netbox/templates/extras/customfield.html b/netbox/templates/extras/customfield.html index 9be7a485a..0d9856938 100644 --- a/netbox/templates/extras/customfield.html +++ b/netbox/templates/extras/customfield.html @@ -19,6 +19,10 @@ Label {{ object.label|placeholder }} + + Group Name + {{ object.group_name|placeholder }} + Type {{ object.get_type_display }} diff --git a/netbox/templates/inc/panels/custom_fields.html b/netbox/templates/inc/panels/custom_fields.html index 32e586d3a..b18d44030 100644 --- a/netbox/templates/inc/panels/custom_fields.html +++ b/netbox/templates/inc/panels/custom_fields.html @@ -1,49 +1,54 @@ {% load helpers %} -{% with custom_fields=object.get_custom_fields %} - {% if custom_fields %} -
-
Custom Fields
-
- - {% for field, value in custom_fields.items %} - - - - +{% with custom_fields=object.get_custom_fields_by_group %} + {% if custom_fields %} +
+
Custom Fields
+
+ {% for group_name, fields in custom_fields.items %} + {% if group_name %} +
{{ group_name }}
+ {% endif %} +
- {{ field }} - - {% if field.type == 'integer' and value is not None %} - {{ value }} - {% elif field.type == 'longtext' and value %} - {{ value|markdown }} - {% elif field.type == 'boolean' and value == True %} - {% checkmark value true="True" %} - {% elif field.type == 'boolean' and value == False %} - {% checkmark value false="False" %} - {% elif field.type == 'url' and value %} - {{ value|truncatechars:70 }} - {% elif field.type == 'json' and value %} - 
{{ value|json }}
- {% elif field.type == 'multiselect' and value %} - {{ value|join:", " }} - {% elif field.type == 'object' and value %} - {{ value|linkify }} - {% elif field.type == 'multiobject' and value %} - {% for obj in value %} - {{ obj|linkify }}{% if not forloop.last %}
{% endif %} - {% endfor %} - {% elif value %} - {{ value }} - {% elif field.required %} - Not defined - {% else %} - — - {% endif %} -
+ {% for field, value in fields.items %} + + +
+ {{ field }} + + {% if field.type == 'integer' and value is not None %} + {{ value }} + {% elif field.type == 'longtext' and value %} + {{ value|markdown }} + {% elif field.type == 'boolean' and value == True %} + {% checkmark value true="True" %} + {% elif field.type == 'boolean' and value == False %} + {% checkmark value false="False" %} + {% elif field.type == 'url' and value %} + {{ value|truncatechars:70 }} + {% elif field.type == 'json' and value %} + 
{{ value|json }}
+ {% elif field.type == 'multiselect' and value %} + {{ value|join:", " }} + {% elif field.type == 'object' and value %} + {{ value|linkify }} + {% elif field.type == 'multiobject' and value %} + {% for obj in value %} + {{ obj|linkify }}{% if not forloop.last %}
{% endif %} {% endfor %} -
-
-
- {% endif %} + {% elif value %} + {{ value }} + {% elif field.required %} + Not defined + {% else %} + {{ ''|placeholder }} + {% endif %} + + + {% endfor %} + + {% endfor %} + + + {% endif %} {% endwith %} From 25877202983182fd12a7b6a31dedca7edf5a589c Mon Sep 17 00:00:00 2001 From: Pieter Lambrecht Date: Tue, 19 Apr 2022 14:44:35 +0200 Subject: [PATCH 003/245] Fix 8878: Restrict API key usage by Source IP --- docs/release-notes/version-3.3.md | 1 + netbox/netbox/api/authentication.py | 26 ++++++++++++++++++ netbox/templates/users/api_tokens.html | 15 ++++++++--- netbox/users/admin/__init__.py | 6 ++++- netbox/users/admin/forms.py | 2 +- netbox/users/api/serializers.py | 2 +- netbox/users/forms.py | 10 ++++++- .../migrations/0003_token_allowed_ips.py | 20 ++++++++++++++ netbox/users/models.py | 27 +++++++++++++++++++ 9 files changed, 101 insertions(+), 8 deletions(-) create mode 100644 netbox/users/migrations/0003_token_allowed_ips.py diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 1dd19a5c0..09dcfcf22 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -6,6 +6,7 @@ * [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results +* [#8878](https://github.com/netbox-community/netbox/issues/8878) - Restrict API key usage by source IP ### REST API Changes diff --git a/netbox/netbox/api/authentication.py b/netbox/netbox/api/authentication.py index 5e177bfcb..2f86a1da2 100644 --- a/netbox/netbox/api/authentication.py +++ b/netbox/netbox/api/authentication.py @@ -1,4 +1,5 @@ from django.conf import settings +from django.core.exceptions import ValidationError from rest_framework import authentication, exceptions from rest_framework.permissions import BasePermission, DjangoObjectPermissions, SAFE_METHODS @@ -11,6 +12,31 @@ class TokenAuthentication(authentication.TokenAuthentication): """ model = Token + def authenticate(self, request): + authenticationresult = super().authenticate(request) + if authenticationresult: + token_user, token = authenticationresult + + # Verify source IP is allowed + if token.allowed_ips: + # Replace 'HTTP_X_REAL_IP' with the settings variable choosen in #8867 + if 'HTTP_X_REAL_IP' in request.META: + clientip = request.META['HTTP_X_REAL_IP'].split(",")[0].strip() + http_header = 'HTTP_X_REAL_IP' + elif 'REMOTE_ADDR' in request.META: + clientip = request.META['REMOTE_ADDR'] + http_header = 'REMOTE_ADDR' + else: + raise exceptions.AuthenticationFailed(f"A HTTP header containing the SourceIP (HTTP_X_REAL_IP, REMOTE_ADDR) is missing from the request.") + + try: + if not token.validate_client_ip(clientip): + raise exceptions.AuthenticationFailed(f"Source IP {clientip} is not allowed to use this token.") + except ValidationError as ValidationErrorInfo: + raise exceptions.ValidationError(f"The value in the HTTP Header {http_header} has a ValidationError: {ValidationErrorInfo.message}") + + return authenticationresult + def authenticate_credentials(self, key): model = self.get_model() try: diff --git a/netbox/templates/users/api_tokens.html b/netbox/templates/users/api_tokens.html index 01ffec23a..360e65a67 100644 --- a/netbox/templates/users/api_tokens.html +++ b/netbox/templates/users/api_tokens.html @@ -22,11 +22,11 @@
-
+
Created
{{ token.created|annotated_date }}
-
+
Expires
{% if token.expires %} {{ token.expires|annotated_date }} @@ -34,7 +34,7 @@ Never {% endif %}
-
+
Create/Edit/Delete Operations
{% if token.write_enabled %} Enabled @@ -42,7 +42,14 @@ Disabled {% endif %}
-
+
+ Allowed Source IPs
+ {% if token.allowed_ips %} + {{ token.allowed_ips|join:', ' }} + {% else %} + Any + {% endif %} +
{% if token.description %}
{{ token.description }} {% endif %} diff --git a/netbox/users/admin/__init__.py b/netbox/users/admin/__init__.py index 1b163ed06..ede26cd1b 100644 --- a/netbox/users/admin/__init__.py +++ b/netbox/users/admin/__init__.py @@ -58,9 +58,13 @@ class UserAdmin(UserAdmin_): class TokenAdmin(admin.ModelAdmin): form = forms.TokenAdminForm list_display = [ - 'key', 'user', 'created', 'expires', 'write_enabled', 'description' + 'key', 'user', 'created', 'expires', 'write_enabled', 'description', 'list_allowed_ips' ] + def list_allowed_ips(self, obj): + return obj.allowed_ips or 'Any' + list_allowed_ips.short_description = "Allowed IPs" + # # Permissions diff --git a/netbox/users/admin/forms.py b/netbox/users/admin/forms.py index 7d0212441..bc3d44862 100644 --- a/netbox/users/admin/forms.py +++ b/netbox/users/admin/forms.py @@ -51,7 +51,7 @@ class TokenAdminForm(forms.ModelForm): class Meta: fields = [ - 'user', 'key', 'write_enabled', 'expires', 'description' + 'user', 'key', 'write_enabled', 'expires', 'description', 'allowed_ips' ] model = Token diff --git a/netbox/users/api/serializers.py b/netbox/users/api/serializers.py index d490e8fe9..4b1f5bff3 100644 --- a/netbox/users/api/serializers.py +++ b/netbox/users/api/serializers.py @@ -62,7 +62,7 @@ class TokenSerializer(ValidatedModelSerializer): class Meta: model = Token - fields = ('id', 'url', 'display', 'user', 'created', 'expires', 'key', 'write_enabled', 'description') + fields = ('id', 'url', 'display', 'user', 'created', 'expires', 'key', 'write_enabled', 'description', 'allowed_ips') def to_internal_value(self, data): if 'key' not in data: diff --git a/netbox/users/forms.py b/netbox/users/forms.py index d5e6218e5..9720f92b7 100644 --- a/netbox/users/forms.py +++ b/netbox/users/forms.py @@ -1,7 +1,9 @@ from django import forms from django.contrib.auth.forms import AuthenticationForm, PasswordChangeForm as DjangoPasswordChangeForm +from django.contrib.postgres.forms import SimpleArrayField from django.utils.html import mark_safe +from ipam.formfields import IPNetworkFormField from netbox.preferences import PREFERENCES from utilities.forms import BootstrapMixin, DateTimePicker, StaticSelect from utilities.utils import flatten_dict @@ -100,10 +102,16 @@ class TokenForm(BootstrapMixin, forms.ModelForm): help_text="If no key is provided, one will be generated automatically." ) + allowed_ips = SimpleArrayField( + base_field=IPNetworkFormField(), + required=False, + help_text='Allowed IPv4/IPv6 networks from where the token can be used. Leave blank for no restrictions. Ex: "10.1.1.0/24, 192.168.10.16/32, 2001:DB8:1::/64"', + ) + class Meta: model = Token fields = [ - 'key', 'write_enabled', 'expires', 'description', + 'key', 'write_enabled', 'expires', 'description', 'allowed_ips', ] widgets = { 'expires': DateTimePicker(), diff --git a/netbox/users/migrations/0003_token_allowed_ips.py b/netbox/users/migrations/0003_token_allowed_ips.py new file mode 100644 index 000000000..f4eaa9f96 --- /dev/null +++ b/netbox/users/migrations/0003_token_allowed_ips.py @@ -0,0 +1,20 @@ +# Generated by Django 3.2.12 on 2022-04-19 12:37 + +import django.contrib.postgres.fields +from django.db import migrations +import ipam.fields + + +class Migration(migrations.Migration): + + dependencies = [ + ('users', '0002_standardize_id_fields'), + ] + + operations = [ + migrations.AddField( + model_name='token', + name='allowed_ips', + field=django.contrib.postgres.fields.ArrayField(base_field=ipam.fields.IPNetworkField(), blank=True, null=True, size=None), + ), + ] diff --git a/netbox/users/models.py b/netbox/users/models.py index 722ec5ba6..40ff78b98 100644 --- a/netbox/users/models.py +++ b/netbox/users/models.py @@ -4,17 +4,20 @@ import os from django.contrib.auth.models import Group, User from django.contrib.contenttypes.models import ContentType from django.contrib.postgres.fields import ArrayField +from django.core.exceptions import ValidationError from django.core.validators import MinLengthValidator from django.db import models from django.db.models.signals import post_save from django.dispatch import receiver from django.utils import timezone +from ipam.fields import IPNetworkField from netbox.config import get_config from utilities.querysets import RestrictedQuerySet from utilities.utils import flatten_dict from .constants import * +import ipaddress __all__ = ( 'ObjectPermission', @@ -216,6 +219,12 @@ class Token(models.Model): max_length=200, blank=True ) + allowed_ips = ArrayField( + base_field=IPNetworkField(), + blank=True, + null=True, + help_text='Allowed IPv4/IPv6 networks from where the token can be used. Leave blank for no restrictions. Ex: "10.1.1.0/24, 192.168.10.16/32, 2001:DB8:1::/64"', + ) class Meta: pass @@ -240,6 +249,24 @@ class Token(models.Model): return False return True + def validate_client_ip(self, raw_ip_address): + """ + Checks that an IP address falls within the allowed IPs. + """ + if not self.allowed_ips: + return True + + try: + ip_address = ipaddress.ip_address(raw_ip_address) + except ValueError as e: + raise ValidationError(str(e)) + + for ip_network in self.allowed_ips: + if ip_address in ipaddress.ip_network(ip_network): + return True + + return False + # # Permissions From 086e34f728c4fb873b7e63561bc901e9954a5ec3 Mon Sep 17 00:00:00 2001 From: Pieter Lambrecht Date: Tue, 19 Apr 2022 21:33:29 +0200 Subject: [PATCH 004/245] Updated docs relnotes to refer to 8233 --- docs/release-notes/version-3.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 09dcfcf22..415e61963 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -6,7 +6,7 @@ * [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results -* [#8878](https://github.com/netbox-community/netbox/issues/8878) - Restrict API key usage by source IP +* [#8233](https://github.com/netbox-community/netbox/issues/8233) - Restrict API key usage by source IP ### REST API Changes From fa4807be8ccf93aed93c42dbcb5231e7657c8e54 Mon Sep 17 00:00:00 2001 From: Pieter Lambrecht Date: Tue, 19 Apr 2022 21:55:39 +0200 Subject: [PATCH 005/245] Update releasenotes --- docs/release-notes/version-3.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 415e61963..294f8f4d7 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -6,7 +6,7 @@ * [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results -* [#8233](https://github.com/netbox-community/netbox/issues/8233) - Restrict API key usage by source IP +* [#8233](https://github.com/netbox-community/netbox/issues/8233) - Restrict API key access by source IP ### REST API Changes From 61d756c7c48d67417255d3ca277c09abfe147bcc Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Apr 2022 13:09:39 -0400 Subject: [PATCH 006/245] Closes #9261: NetBoxTable no longer automatically clears pre-existing calls to prefetch_related() on its queryset --- docs/release-notes/version-3.3.md | 4 ++++ netbox/netbox/tables/tables.py | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 1dd19a5c0..9b061b7d6 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -7,6 +7,10 @@ * [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results +### Other Changes + +* [#9261](https://github.com/netbox-community/netbox/issues/9261) - `NetBoxTable` no longer automatically clears pre-existing calls to `prefetch_related()` on its queryset + ### REST API Changes * extras.CustomField diff --git a/netbox/netbox/tables/tables.py b/netbox/netbox/tables/tables.py index 8c5fb039c..5ebb78865 100644 --- a/netbox/netbox/tables/tables.py +++ b/netbox/netbox/tables/tables.py @@ -97,7 +97,7 @@ class BaseTable(tables.Table): break if prefetch_path: prefetch_fields.append('__'.join(prefetch_path)) - self.data.data = self.data.data.prefetch_related(None).prefetch_related(*prefetch_fields) + self.data.data = self.data.data.prefetch_related(*prefetch_fields) def _get_columns(self, visible=True): columns = [] From e2a02de6e914cc6fd37c7c67570ddaaa88f19380 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 11 May 2022 16:13:35 -0400 Subject: [PATCH 007/245] Remove erroneous field from prefetch --- netbox/ipam/views.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/ipam/views.py b/netbox/ipam/views.py index 79804aabd..078848b3e 100644 --- a/netbox/ipam/views.py +++ b/netbox/ipam/views.py @@ -585,7 +585,7 @@ class IPRangeIPAddressesView(generic.ObjectChildrenView): def get_children(self, request, parent): return parent.get_child_ips().restrict(request.user, 'view').prefetch_related( - 'vrf', 'role', 'tenant', + 'vrf', 'tenant', ) def get_extra_context(self, request, instance): From 01d2ede097b8f908f8a57302d868ae0e50ef4dcb Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 11 May 2022 16:22:07 -0400 Subject: [PATCH 008/245] Closes #1202: Support overlapping assignment of NAT IP addresses --- docs/release-notes/version-3.3.md | 8 ++++++++ netbox/ipam/api/serializers.py | 3 +-- .../0058_ipaddress_nat_inside_nonunique.py | 17 +++++++++++++++++ netbox/ipam/models/ip.py | 2 +- netbox/templates/ipam/ipaddress.html | 10 ++++++++-- 5 files changed, 35 insertions(+), 5 deletions(-) create mode 100644 netbox/ipam/migrations/0058_ipaddress_nat_inside_nonunique.py diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 9b061b7d6..c46fceea5 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -2,8 +2,13 @@ ## v3.3.0 (FUTURE) +### Breaking Changes + +* The `nat_outside` relation on the IP address model now returns a list of zero or more related IP addresses, rather than a single instance (or None). + ### Enhancements +* [#1202](https://github.com/netbox-community/netbox/issues/1202) - Support overlapping assignment of NAT IP addresses * [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results @@ -15,3 +20,6 @@ * extras.CustomField * Added `group_name` field +* ipam.IPAddress + * The `nat_inside` field no longer requires a unique value + * The `nat_outside` field has changed from a single IP address instance to a list of multiple IP addresses diff --git a/netbox/ipam/api/serializers.py b/netbox/ipam/api/serializers.py index 3fa1bcc7e..ea5c37f91 100644 --- a/netbox/ipam/api/serializers.py +++ b/netbox/ipam/api/serializers.py @@ -360,7 +360,7 @@ class IPAddressSerializer(NetBoxModelSerializer): ) assigned_object = serializers.SerializerMethodField(read_only=True) nat_inside = NestedIPAddressSerializer(required=False, allow_null=True) - nat_outside = NestedIPAddressSerializer(required=False, read_only=True) + nat_outside = NestedIPAddressSerializer(many=True, read_only=True) class Meta: model = IPAddress @@ -369,7 +369,6 @@ class IPAddressSerializer(NetBoxModelSerializer): 'assigned_object_id', 'assigned_object', 'nat_inside', 'nat_outside', 'dns_name', 'description', 'tags', 'custom_fields', 'created', 'last_updated', ] - read_only_fields = ['family', 'nat_outside'] @swagger_serializer_method(serializer_or_field=serializers.DictField) def get_assigned_object(self, obj): diff --git a/netbox/ipam/migrations/0058_ipaddress_nat_inside_nonunique.py b/netbox/ipam/migrations/0058_ipaddress_nat_inside_nonunique.py new file mode 100644 index 000000000..63e93d137 --- /dev/null +++ b/netbox/ipam/migrations/0058_ipaddress_nat_inside_nonunique.py @@ -0,0 +1,17 @@ +from django.db import migrations, models +import django.db.models.deletion + + +class Migration(migrations.Migration): + + dependencies = [ + ('ipam', '0057_created_datetimefield'), + ] + + operations = [ + migrations.AlterField( + model_name='ipaddress', + name='nat_inside', + field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='nat_outside', to='ipam.ipaddress'), + ), + ] diff --git a/netbox/ipam/models/ip.py b/netbox/ipam/models/ip.py index a3b8fb2c1..db662f49c 100644 --- a/netbox/ipam/models/ip.py +++ b/netbox/ipam/models/ip.py @@ -813,7 +813,7 @@ class IPAddress(NetBoxModel): ct_field='assigned_object_type', fk_field='assigned_object_id' ) - nat_inside = models.OneToOneField( + nat_inside = models.ForeignKey( to='self', on_delete=models.SET_NULL, related_name='nat_outside', diff --git a/netbox/templates/ipam/ipaddress.html b/netbox/templates/ipam/ipaddress.html index 7867e829b..96a76cf8c 100644 --- a/netbox/templates/ipam/ipaddress.html +++ b/netbox/templates/ipam/ipaddress.html @@ -91,8 +91,14 @@ - NAT (outside) - {{ object.nat_outside|linkify|placeholder }} + Outside NAT IPs + + {% for ip in object.nat_outside.all %} + {{ ip|linkify }}
+ {% empty %} + {{ ''|placeholder }} + {% endfor %} +
From c48c8cc353efc21a20a7c67fa435c19619ef6359 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 25 Apr 2022 14:05:44 -0400 Subject: [PATCH 009/245] Remove termination IDs from cable creation view paths --- netbox/circuits/urls.py | 2 +- netbox/dcim/forms/connections.py | 3 +- netbox/dcim/tables/template_code.py | 50 +++++++++---------- netbox/dcim/urls.py | 16 +++--- netbox/dcim/views.py | 26 +++++----- .../circuits/inc/circuit_termination.html | 8 +-- netbox/templates/dcim/consoleport.html | 6 +-- netbox/templates/dcim/consoleserverport.html | 6 +-- netbox/templates/dcim/frontport.html | 12 ++--- netbox/templates/dcim/interface.html | 8 +-- netbox/templates/dcim/powerfeed.html | 2 +- netbox/templates/dcim/poweroutlet.html | 2 +- netbox/templates/dcim/powerport.html | 4 +- netbox/templates/dcim/rearport.html | 8 +-- 14 files changed, 76 insertions(+), 77 deletions(-) diff --git a/netbox/circuits/urls.py b/netbox/circuits/urls.py index f3ee64cf0..894be27f3 100644 --- a/netbox/circuits/urls.py +++ b/netbox/circuits/urls.py @@ -60,7 +60,7 @@ urlpatterns = [ path('circuit-terminations/add/', views.CircuitTerminationEditView.as_view(), name='circuittermination_add'), path('circuit-terminations//edit/', views.CircuitTerminationEditView.as_view(), name='circuittermination_edit'), path('circuit-terminations//delete/', views.CircuitTerminationDeleteView.as_view(), name='circuittermination_delete'), - path('circuit-terminations//connect//', CableCreateView.as_view(), name='circuittermination_connect', kwargs={'termination_a_type': CircuitTermination}), path('circuit-terminations//trace/', PathTraceView.as_view(), name='circuittermination_trace', kwargs={'model': CircuitTermination}), + path('circuit-terminations/connect/', CableCreateView.as_view(), name='circuittermination_connect', kwargs={'termination_a_type': CircuitTermination}), ] diff --git a/netbox/dcim/forms/connections.py b/netbox/dcim/forms/connections.py index 1ba7adf84..13ab0ae09 100644 --- a/netbox/dcim/forms/connections.py +++ b/netbox/dcim/forms/connections.py @@ -1,9 +1,8 @@ from circuits.models import Circuit, CircuitTermination, Provider from dcim.models import * -from extras.models import Tag from netbox.forms import NetBoxModelForm from tenancy.forms import TenancyForm -from utilities.forms import DynamicModelChoiceField, DynamicModelMultipleChoiceField, StaticSelect +from utilities.forms import DynamicModelChoiceField, StaticSelect __all__ = ( 'ConnectCableToCircuitTerminationForm', diff --git a/netbox/dcim/tables/template_code.py b/netbox/dcim/tables/template_code.py index 92739c6ed..0c1e0ed9e 100644 --- a/netbox/dcim/tables/template_code.py +++ b/netbox/dcim/tables/template_code.py @@ -133,9 +133,9 @@ CONSOLEPORT_BUTTONS = """ {% else %} @@ -165,9 +165,9 @@ CONSOLESERVERPORT_BUTTONS = """ {% else %} @@ -197,8 +197,8 @@ POWERPORT_BUTTONS = """ {% else %} @@ -224,7 +224,7 @@ POWEROUTLET_BUTTONS = """ {% if not record.mark_connected %} - + {% else %} @@ -274,10 +274,10 @@ INTERFACE_BUTTONS = """ {% else %} @@ -313,12 +313,12 @@ FRONTPORT_BUTTONS = """ {% else %} @@ -350,12 +350,12 @@ REARPORT_BUTTONS = """ {% else %} diff --git a/netbox/dcim/urls.py b/netbox/dcim/urls.py index c5cd0fa65..0c04c734e 100644 --- a/netbox/dcim/urls.py +++ b/netbox/dcim/urls.py @@ -294,7 +294,7 @@ urlpatterns = [ path('console-ports//delete/', views.ConsolePortDeleteView.as_view(), name='consoleport_delete'), path('console-ports//changelog/', ObjectChangeLogView.as_view(), name='consoleport_changelog', kwargs={'model': ConsolePort}), path('console-ports//trace/', views.PathTraceView.as_view(), name='consoleport_trace', kwargs={'model': ConsolePort}), - path('console-ports//connect//', views.CableCreateView.as_view(), name='consoleport_connect', kwargs={'termination_a_type': ConsolePort}), + path('console-ports/connect/', views.CableCreateView.as_view(), name='consoleport_connect', kwargs={'termination_a_type': ConsolePort}), path('devices/console-ports/add/', views.DeviceBulkAddConsolePortView.as_view(), name='device_bulk_add_consoleport'), # Console server ports @@ -310,7 +310,7 @@ urlpatterns = [ path('console-server-ports//delete/', views.ConsoleServerPortDeleteView.as_view(), name='consoleserverport_delete'), path('console-server-ports//changelog/', ObjectChangeLogView.as_view(), name='consoleserverport_changelog', kwargs={'model': ConsoleServerPort}), path('console-server-ports//trace/', views.PathTraceView.as_view(), name='consoleserverport_trace', kwargs={'model': ConsoleServerPort}), - path('console-server-ports//connect//', views.CableCreateView.as_view(), name='consoleserverport_connect', kwargs={'termination_a_type': ConsoleServerPort}), + path('console-server-ports/connect/', views.CableCreateView.as_view(), name='consoleserverport_connect', kwargs={'termination_a_type': ConsoleServerPort}), path('devices/console-server-ports/add/', views.DeviceBulkAddConsoleServerPortView.as_view(), name='device_bulk_add_consoleserverport'), # Power ports @@ -326,7 +326,7 @@ urlpatterns = [ path('power-ports//delete/', views.PowerPortDeleteView.as_view(), name='powerport_delete'), path('power-ports//changelog/', ObjectChangeLogView.as_view(), name='powerport_changelog', kwargs={'model': PowerPort}), path('power-ports//trace/', views.PathTraceView.as_view(), name='powerport_trace', kwargs={'model': PowerPort}), - path('power-ports//connect//', views.CableCreateView.as_view(), name='powerport_connect', kwargs={'termination_a_type': PowerPort}), + path('power-ports/connect/', views.CableCreateView.as_view(), name='powerport_connect', kwargs={'termination_a_type': PowerPort}), path('devices/power-ports/add/', views.DeviceBulkAddPowerPortView.as_view(), name='device_bulk_add_powerport'), # Power outlets @@ -342,7 +342,7 @@ urlpatterns = [ path('power-outlets//delete/', views.PowerOutletDeleteView.as_view(), name='poweroutlet_delete'), path('power-outlets//changelog/', ObjectChangeLogView.as_view(), name='poweroutlet_changelog', kwargs={'model': PowerOutlet}), path('power-outlets//trace/', views.PathTraceView.as_view(), name='poweroutlet_trace', kwargs={'model': PowerOutlet}), - path('power-outlets//connect//', views.CableCreateView.as_view(), name='poweroutlet_connect', kwargs={'termination_a_type': PowerOutlet}), + path('power-outlets/connect/', views.CableCreateView.as_view(), name='poweroutlet_connect', kwargs={'termination_a_type': PowerOutlet}), path('devices/power-outlets/add/', views.DeviceBulkAddPowerOutletView.as_view(), name='device_bulk_add_poweroutlet'), # Interfaces @@ -358,7 +358,7 @@ urlpatterns = [ path('interfaces//delete/', views.InterfaceDeleteView.as_view(), name='interface_delete'), path('interfaces//changelog/', ObjectChangeLogView.as_view(), name='interface_changelog', kwargs={'model': Interface}), path('interfaces//trace/', views.PathTraceView.as_view(), name='interface_trace', kwargs={'model': Interface}), - path('interfaces//connect//', views.CableCreateView.as_view(), name='interface_connect', kwargs={'termination_a_type': Interface}), + path('interfaces/connect/', views.CableCreateView.as_view(), name='interface_connect', kwargs={'termination_a_type': Interface}), path('devices/interfaces/add/', views.DeviceBulkAddInterfaceView.as_view(), name='device_bulk_add_interface'), # Front ports @@ -374,7 +374,7 @@ urlpatterns = [ path('front-ports//delete/', views.FrontPortDeleteView.as_view(), name='frontport_delete'), path('front-ports//changelog/', ObjectChangeLogView.as_view(), name='frontport_changelog', kwargs={'model': FrontPort}), path('front-ports//trace/', views.PathTraceView.as_view(), name='frontport_trace', kwargs={'model': FrontPort}), - path('front-ports//connect//', views.CableCreateView.as_view(), name='frontport_connect', kwargs={'termination_a_type': FrontPort}), + path('front-ports/connect/', views.CableCreateView.as_view(), name='frontport_connect', kwargs={'termination_a_type': FrontPort}), # path('devices/front-ports/add/', views.DeviceBulkAddFrontPortView.as_view(), name='device_bulk_add_frontport'), # Rear ports @@ -390,7 +390,7 @@ urlpatterns = [ path('rear-ports//delete/', views.RearPortDeleteView.as_view(), name='rearport_delete'), path('rear-ports//changelog/', ObjectChangeLogView.as_view(), name='rearport_changelog', kwargs={'model': RearPort}), path('rear-ports//trace/', views.PathTraceView.as_view(), name='rearport_trace', kwargs={'model': RearPort}), - path('rear-ports//connect//', views.CableCreateView.as_view(), name='rearport_connect', kwargs={'termination_a_type': RearPort}), + path('rear-ports/connect/', views.CableCreateView.as_view(), name='rearport_connect', kwargs={'termination_a_type': RearPort}), path('devices/rear-ports/add/', views.DeviceBulkAddRearPortView.as_view(), name='device_bulk_add_rearport'), # Module bays @@ -500,6 +500,6 @@ urlpatterns = [ path('power-feeds//trace/', views.PathTraceView.as_view(), name='powerfeed_trace', kwargs={'model': PowerFeed}), path('power-feeds//changelog/', ObjectChangeLogView.as_view(), name='powerfeed_changelog', kwargs={'model': PowerFeed}), path('power-feeds//journal/', ObjectJournalView.as_view(), name='powerfeed_journal', kwargs={'model': PowerFeed}), - path('power-feeds//connect//', views.CableCreateView.as_view(), name='powerfeed_connect', kwargs={'termination_a_type': PowerFeed}), + path('power-feeds/connect/', views.CableCreateView.as_view(), name='powerfeed_connect', kwargs={'termination_a_type': PowerFeed}), ] diff --git a/netbox/dcim/views.py b/netbox/dcim/views.py index 57e8b1c79..b18b6d4b3 100644 --- a/netbox/dcim/views.py +++ b/netbox/dcim/views.py @@ -2812,16 +2812,16 @@ class CableCreateView(generic.ObjectEditView): # Set the form class based on the type of component being connected self.form = { - 'console-port': forms.ConnectCableToConsolePortForm, - 'console-server-port': forms.ConnectCableToConsoleServerPortForm, - 'power-port': forms.ConnectCableToPowerPortForm, - 'power-outlet': forms.ConnectCableToPowerOutletForm, - 'interface': forms.ConnectCableToInterfaceForm, - 'front-port': forms.ConnectCableToFrontPortForm, - 'rear-port': forms.ConnectCableToRearPortForm, - 'power-feed': forms.ConnectCableToPowerFeedForm, - 'circuit-termination': forms.ConnectCableToCircuitTerminationForm, - }[kwargs.get('termination_b_type')] + 'dcim.consoleport': forms.ConnectCableToConsolePortForm, + 'dcim.consoleserverport': forms.ConnectCableToConsoleServerPortForm, + 'dcim.powerport': forms.ConnectCableToPowerPortForm, + 'dcim.poweroutlet': forms.ConnectCableToPowerOutletForm, + 'dcim.interface': forms.ConnectCableToInterfaceForm, + 'dcim.frontport': forms.ConnectCableToFrontPortForm, + 'dcim.rearport': forms.ConnectCableToRearPortForm, + 'dcim.powerfeed': forms.ConnectCableToPowerFeedForm, + 'circuits.circuittermination': forms.ConnectCableToCircuitTerminationForm, + }[request.GET.get('termination_b_type')] return super().dispatch(request, *args, **kwargs) @@ -2831,9 +2831,9 @@ class CableCreateView(generic.ObjectEditView): def alter_object(self, obj, request, url_args, url_kwargs): termination_a_type = url_kwargs.get('termination_a_type') - termination_a_id = url_kwargs.get('termination_a_id') - termination_b_type_name = url_kwargs.get('termination_b_type') - self.termination_b_type = ContentType.objects.get(model=termination_b_type_name.replace('-', '')) + termination_a_id = request.GET.get('termination_a_id') + app_label, model = request.GET.get('termination_b_type').split('.') + self.termination_b_type = ContentType.objects.get(app_label=app_label, model=model) # Initialize Cable termination attributes obj.termination_a = termination_a_type.objects.get(pk=termination_a_id) diff --git a/netbox/templates/circuits/inc/circuit_termination.html b/netbox/templates/circuits/inc/circuit_termination.html index fdb01e803..12fb85d57 100644 --- a/netbox/templates/circuits/inc/circuit_termination.html +++ b/netbox/templates/circuits/inc/circuit_termination.html @@ -70,10 +70,10 @@ Connect
{% endif %} diff --git a/netbox/templates/dcim/consoleport.html b/netbox/templates/dcim/consoleport.html index ce2c1655d..f2ebc16d9 100644 --- a/netbox/templates/dcim/consoleport.html +++ b/netbox/templates/dcim/consoleport.html @@ -113,7 +113,7 @@
  • Console Server Port @@ -121,7 +121,7 @@
  • Front Port @@ -129,7 +129,7 @@
  • Rear Port diff --git a/netbox/templates/dcim/consoleserverport.html b/netbox/templates/dcim/consoleserverport.html index 52b1a3229..47b784ede 100644 --- a/netbox/templates/dcim/consoleserverport.html +++ b/netbox/templates/dcim/consoleserverport.html @@ -115,7 +115,7 @@
  • Console Port @@ -123,7 +123,7 @@
  • Front Port @@ -131,7 +131,7 @@
  • Rear Port diff --git a/netbox/templates/dcim/frontport.html b/netbox/templates/dcim/frontport.html index 891f217ee..75402e2e7 100644 --- a/netbox/templates/dcim/frontport.html +++ b/netbox/templates/dcim/frontport.html @@ -105,22 +105,22 @@
    • diff --git a/netbox/templates/dcim/interface.html b/netbox/templates/dcim/interface.html index 358922730..7181d2554 100644 --- a/netbox/templates/dcim/interface.html +++ b/netbox/templates/dcim/interface.html @@ -251,22 +251,22 @@ diff --git a/netbox/utilities/templatetags/navigation.py b/netbox/utilities/templatetags/navigation.py index ede8792fa..ef0657446 100644 --- a/netbox/utilities/templatetags/navigation.py +++ b/netbox/utilities/templatetags/navigation.py @@ -13,7 +13,26 @@ def nav(context: Context) -> Dict: """ Render the navigation menu. """ + user = context['request'].user + nav_items = [] + + # Construct the navigation menu based upon the current user's permissions + for menu in MENUS: + groups = [] + for group in menu.groups: + items = [] + for item in group.items: + if user.has_perms(item.permissions): + buttons = [ + button for button in item.buttons if user.has_perms(button.permissions) + ] + items.append((item, buttons)) + if items: + groups.append((group, items)) + if groups: + nav_items.append((menu, groups)) + return { - "nav_items": MENUS, + "nav_items": nav_items, "request": context["request"] } From 3be9f6c4f3a74ab74f35f6cdc4de77593583c409 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 29 Jun 2022 16:01:20 -0500 Subject: [PATCH 113/245] #8157 - Final work on L2VPN model --- netbox/dcim/api/serializers.py | 4 +- netbox/dcim/models/device_components.py | 7 +- netbox/ipam/api/nested_serializers.py | 8 +- netbox/ipam/api/serializers.py | 5 +- netbox/ipam/api/views.py | 2 +- netbox/ipam/filtersets.py | 51 ++++++++- netbox/ipam/forms/bulk_edit.py | 5 + netbox/ipam/graphql/schema.py | 6 ++ netbox/ipam/graphql/types.py | 16 +++ netbox/ipam/models/vlans.py | 7 +- netbox/ipam/tests/test_api.py | 38 +++---- netbox/ipam/tests/test_filtersets.py | 62 +++++------ netbox/ipam/tests/test_models.py | 81 ++++++++++++-- netbox/ipam/tests/test_views.py | 138 ++++++++++++++++++++++-- netbox/ipam/urls.py | 1 + netbox/ipam/views.py | 21 ++-- netbox/templates/dcim/interface.html | 4 + netbox/templates/ipam/vlan.html | 4 + 18 files changed, 376 insertions(+), 84 deletions(-) diff --git a/netbox/dcim/api/serializers.py b/netbox/dcim/api/serializers.py index 8ac2aa738..32709000b 100644 --- a/netbox/dcim/api/serializers.py +++ b/netbox/dcim/api/serializers.py @@ -10,6 +10,7 @@ from dcim.constants import * from dcim.models import * from ipam.api.nested_serializers import ( NestedASNSerializer, NestedIPAddressSerializer, NestedVLANSerializer, NestedVRFSerializer, + NestedL2VPNTerminationSerializer, ) from ipam.models import ASN, VLAN from netbox.api import ChoiceField, ContentTypeField, SerializedPKRelatedField @@ -823,6 +824,7 @@ class InterfaceSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Conn many=True ) vrf = NestedVRFSerializer(required=False, allow_null=True) + l2vpn_termination = NestedL2VPNTerminationSerializer(read_only=True) cable = NestedCableSerializer(read_only=True) wireless_link = NestedWirelessLinkSerializer(read_only=True) wireless_lans = SerializedPKRelatedField( @@ -841,7 +843,7 @@ class InterfaceSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Conn 'mtu', 'mac_address', 'speed', 'duplex', 'wwn', 'mgmt_only', 'description', 'mode', 'rf_role', 'rf_channel', 'poe_mode', 'poe_type', 'rf_channel_frequency', 'rf_channel_width', 'tx_power', 'untagged_vlan', 'tagged_vlans', 'mark_connected', 'cable', 'wireless_link', 'link_peer', 'link_peer_type', 'wireless_lans', - 'vrf', 'connected_endpoint', 'connected_endpoint_type', 'connected_endpoint_reachable', 'tags', + 'vrf', 'l2vpn_termination', 'connected_endpoint', 'connected_endpoint_type', 'connected_endpoint_reachable', 'tags', 'custom_fields', 'created', 'last_updated', 'count_ipaddresses', 'count_fhrp_groups', '_occupied', ] diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 4d19a2d8d..70c21c165 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -649,10 +649,11 @@ class Interface(ModularComponentModel, BaseInterface, LinkTermination, PathEndpo object_id_field='interface_id', related_query_name='+' ) - l2vpn = GenericRelation( + l2vpn_terminations = GenericRelation( to='ipam.L2VPNTermination', content_type_field='assigned_object_type', object_id_field='assigned_object_id', + related_query_name='interface', ) clone_fields = ['device', 'parent', 'bridge', 'lag', 'type', 'mgmt_only', 'poe_mode', 'poe_type'] @@ -828,6 +829,10 @@ class Interface(ModularComponentModel, BaseInterface, LinkTermination, PathEndpo def link(self): return self.cable or self.wireless_link + @property + def l2vpn_termination(self): + return self.l2vpn_terminations.first() + # # Pass-through ports diff --git a/netbox/ipam/api/nested_serializers.py b/netbox/ipam/api/nested_serializers.py index 8316cb992..39305a017 100644 --- a/netbox/ipam/api/nested_serializers.py +++ b/netbox/ipam/api/nested_serializers.py @@ -11,6 +11,8 @@ __all__ = [ 'NestedFHRPGroupAssignmentSerializer', 'NestedIPAddressSerializer', 'NestedIPRangeSerializer', + 'NestedL2VPNSerializer', + 'NestedL2VPNTerminationSerializer', 'NestedPrefixSerializer', 'NestedRIRSerializer', 'NestedRoleSerializer', @@ -203,17 +205,17 @@ class NestedL2VPNSerializer(WritableNestedSerializer): class Meta: model = L2VPN fields = [ - 'id', 'url', 'display', 'name', 'type' + 'id', 'url', 'display', 'identifier', 'name', 'slug', 'type' ] class NestedL2VPNTerminationSerializer(WritableNestedSerializer): - url = serializers.HyperlinkedIdentityField(view_name='ipam-api:l2vpn_termination-detail') + url = serializers.HyperlinkedIdentityField(view_name='ipam-api:l2vpntermination-detail') l2vpn = NestedL2VPNSerializer() class Meta: model = L2VPNTermination fields = [ - 'id', 'url', 'display', 'l2vpn', 'assigned_object' + 'id', 'url', 'display', 'l2vpn' ] diff --git a/netbox/ipam/api/serializers.py b/netbox/ipam/api/serializers.py index a51043e27..36102f853 100644 --- a/netbox/ipam/api/serializers.py +++ b/netbox/ipam/api/serializers.py @@ -207,13 +207,14 @@ class VLANSerializer(NetBoxModelSerializer): tenant = NestedTenantSerializer(required=False, allow_null=True) status = ChoiceField(choices=VLANStatusChoices, required=False) role = NestedRoleSerializer(required=False, allow_null=True) + l2vpn_termination = NestedL2VPNTerminationSerializer(read_only=True) prefix_count = serializers.IntegerField(read_only=True) class Meta: model = VLAN fields = [ - 'id', 'url', 'display', 'site', 'group', 'vid', 'name', 'tenant', 'status', 'role', 'description', 'tags', - 'custom_fields', 'created', 'last_updated', 'prefix_count', + 'id', 'url', 'display', 'site', 'group', 'vid', 'name', 'tenant', 'status', 'role', 'description', + 'l2vpn_termination', 'tags', 'custom_fields', 'created', 'last_updated', 'prefix_count', ] diff --git a/netbox/ipam/api/views.py b/netbox/ipam/api/views.py index 36a6f02b6..f5a61c031 100644 --- a/netbox/ipam/api/views.py +++ b/netbox/ipam/api/views.py @@ -165,7 +165,7 @@ class L2VPNViewSet(NetBoxModelViewSet): class L2VPNTerminationViewSet(NetBoxModelViewSet): - queryset = L2VPNTermination.objects + queryset = L2VPNTermination.objects.prefetch_related('assigned_object') serializer_class = serializers.L2VPNTerminationSerializer filterset_class = filtersets.L2VPNTerminationFilterSet diff --git a/netbox/ipam/filtersets.py b/netbox/ipam/filtersets.py index 03189a7cb..f682009ee 100644 --- a/netbox/ipam/filtersets.py +++ b/netbox/ipam/filtersets.py @@ -957,7 +957,7 @@ class L2VPNFilterSet(NetBoxModelFilterSet, TenancyFilterSet): class Meta: model = L2VPN - fields = ['identifier', 'name', 'type', 'description'] + fields = ['id', 'identifier', 'name', 'type', 'description'] def search(self, queryset, name, value): if not value.strip(): @@ -977,13 +977,60 @@ class L2VPNTerminationFilterSet(NetBoxModelFilterSet): to_field_name='name', label='L2VPN (name)', ) + device = MultiValueCharFilter( + method='filter_device', + field_name='name', + label='Device (name)', + ) + device_id = MultiValueNumberFilter( + method='filter_device', + field_name='pk', + label='Device (ID)', + ) + interface = django_filters.ModelMultipleChoiceFilter( + field_name='interface__name', + queryset=Interface.objects.all(), + to_field_name='name', + label='Interface (name)', + ) + interface_id = django_filters.ModelMultipleChoiceFilter( + field_name='interface', + queryset=Interface.objects.all(), + label='Interface (ID)', + ) + vlan = django_filters.ModelMultipleChoiceFilter( + field_name='vlan__name', + queryset=VLAN.objects.all(), + to_field_name='name', + label='VLAN (name)', + ) + vlan_vid = django_filters.NumberFilter( + field_name='vlan__vid', + label='VLAN number (1-4094)', + ) + vlan_id = django_filters.ModelMultipleChoiceFilter( + field_name='vlan', + queryset=VLAN.objects.all(), + label='VLAN (ID)', + ) class Meta: model = L2VPNTermination - fields = ['l2vpn'] + fields = ['id', ] def search(self, queryset, name, value): if not value.strip(): return queryset qs_filter = Q(l2vpn__name__icontains=value) return queryset.filter(qs_filter) + + def filter_device(self, queryset, name, value): + devices = Device.objects.filter(**{'{}__in'.format(name): value}) + if not devices.exists(): + return queryset.none() + interface_ids = [] + for device in devices: + interface_ids.extend(device.vc_interfaces().values_list('id', flat=True)) + return queryset.filter( + interface__in=interface_ids + ) diff --git a/netbox/ipam/forms/bulk_edit.py b/netbox/ipam/forms/bulk_edit.py index bbfa5bf9f..50fc51522 100644 --- a/netbox/ipam/forms/bulk_edit.py +++ b/netbox/ipam/forms/bulk_edit.py @@ -19,6 +19,7 @@ __all__ = ( 'IPAddressBulkEditForm', 'IPRangeBulkEditForm', 'L2VPNBulkEditForm', + 'L2VPNTerminationBulkEditForm', 'PrefixBulkEditForm', 'RIRBulkEditForm', 'RoleBulkEditForm', @@ -458,3 +459,7 @@ class L2VPNBulkEditForm(NetBoxModelBulkEditForm): (None, ('tenant', 'description')), ) nullable_fields = ('tenant', 'description',) + + +class L2VPNTerminationBulkEditForm(NetBoxModelBulkEditForm): + model = L2VPN diff --git a/netbox/ipam/graphql/schema.py b/netbox/ipam/graphql/schema.py index f466c1857..5cd5e030e 100644 --- a/netbox/ipam/graphql/schema.py +++ b/netbox/ipam/graphql/schema.py @@ -17,6 +17,12 @@ class IPAMQuery(graphene.ObjectType): ip_range = ObjectField(IPRangeType) ip_range_list = ObjectListField(IPRangeType) + l2vpn = ObjectField(L2VPNType) + l2vpn_list = ObjectListField(L2VPNType) + + l2vpn_termination = ObjectField(L2VPNTerminationType) + l2vpn_termination_list = ObjectListField(L2VPNTerminationType) + prefix = ObjectField(PrefixType) prefix_list = ObjectListField(PrefixType) diff --git a/netbox/ipam/graphql/types.py b/netbox/ipam/graphql/types.py index ca206b4b8..5af2ca72a 100644 --- a/netbox/ipam/graphql/types.py +++ b/netbox/ipam/graphql/types.py @@ -11,6 +11,8 @@ __all__ = ( 'FHRPGroupAssignmentType', 'IPAddressType', 'IPRangeType', + 'L2VPNType', + 'L2VPNTerminationType', 'PrefixType', 'RIRType', 'RoleType', @@ -151,3 +153,17 @@ class VRFType(NetBoxObjectType): model = models.VRF fields = '__all__' filterset_class = filtersets.VRFFilterSet + + +class L2VPNType(NetBoxObjectType): + class Meta: + model = models.L2VPN + fields = '__all__' + filtersets_class = filtersets.L2VPNFilterSet + + +class L2VPNTerminationType(NetBoxObjectType): + class Meta: + model = models.L2VPNTermination + fields = '__all__' + filtersets_class = filtersets.L2VPNTerminationFilterSet diff --git a/netbox/ipam/models/vlans.py b/netbox/ipam/models/vlans.py index 3a7969405..f0e062721 100644 --- a/netbox/ipam/models/vlans.py +++ b/netbox/ipam/models/vlans.py @@ -174,10 +174,11 @@ class VLAN(NetBoxModel): blank=True ) - l2vpn = GenericRelation( + l2vpn_terminations = GenericRelation( to='ipam.L2VPNTermination', content_type_field='assigned_object_type', object_id_field='assigned_object_id', + related_query_name='vlan' ) objects = VLANQuerySet.as_manager() @@ -234,3 +235,7 @@ class VLAN(NetBoxModel): Q(untagged_vlan_id=self.pk) | Q(tagged_vlans=self.pk) ).distinct() + + @property + def l2vpn_termination(self): + return self.l2vpn_terminations.first() diff --git a/netbox/ipam/tests/test_api.py b/netbox/ipam/tests/test_api.py index 0e93bd43e..a5ebef2c7 100644 --- a/netbox/ipam/tests/test_api.py +++ b/netbox/ipam/tests/test_api.py @@ -947,28 +947,28 @@ class L2VPNTest(APIViewTestCases.APIViewTestCase): def setUpTestData(cls): l2vpns = ( - L2VPN(name='L2VPN 1', type='vxlan', identifier=650001), - L2VPN(name='L2VPN 2', type='vpws', identifier=650002), - L2VPN(name='L2VPN 3', type='vpls'), # No RD + L2VPN(name='L2VPN 1', slug='l2vpn-1', type='vxlan', identifier=650001), + L2VPN(name='L2VPN 2', slug='l2vpn-2', type='vpws', identifier=650002), + L2VPN(name='L2VPN 3', slug='l2vpn-3', type='vpls'), # No RD ) L2VPN.objects.bulk_create(l2vpns) class L2VPNTerminationTest(APIViewTestCases.APIViewTestCase): model = L2VPNTermination - brief_fields = ['display', 'id', 'l2vpn', 'assigned_object', 'assigned_object_id', 'assigned_object_type', 'url'] + brief_fields = ['display', 'id', 'l2vpn', 'url'] @classmethod def setUpTestData(cls): vlans = ( - VLAN(name='VLAN 1', vid=650001), - VLAN(name='VLAN 2', vid=650002), - VLAN(name='VLAN 3', vid=650003), - VLAN(name='VLAN 4', vid=650004), - VLAN(name='VLAN 5', vid=650005), - VLAN(name='VLAN 6', vid=650006), - VLAN(name='VLAN 7', vid=650007) + VLAN(name='VLAN 1', vid=651), + VLAN(name='VLAN 2', vid=652), + VLAN(name='VLAN 3', vid=653), + VLAN(name='VLAN 4', vid=654), + VLAN(name='VLAN 5', vid=655), + VLAN(name='VLAN 6', vid=656), + VLAN(name='VLAN 7', vid=657) ) VLAN.objects.bulk_create(vlans) @@ -986,24 +986,26 @@ class L2VPNTerminationTest(APIViewTestCases.APIViewTestCase): L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[2]) ) + L2VPNTermination.objects.bulk_create(l2vpnterminations) + cls.create_data = [ { - 'l2vpn': l2vpns[0], + 'l2vpn': l2vpns[0].pk, 'assigned_object_type': 'ipam.vlan', - 'assigned_object_id': vlans[3], + 'assigned_object_id': vlans[3].pk, }, { - 'l2vpn': l2vpns[0], + 'l2vpn': l2vpns[0].pk, 'assigned_object_type': 'ipam.vlan', - 'assigned_object_id': vlans[4], + 'assigned_object_id': vlans[4].pk, }, { - 'l2vpn': l2vpns[0], + 'l2vpn': l2vpns[0].pk, 'assigned_object_type': 'ipam.vlan', - 'assigned_object_id': vlans[5], + 'assigned_object_id': vlans[5].pk, }, ] cls.bulk_update_data = { - 'l2vpn': l2vpns[2] + 'l2vpn': l2vpns[2].pk } diff --git a/netbox/ipam/tests/test_filtersets.py b/netbox/ipam/tests/test_filtersets.py index c5cffc7dc..2b5fb0759 100644 --- a/netbox/ipam/tests/test_filtersets.py +++ b/netbox/ipam/tests/test_filtersets.py @@ -1465,8 +1465,7 @@ class ServiceTestCase(TestCase, ChangeLoggedFilterSetTests): self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) -class L2VPNTest(TestCase, ChangeLoggedFilterSetTests): - # TODO: L2VPN Tests +class L2VPNTestCase(TestCase, ChangeLoggedFilterSetTests): queryset = L2VPN.objects.all() filterset = L2VPNFilterSet @@ -1480,20 +1479,8 @@ class L2VPNTest(TestCase, ChangeLoggedFilterSetTests): ) L2VPN.objects.bulk_create(l2vpns) - def test_created(self): - from datetime import date, date - pk_list = self.queryset.values_list('pk', flat=True)[:2] - print(pk_list) - self.queryset.filter(pk__in=pk_list).update(created=datetime(2021, 1, 1, 0, 0, 0, tzinfo=timezone.utc)) - params = {'created': '2021-01-01T00:00:00'} - fs = self.filterset({}, self.queryset).qs.all() - for res in fs: - print(f'{res.name}:{res.created}') - self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) - -class L2VPNTerminationTest(TestCase, ChangeLoggedFilterSetTests): - # TODO: L2VPN Termination Tests +class L2VPNTerminationTestCase(TestCase, ChangeLoggedFilterSetTests): queryset = L2VPNTermination.objects.all() filterset = L2VPNTerminationFilterSet @@ -1511,22 +1498,24 @@ class L2VPNTerminationTest(TestCase, ChangeLoggedFilterSetTests): device_role=device_role, status='active' ) - interfaces = Interface.objects.bulk_create( - Interface(name='GigabitEthernet1/0/1', device=device, type='1000baset'), - Interface(name='GigabitEthernet1/0/2', device=device, type='1000baset'), - Interface(name='GigabitEthernet1/0/3', device=device, type='1000baset'), - Interface(name='GigabitEthernet1/0/4', device=device, type='1000baset'), - Interface(name='GigabitEthernet1/0/5', device=device, type='1000baset'), + + interfaces = ( + Interface(name='Interface 1', device=device, type='1000baset'), + Interface(name='Interface 2', device=device, type='1000baset'), + Interface(name='Interface 3', device=device, type='1000baset'), + Interface(name='Interface 4', device=device, type='1000baset'), + Interface(name='Interface 5', device=device, type='1000baset'), + Interface(name='Interface 6', device=device, type='1000baset') ) + Interface.objects.bulk_create(interfaces) + vlans = ( - VLAN(name='VLAN 1', vid=650001), - VLAN(name='VLAN 2', vid=650002), - VLAN(name='VLAN 3', vid=650003), - VLAN(name='VLAN 4', vid=650004), - VLAN(name='VLAN 5', vid=650005), - VLAN(name='VLAN 6', vid=650006), - VLAN(name='VLAN 7', vid=650007) + VLAN(name='VLAN 1', vid=651), + VLAN(name='VLAN 2', vid=652), + VLAN(name='VLAN 3', vid=653), + VLAN(name='VLAN 4', vid=654), + VLAN(name='VLAN 5', vid=655) ) VLAN.objects.bulk_create(vlans) @@ -1534,26 +1523,33 @@ class L2VPNTerminationTest(TestCase, ChangeLoggedFilterSetTests): l2vpns = ( L2VPN(name='L2VPN 1', type='vxlan', identifier=650001), L2VPN(name='L2VPN 2', type='vpws', identifier=650002), - L2VPN(name='L2VPN 3', type='vpls'), # No RD + L2VPN(name='L2VPN 3', type='vpls'), # No RD, ) L2VPN.objects.bulk_create(l2vpns) l2vpnterminations = ( L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[0]), - L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[1]), - L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[2]) + L2VPNTermination(l2vpn=l2vpns[1], assigned_object=vlans[1]), + L2VPNTermination(l2vpn=l2vpns[2], assigned_object=vlans[2]), + L2VPNTermination(l2vpn=l2vpns[0], assigned_object=interfaces[0]), + L2VPNTermination(l2vpn=l2vpns[1], assigned_object=interfaces[1]), + L2VPNTermination(l2vpn=l2vpns[2], assigned_object=interfaces[2]), ) + L2VPNTermination.objects.bulk_create(l2vpnterminations) + def test_l2vpns(self): l2vpns = L2VPN.objects.all()[:2] params = {'l2vpn_id': [l2vpns[0].pk, l2vpns[1].pk]} - self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 4) params = {'l2vpn': ['L2VPN 1', 'L2VPN 2']} - self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 4) def test_interfaces(self): interfaces = Interface.objects.all()[:2] params = {'interface_id': [interfaces[0].pk, interfaces[1].pk]} + qs = self.filterset(params, self.queryset).qs + results = qs.all() self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) params = {'interface': ['Interface 1', 'Interface 2']} self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) diff --git a/netbox/ipam/tests/test_models.py b/netbox/ipam/tests/test_models.py index ce4643516..1b5fbadc3 100644 --- a/netbox/ipam/tests/test_models.py +++ b/netbox/ipam/tests/test_models.py @@ -2,8 +2,9 @@ from netaddr import IPNetwork, IPSet from django.core.exceptions import ValidationError from django.test import TestCase, override_settings +from dcim.models import Interface, Device, DeviceRole, DeviceType, Manufacturer, Site from ipam.choices import IPAddressRoleChoices, PrefixStatusChoices -from ipam.models import Aggregate, IPAddress, IPRange, Prefix, RIR, VLAN, VLANGroup, VRF +from ipam.models import Aggregate, IPAddress, IPRange, Prefix, RIR, VLAN, VLANGroup, VRF, L2VPN, L2VPNTermination class TestAggregate(TestCase): @@ -540,11 +541,75 @@ class TestVLANGroup(TestCase): self.assertEqual(vlangroup.get_next_available_vid(), 105) -class TestL2VPN(TestCase): - # TODO: L2VPN Tests - pass - - class TestL2VPNTermination(TestCase): - # TODO: L2VPN Termination Tests - pass + + @classmethod + def setUpTestData(cls): + + site = Site.objects.create(name='Site 1') + manufacturer = Manufacturer.objects.create(name='Manufacturer 1') + device_type = DeviceType.objects.create(model='Device Type 1', manufacturer=manufacturer) + device_role = DeviceRole.objects.create(name='Switch') + device = Device.objects.create( + name='Device 1', + site=site, + device_type=device_type, + device_role=device_role, + status='active' + ) + + interfaces = ( + Interface(name='Interface 1', device=device, type='1000baset'), + Interface(name='Interface 2', device=device, type='1000baset'), + Interface(name='Interface 3', device=device, type='1000baset'), + Interface(name='Interface 4', device=device, type='1000baset'), + Interface(name='Interface 5', device=device, type='1000baset'), + ) + + Interface.objects.bulk_create(interfaces) + + vlans = ( + VLAN(name='VLAN 1', vid=651), + VLAN(name='VLAN 2', vid=652), + VLAN(name='VLAN 3', vid=653), + VLAN(name='VLAN 4', vid=654), + VLAN(name='VLAN 5', vid=655), + VLAN(name='VLAN 6', vid=656), + VLAN(name='VLAN 7', vid=657) + ) + + VLAN.objects.bulk_create(vlans) + + l2vpns = ( + L2VPN(name='L2VPN 1', type='vxlan', identifier=650001), + L2VPN(name='L2VPN 2', type='vpws', identifier=650002), + L2VPN(name='L2VPN 3', type='vpls'), # No RD + ) + L2VPN.objects.bulk_create(l2vpns) + + l2vpnterminations = ( + L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[0]), + L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[1]), + L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[2]) + ) + + L2VPNTermination.objects.bulk_create(l2vpnterminations) + + def test_duplicate_interface_terminations(self): + device = Device.objects.first() + interface = Interface.objects.filter(device=device).first() + l2vpn = L2VPN.objects.first() + + L2VPNTermination.objects.create(l2vpn=l2vpn, assigned_object=interface) + duplicate = L2VPNTermination(l2vpn=l2vpn, assigned_object=interface) + + self.assertRaises(ValidationError, duplicate.clean) + + def test_duplicate_vlan_terminations(self): + vlan = Interface.objects.first() + l2vpn = L2VPN.objects.first() + + L2VPNTermination.objects.create(l2vpn=l2vpn, assigned_object=vlan) + duplicate = L2VPNTermination(l2vpn=l2vpn, assigned_object=vlan) + self.assertRaises(ValidationError, duplicate.clean) + diff --git a/netbox/ipam/tests/test_views.py b/netbox/ipam/tests/test_views.py index 8d1b9bd1b..dd3733d4d 100644 --- a/netbox/ipam/tests/test_views.py +++ b/netbox/ipam/tests/test_views.py @@ -1,14 +1,18 @@ import datetime +from django.contrib.contenttypes.models import ContentType from django.test import override_settings from django.urls import reverse from netaddr import IPNetwork -from dcim.models import Device, DeviceRole, DeviceType, Manufacturer, Site +from dcim.models import Device, DeviceRole, DeviceType, Manufacturer, Site, Interface +from extras.choices import ObjectChangeActionChoices +from extras.models import ObjectChange from ipam.choices import * from ipam.models import * from tenancy.models import Tenant -from utilities.testing import ViewTestCases, create_tags +from users.models import ObjectPermission +from utilities.testing import ViewTestCases, create_tags, post_data class ASNTestCase(ViewTestCases.PrimaryObjectViewTestCase): @@ -749,10 +753,130 @@ class ServiceTestCase(ViewTestCases.PrimaryObjectViewTestCase): class L2VPNTestCase(ViewTestCases.PrimaryObjectViewTestCase): - # TODO: L2VPN Tests - pass + model = L2VPN + csv_data = ( + 'name,slug,type,identifier', + 'L2VPN 5,l2vpn-5,vxlan,456', + 'L2VPN 6,l2vpn-6,vxlan,444', + ) + bulk_edit_data = { + 'description': 'New Description', + } + + @classmethod + def setUpTestData(cls): + rts = ( + RouteTarget(name='64534:123'), + RouteTarget(name='64534:321') + ) + RouteTarget.objects.bulk_create(rts) + + l2vpns = ( + L2VPN(name='L2VPN 1', slug='l2vpn-1', type='vxlan', identifier='650001'), + L2VPN(name='L2VPN 2', slug='l2vpn-2', type='vxlan', identifier='650002'), + L2VPN(name='L2VPN 3', slug='l2vpn-3', type='vxlan', identifier='650003') + ) + + L2VPN.objects.bulk_create(l2vpns) + + cls.form_data = { + 'name': 'L2VPN 8', + 'slug': 'l2vpn-8', + 'type': 'vxlan', + 'identifier': 123, + 'description': 'Description', + 'import_targets': [rts[0].pk], + 'export_targets': [rts[1].pk] + } + + print(cls.form_data) -class L2VPNTerminationTestCase(ViewTestCases.PrimaryObjectViewTestCase): - # TODO: L2VPN Termination Tests - pass +class L2VPNTerminationTestCase( + ViewTestCases.GetObjectViewTestCase, + ViewTestCases.GetObjectChangelogViewTestCase, + ViewTestCases.CreateObjectViewTestCase, + ViewTestCases.EditObjectViewTestCase, + ViewTestCases.DeleteObjectViewTestCase, + ViewTestCases.ListObjectsViewTestCase, + ViewTestCases.BulkImportObjectsViewTestCase, + ViewTestCases.BulkDeleteObjectsViewTestCase, +): + + model = L2VPNTermination + + @classmethod + def setUpTestData(cls): + site = Site.objects.create(name='Site 1') + manufacturer = Manufacturer.objects.create(name='Manufacturer 1') + device_type = DeviceType.objects.create(model='Device Type 1', manufacturer=manufacturer) + device_role = DeviceRole.objects.create(name='Switch') + device = Device.objects.create( + name='Device 1', + site=site, + device_type=device_type, + device_role=device_role, + status='active' + ) + + interface = Interface.objects.create(name='Interface 1', device=device, type='1000baset') + l2vpn = L2VPN.objects.create(name='L2VPN 1', type='vxlan', identifier=650001) + l2vpn_vlans = L2VPN.objects.create(name='L2VPN 2', type='vxlan', identifier=650002) + + vlans = ( + VLAN(name='Vlan 1', vid=1001), + VLAN(name='Vlan 2', vid=1002), + VLAN(name='Vlan 3', vid=1003), + VLAN(name='Vlan 4', vid=1004), + VLAN(name='Vlan 5', vid=1005), + VLAN(name='Vlan 6', vid=1006) + ) + VLAN.objects.bulk_create(vlans) + + terminations = ( + L2VPNTermination(l2vpn=l2vpn, assigned_object=vlans[0]), + L2VPNTermination(l2vpn=l2vpn, assigned_object=vlans[1]), + L2VPNTermination(l2vpn=l2vpn, assigned_object=vlans[2]) + ) + L2VPNTermination.objects.bulk_create(terminations) + + cls.form_data = { + 'l2vpn': l2vpn.pk, + 'device': device.pk, + 'interface': interface.pk, + } + + cls.csv_data = ( + "l2vpn,vlan", + "L2VPN 2,Vlan 4", + "L2VPN 2,Vlan 5", + "L2VPN 2,Vlan 6", + ) + + cls.bulk_edit_data = {} + + # + # Custom assertions + # + + def assertInstanceEqual(self, instance, data, exclude=None, api=False): + """ + Override parent + """ + if exclude is None: + exclude = [] + + fields = [k for k in data.keys() if k not in exclude] + model_dict = self.model_to_dict(instance, fields=fields, api=api) + + # Omit any dictionary keys which are not instance attributes or have been excluded + relevant_data = { + k: v for k, v in data.items() if hasattr(instance, k) and k not in exclude + } + + # Handle relations on the model + for k, v in model_dict.items(): + if isinstance(v, object) and hasattr(v, 'first'): + model_dict[k] = v.first().pk + + self.assertDictEqual(model_dict, relevant_data) diff --git a/netbox/ipam/urls.py b/netbox/ipam/urls.py index 65a6b55ad..e00b0365f 100644 --- a/netbox/ipam/urls.py +++ b/netbox/ipam/urls.py @@ -201,6 +201,7 @@ urlpatterns = [ path('l2vpn-termination/', views.L2VPNTerminationListView.as_view(), name='l2vpntermination_list'), path('l2vpn-termination/add/', views.L2VPNTerminationEditView.as_view(), name='l2vpntermination_add'), path('l2vpn-termination/import/', views.L2VPNTerminationBulkImportView.as_view(), name='l2vpntermination_import'), + path('l2vpn-termination/edit/', views.L2VPNTerminationBulkEditView.as_view(), name='l2vpntermination_bulk_edit'), path('l2vpn-termination/delete/', views.L2VPNTerminationBulkDeleteView.as_view(), name='l2vpntermination_bulk_delete'), path('l2vpn-termination//', views.L2VPNTerminationView.as_view(), name='l2vpntermination'), path('l2vpn-termination//edit/', views.L2VPNTerminationEditView.as_view(), name='l2vpntermination_edit'), diff --git a/netbox/ipam/views.py b/netbox/ipam/views.py index 77539434c..35103be48 100644 --- a/netbox/ipam/views.py +++ b/netbox/ipam/views.py @@ -1141,6 +1141,13 @@ class ServiceBulkEditView(generic.BulkEditView): queryset = Service.objects.prefetch_related('device', 'virtual_machine') filterset = filtersets.ServiceFilterSet table = tables.ServiceTable + form = forms.ServiceBulkEditForm + + +class ServiceBulkDeleteView(generic.BulkDeleteView): + queryset = Service.objects.prefetch_related('device', 'virtual_machine') + filterset = filtersets.ServiceFilterSet + table = tables.ServiceTable # L2VPN @@ -1232,14 +1239,14 @@ class L2VPNTerminationBulkImportView(generic.BulkImportView): table = tables.L2VPNTerminationTable +class L2VPNTerminationBulkEditView(generic.BulkEditView): + queryset = L2VPNTermination.objects.all() + filterset = filtersets.L2VPNTerminationFilterSet + table = tables.L2VPNTerminationTable + form = forms.L2VPNTerminationBulkEditForm + + class L2VPNTerminationBulkDeleteView(generic.BulkDeleteView): queryset = L2VPNTermination.objects.all() filterset = filtersets.L2VPNTerminationFilterSet table = tables.L2VPNTerminationTable - form = forms.ServiceBulkEditForm - - -class ServiceBulkDeleteView(generic.BulkDeleteView): - queryset = Service.objects.prefetch_related('device', 'virtual_machine') - filterset = filtersets.ServiceFilterSet - table = tables.ServiceTable diff --git a/netbox/templates/dcim/interface.html b/netbox/templates/dcim/interface.html index e98750518..247592e14 100644 --- a/netbox/templates/dcim/interface.html +++ b/netbox/templates/dcim/interface.html @@ -104,6 +104,10 @@ LAG {{ object.lag|linkify|placeholder }} + + L2VPN + {{ object.l2vpn_termination.l2vpn|linkify|placeholder }} + diff --git a/netbox/templates/ipam/vlan.html b/netbox/templates/ipam/vlan.html index fd0ba36a3..53bb75b8f 100644 --- a/netbox/templates/ipam/vlan.html +++ b/netbox/templates/ipam/vlan.html @@ -64,6 +64,10 @@ Description {{ object.description|placeholder }} + + L2VPN + {{ object.l2vpn_termination.l2vpn|linkify|placeholder }} + From 6e983d154264b6af6586db01ef93586a7276261f Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 29 Jun 2022 16:14:30 -0500 Subject: [PATCH 114/245] Fix up some PEP errors --- netbox/ipam/api/nested_serializers.py | 1 - netbox/ipam/choices.py | 31 +++++++++++++-------------- netbox/ipam/tests/test_models.py | 1 - 3 files changed, 15 insertions(+), 18 deletions(-) diff --git a/netbox/ipam/api/nested_serializers.py b/netbox/ipam/api/nested_serializers.py index 39305a017..07a7c9598 100644 --- a/netbox/ipam/api/nested_serializers.py +++ b/netbox/ipam/api/nested_serializers.py @@ -218,4 +218,3 @@ class NestedL2VPNTerminationSerializer(WritableNestedSerializer): fields = [ 'id', 'url', 'display', 'l2vpn' ] - diff --git a/netbox/ipam/choices.py b/netbox/ipam/choices.py index a867b05bc..72cd4ff73 100644 --- a/netbox/ipam/choices.py +++ b/netbox/ipam/choices.py @@ -192,26 +192,25 @@ class L2VPNTypeChoices(ChoiceSet): (TYPE_VPLS, 'VPLS'), )), ('E-Line', ( - (TYPE_EPL, 'EPL'), - (TYPE_EVPL, 'EVPL'), - )), + (TYPE_EPL, 'EPL'), + (TYPE_EVPL, 'EVPL'), + )), ('E-LAN', ( - (TYPE_EPLAN, 'Ethernet Private LAN'), - (TYPE_EVPLAN, 'Ethernet Virtual Private LAN'), - )), + (TYPE_EPLAN, 'Ethernet Private LAN'), + (TYPE_EVPLAN, 'Ethernet Virtual Private LAN'), + )), ('E-Tree', ( - (TYPE_EPTREE, 'Ethernet Private Tree'), - (TYPE_EVPTREE, 'Ethernet Virtual Private Tree'), - )), + (TYPE_EPTREE, 'Ethernet Private Tree'), + (TYPE_EVPTREE, 'Ethernet Virtual Private Tree'), + )), ('VXLAN', ( - (TYPE_VXLAN, 'VXLAN'), - (TYPE_VXLAN_EVPN, 'VXLAN-EVPN'), - )), + (TYPE_VXLAN, 'VXLAN'), + (TYPE_VXLAN_EVPN, 'VXLAN-EVPN'), + )), ('L2VPN E-VPN', ( - (TYPE_MPLS_EVPN, 'MPLS EVPN'), - (TYPE_PBB_EVPN, 'PBB EVPN'), - )) - + (TYPE_MPLS_EVPN, 'MPLS EVPN'), + (TYPE_PBB_EVPN, 'PBB EVPN'), + )) ) P2P = ( diff --git a/netbox/ipam/tests/test_models.py b/netbox/ipam/tests/test_models.py index 1b5fbadc3..3bd7e8ccb 100644 --- a/netbox/ipam/tests/test_models.py +++ b/netbox/ipam/tests/test_models.py @@ -612,4 +612,3 @@ class TestL2VPNTermination(TestCase): L2VPNTermination.objects.create(l2vpn=l2vpn, assigned_object=vlan) duplicate = L2VPNTermination(l2vpn=l2vpn, assigned_object=vlan) self.assertRaises(ValidationError, duplicate.clean) - From dd6bfed565fc25f841f58bc3f70e339da37f69ba Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 29 Jun 2022 18:37:31 -0500 Subject: [PATCH 115/245] Add migration file --- .../0059_l2vpn_l2vpntermination_and_more.py | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 netbox/ipam/migrations/0059_l2vpn_l2vpntermination_and_more.py diff --git a/netbox/ipam/migrations/0059_l2vpn_l2vpntermination_and_more.py b/netbox/ipam/migrations/0059_l2vpn_l2vpntermination_and_more.py new file mode 100644 index 000000000..a8e5ace25 --- /dev/null +++ b/netbox/ipam/migrations/0059_l2vpn_l2vpntermination_and_more.py @@ -0,0 +1,62 @@ +# Generated by Django 4.0.5 on 2022-06-28 04:57 + +import django.core.serializers.json +from django.db import migrations, models +import django.db.models.deletion +import taggit.managers + + +class Migration(migrations.Migration): + + dependencies = [ + ('contenttypes', '0002_remove_content_type_name'), + ('tenancy', '0007_contact_link'), + ('extras', '0076_configcontext_locations'), + ('ipam', '0058_ipaddress_nat_inside_nonunique'), + ] + + operations = [ + migrations.CreateModel( + name='L2VPN', + fields=[ + ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False)), + ('created', models.DateTimeField(auto_now_add=True, null=True)), + ('last_updated', models.DateTimeField(auto_now=True, null=True)), + ('custom_field_data', models.JSONField(blank=True, default=dict, encoder=django.core.serializers.json.DjangoJSONEncoder)), + ('name', models.CharField(max_length=100, unique=True)), + ('slug', models.SlugField()), + ('type', models.CharField(max_length=50)), + ('identifier', models.BigIntegerField(blank=True, null=True, unique=True)), + ('description', models.TextField(blank=True, null=True)), + ('export_targets', models.ManyToManyField(blank=True, related_name='exporting_l2vpns', to='ipam.routetarget')), + ('import_targets', models.ManyToManyField(blank=True, related_name='importing_l2vpns', to='ipam.routetarget')), + ('tags', taggit.managers.TaggableManager(through='extras.TaggedItem', to='extras.Tag')), + ('tenant', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='l2vpns', to='tenancy.tenant')), + ], + options={ + 'verbose_name': 'L2VPN', + 'ordering': ('identifier', 'name'), + }, + ), + migrations.CreateModel( + name='L2VPNTermination', + fields=[ + ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False)), + ('created', models.DateTimeField(auto_now_add=True, null=True)), + ('last_updated', models.DateTimeField(auto_now=True, null=True)), + ('custom_field_data', models.JSONField(blank=True, default=dict, encoder=django.core.serializers.json.DjangoJSONEncoder)), + ('assigned_object_id', models.PositiveBigIntegerField(blank=True, null=True)), + ('assigned_object_type', models.ForeignKey(blank=True, limit_choices_to=models.Q(models.Q(models.Q(('app_label', 'dcim'), ('model', 'interface')), models.Q(('app_label', 'ipam'), ('model', 'vlan')), models.Q(('app_label', 'virtualization'), ('model', 'vminterface')), _connector='OR')), null=True, on_delete=django.db.models.deletion.PROTECT, related_name='+', to='contenttypes.contenttype')), + ('l2vpn', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='terminations', to='ipam.l2vpn')), + ('tags', taggit.managers.TaggableManager(through='extras.TaggedItem', to='extras.Tag')), + ], + options={ + 'verbose_name': 'L2VPN Termination', + 'ordering': ('l2vpn',), + }, + ), + migrations.AddConstraint( + model_name='l2vpntermination', + constraint=models.UniqueConstraint(fields=('assigned_object_type', 'assigned_object_id'), name='ipam_l2vpntermination_assigned_object'), + ), + ] From 5b397a98272c15cc2dc582abb10d629e8f753429 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Thu, 30 Jun 2022 08:29:08 -0500 Subject: [PATCH 116/245] Add docs --- docs/core-functionality/ipam.md | 5 +++++ docs/development/models.md | 2 ++ docs/models/ipam/l2vpn.md | 19 +++++++++++++++++++ docs/models/ipam/l2vpntermination.md | 12 ++++++++++++ 4 files changed, 38 insertions(+) create mode 100644 docs/models/ipam/l2vpn.md create mode 100644 docs/models/ipam/l2vpntermination.md diff --git a/docs/core-functionality/ipam.md b/docs/core-functionality/ipam.md index 01bb3c76d..c86819380 100644 --- a/docs/core-functionality/ipam.md +++ b/docs/core-functionality/ipam.md @@ -26,3 +26,8 @@ --- {!models/ipam/asn.md!} + +--- + +{!models/ipam/l2vpn.md!} +{!models/ipam/l2vpntermination.md!} diff --git a/docs/development/models.md b/docs/development/models.md index ae1bab7e7..b6b2e4da2 100644 --- a/docs/development/models.md +++ b/docs/development/models.md @@ -45,6 +45,8 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/ * [ipam.FHRPGroup](../models/ipam/fhrpgroup.md) * [ipam.IPAddress](../models/ipam/ipaddress.md) * [ipam.IPRange](../models/ipam/iprange.md) +* [ipam.L2VPN](../models/ipam/l2vpn.md) +* [ipam.L2VPNTermination](../models/ipam/l2vpntermination.md) * [ipam.Prefix](../models/ipam/prefix.md) * [ipam.RouteTarget](../models/ipam/routetarget.md) * [ipam.Service](../models/ipam/service.md) diff --git a/docs/models/ipam/l2vpn.md b/docs/models/ipam/l2vpn.md new file mode 100644 index 000000000..9c50a6407 --- /dev/null +++ b/docs/models/ipam/l2vpn.md @@ -0,0 +1,19 @@ +# L2VPN + +A L2VPN object is NetBox is a representation of a layer 2 bridge technology such as VXLAN, VPLS or EPL. Each L2VPN can be identified by name as well as an optional unique identifier (VNI would be an example). + +Each L2VPN instance must have one of the following type associated with it: + +* VPLS +* VPWS +* EPL +* EVPL +* EP-LAN +* EVP-LAN +* EP-TREE +* EVP-TREE +* VXLAN +* VXLAN EVPN +* MPLS-EVPN +* PBB-EVPN + diff --git a/docs/models/ipam/l2vpntermination.md b/docs/models/ipam/l2vpntermination.md new file mode 100644 index 000000000..9135f72a3 --- /dev/null +++ b/docs/models/ipam/l2vpntermination.md @@ -0,0 +1,12 @@ +# L2VPN Termination + +A L2VPN Termination is the termination point of a L2VPN. Certain types of L2VPN's may only have 2 termination points (point-to-point) while others may have many terminations (multipoint). + +Each termination consists of a L2VPN it is a member of as well as the connected endpoint which can be an interface or a VLAN. + +The following types of L2VPN's are considered point-to-point: + +* VPWS +* EPL +* EP-LAN +* EP-TREE \ No newline at end of file From 65f4895dd652e31e1e9f432dc549b669e7cdb339 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 30 Jun 2022 14:35:41 -0400 Subject: [PATCH 117/245] Add ActionsMixin to __all__ --- netbox/netbox/views/generic/mixins.py | 1 + 1 file changed, 1 insertion(+) diff --git a/netbox/netbox/views/generic/mixins.py b/netbox/netbox/views/generic/mixins.py index 4b3fa0740..8e363f0a5 100644 --- a/netbox/netbox/views/generic/mixins.py +++ b/netbox/netbox/views/generic/mixins.py @@ -3,6 +3,7 @@ from collections import defaultdict from utilities.permissions import get_permission_for_model __all__ = ( + 'ActionsMixin', 'TableMixin', ) From 3a6f46bf38e2a6f8fd8076620c8199311e0c6950 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 30 Jun 2022 15:15:07 -0400 Subject: [PATCH 118/245] Closes #9075: Introduce AbortRequest exception for cleanly interrupting object mutations --- docs/plugins/development/exceptions.md | 28 +++++++++++++ docs/release-notes/version-3.3.md | 1 + mkdocs.yml | 1 + netbox/netbox/api/viewsets/__init__.py | 9 ++++ netbox/netbox/views/generic/bulk_views.py | 46 +++++++++++---------- netbox/netbox/views/generic/object_views.py | 29 +++++++------ netbox/utilities/exceptions.py | 17 +++++++- 7 files changed, 95 insertions(+), 36 deletions(-) create mode 100644 docs/plugins/development/exceptions.md diff --git a/docs/plugins/development/exceptions.md b/docs/plugins/development/exceptions.md new file mode 100644 index 000000000..80f5db258 --- /dev/null +++ b/docs/plugins/development/exceptions.md @@ -0,0 +1,28 @@ +# Exceptions + +The exception classes listed here may be raised by a plugin to alter NetBox's default behavior in various scenarios. + +## `AbortRequest` + +NetBox provides several [generic views](./views.md) and [REST API viewsets](./rest-api.md) which facilitate the creation, modification, and deletion of objects, either individually or in bulk. Under certain conditions, it may be desirable for a plugin to interrupt these actions and cleanly abort the request, reporting an error message to the end user or API consumer. + +For example, a plugin may prohibit the creation of a site with a prohibited name by connecting a receiver to Django's `pre_save` signal for the Site model: + +```python +from django.db.models.signals import pre_save +from django.dispatch import receiver +from dcim.models import Site +from utilities.exceptions import AbortRequest + +PROHIBITED_NAMES = ('foo', 'bar', 'baz') + +@receiver(pre_save, sender=Site) +def test_abort_request(instance, **kwargs): + if instance.name.lower() in PROHIBITED_NAMES: + raise AbortRequest(f"Site name can't be {instance.name}!") +``` + +An error message must be supplied when raising `AbortRequest`. This will be conveyed to the user and should clearly explain the reason for which the request was aborted, as well as any potential remedy. + +!!! tip "Consider custom validation rules" + This exception is intended to be used for handling complex evaluation logic and should be used sparingly. For simple object validation (such as the contrived example above), consider using [custom validation rules](../../customization/custom-validation.md) instead. diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 62644f55f..a0abb81c4 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -35,6 +35,7 @@ ### Plugins API +* [#9075](https://github.com/netbox-community/netbox/issues/9075) - Introduce `AbortRequest` exception for cleanly interrupting object mutations * [#9092](https://github.com/netbox-community/netbox/issues/9092) - Add support for `ObjectChildrenView` generic view * [#9414](https://github.com/netbox-community/netbox/issues/9414) - Add `clone()` method to NetBoxModel for copying instance attributes diff --git a/mkdocs.yml b/mkdocs.yml index 507b25627..88a2794e8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -118,6 +118,7 @@ nav: - REST API: 'plugins/development/rest-api.md' - GraphQL API: 'plugins/development/graphql-api.md' - Background Tasks: 'plugins/development/background-tasks.md' + - Exceptions: 'plugins/development/exceptions.md' - Administration: - Authentication: - Overview: 'administration/authentication/overview.md' diff --git a/netbox/netbox/api/viewsets/__init__.py b/netbox/netbox/api/viewsets/__init__.py index 462c07c6f..2d3780bde 100644 --- a/netbox/netbox/api/viewsets/__init__.py +++ b/netbox/netbox/api/viewsets/__init__.py @@ -11,6 +11,7 @@ from rest_framework.viewsets import ModelViewSet from extras.models import ExportTemplate from netbox.api.exceptions import SerializerNotFound from utilities.api import get_serializer_for_model +from utilities.exceptions import AbortRequest from .mixins import * __all__ = ( @@ -125,6 +126,14 @@ class NetBoxModelViewSet(BulkUpdateModelMixin, BulkDestroyModelMixin, ObjectVali *args, **kwargs ) + except AbortRequest as e: + logger.debug(e.message) + return self.finalize_response( + request, + Response({'detail': e.message}, status=400), + *args, + **kwargs + ) def list(self, request, *args, **kwargs): """ diff --git a/netbox/netbox/views/generic/bulk_views.py b/netbox/netbox/views/generic/bulk_views.py index bb1c2b8e3..82244bcd2 100644 --- a/netbox/netbox/views/generic/bulk_views.py +++ b/netbox/netbox/views/generic/bulk_views.py @@ -1,6 +1,5 @@ import logging import re -from collections import defaultdict from copy import deepcopy from django.contrib import messages @@ -12,11 +11,12 @@ from django.forms import Form, ModelMultipleChoiceField, MultipleHiddenInput from django.http import HttpResponse from django.shortcuts import get_object_or_404, redirect, render from django_tables2.export import TableExport +from django.utils.safestring import mark_safe from extras.models import ExportTemplate from extras.signals import clear_webhooks from utilities.error_handlers import handle_protectederror -from utilities.exceptions import PermissionsViolation +from utilities.exceptions import AbortRequest, PermissionsViolation from utilities.forms import ( BootstrapMixin, BulkRenameForm, ConfirmationForm, CSVDataField, CSVFileField, restrict_form_fields, ) @@ -264,10 +264,10 @@ class BulkCreateView(GetReturnURLMixin, BaseMultiObjectView): except IntegrityError: pass - except PermissionsViolation: - msg = "Object creation failed due to object-level permissions violation" - logger.debug(msg) - form.add_error(None, msg) + except (AbortRequest, PermissionsViolation) as e: + logger.debug(e.message) + form.add_error(None, e.message) + clear_webhooks.send(sender=self) else: logger.debug("Form validation failed") @@ -392,10 +392,9 @@ class BulkImportView(GetReturnURLMixin, BaseMultiObjectView): except ValidationError: clear_webhooks.send(sender=self) - except PermissionsViolation: - msg = "Object import failed due to object-level permissions violation" - logger.debug(msg) - form.add_error(None, msg) + except (AbortRequest, PermissionsViolation) as e: + logger.debug(e.message) + form.add_error(None, e.message) clear_webhooks.send(sender=self) else: @@ -542,10 +541,9 @@ class BulkEditView(GetReturnURLMixin, BaseMultiObjectView): messages.error(self.request, ", ".join(e.messages)) clear_webhooks.send(sender=self) - except PermissionsViolation: - msg = "Object update failed due to object-level permissions violation" - logger.debug(msg) - form.add_error(None, msg) + except (AbortRequest, PermissionsViolation) as e: + logger.debug(e.message) + form.add_error(None, e.message) clear_webhooks.send(sender=self) else: @@ -639,10 +637,9 @@ class BulkRenameView(GetReturnURLMixin, BaseMultiObjectView): messages.success(request, f"Renamed {len(selected_objects)} {model_name}") return redirect(self.get_return_url(request)) - except PermissionsViolation: - msg = "Object update failed due to object-level permissions violation" - logger.debug(msg) - form.add_error(None, msg) + except (AbortRequest, PermissionsViolation) as e: + logger.debug(e.message) + form.add_error(None, e.message) clear_webhooks.send(sender=self) else: @@ -717,11 +714,17 @@ class BulkDeleteView(GetReturnURLMixin, BaseMultiObjectView): if hasattr(obj, 'snapshot'): obj.snapshot() obj.delete() + except ProtectedError as e: logger.info("Caught ProtectedError while attempting to delete objects") handle_protectederror(queryset, request, e) return redirect(self.get_return_url(request)) + except AbortRequest as e: + logger.debug(e.message) + messages.error(request, mark_safe(e.message)) + return redirect(self.get_return_url(request)) + msg = f"Deleted {deleted_count} {model._meta.verbose_name_plural}" logger.info(msg) messages.success(request, msg) @@ -829,10 +832,9 @@ class BulkComponentCreateView(GetReturnURLMixin, BaseMultiObjectView): except IntegrityError: clear_webhooks.send(sender=self) - except PermissionsViolation: - msg = "Component creation failed due to object-level permissions violation" - logger.debug(msg) - form.add_error(None, msg) + except (AbortRequest, PermissionsViolation) as e: + logger.debug(e.message) + form.add_error(None, e.message) clear_webhooks.send(sender=self) if not form.errors: diff --git a/netbox/netbox/views/generic/object_views.py b/netbox/netbox/views/generic/object_views.py index 82867b429..dc078a7e2 100644 --- a/netbox/netbox/views/generic/object_views.py +++ b/netbox/netbox/views/generic/object_views.py @@ -13,7 +13,7 @@ from django.utils.safestring import mark_safe from extras.signals import clear_webhooks from utilities.error_handlers import handle_protectederror -from utilities.exceptions import AbortTransaction, PermissionsViolation +from utilities.exceptions import AbortRequest, AbortTransaction, PermissionsViolation from utilities.forms import ConfirmationForm, ImportForm, restrict_form_fields from utilities.htmx import is_htmx from utilities.permissions import get_permission_for_model @@ -246,10 +246,9 @@ class ObjectImportView(GetReturnURLMixin, BaseObjectView): except AbortTransaction: clear_webhooks.send(sender=self) - except PermissionsViolation: - msg = "Object creation failed due to object-level permissions violation" - logger.debug(msg) - form.add_error(None, msg) + except (AbortRequest, PermissionsViolation) as e: + logger.debug(e.message) + form.add_error(None, e.message) clear_webhooks.send(sender=self) if not model_form.errors: @@ -410,10 +409,9 @@ class ObjectEditView(GetReturnURLMixin, BaseObjectView): return redirect(return_url) - except PermissionsViolation: - msg = "Object save failed due to object-level permissions violation" - logger.debug(msg) - form.add_error(None, msg) + except (AbortRequest, PermissionsViolation) as e: + logger.debug(e.message) + form.add_error(None, e.message) clear_webhooks.send(sender=self) else: @@ -489,11 +487,17 @@ class ObjectDeleteView(GetReturnURLMixin, BaseObjectView): try: obj.delete() + except ProtectedError as e: logger.info("Caught ProtectedError while attempting to delete object") handle_protectederror([obj], request, e) return redirect(obj.get_absolute_url()) + except AbortRequest as e: + logger.debug(e.message) + messages.error(request, mark_safe(e.message)) + return redirect(obj.get_absolute_url()) + msg = 'Deleted {} {}'.format(self.queryset.model._meta.verbose_name, obj) logger.info(msg) messages.success(request, msg) @@ -603,10 +607,9 @@ class ComponentCreateView(GetReturnURLMixin, BaseObjectView): else: return redirect(self.get_return_url(request)) - except PermissionsViolation: - msg = "Component creation failed due to object-level permissions violation" - logger.debug(msg) - form.add_error(None, msg) + except (AbortRequest, PermissionsViolation) as e: + logger.debug(e.message) + form.add_error(None, e.message) clear_webhooks.send(sender=self) return render(request, self.template_name, { diff --git a/netbox/utilities/exceptions.py b/netbox/utilities/exceptions.py index 4ba62bc01..657e90745 100644 --- a/netbox/utilities/exceptions.py +++ b/netbox/utilities/exceptions.py @@ -1,6 +1,13 @@ from rest_framework import status from rest_framework.exceptions import APIException +__all__ = ( + 'AbortRequest', + 'AbortTransaction', + 'PermissionsViolation', + 'RQWorkerNotRunningException', +) + class AbortTransaction(Exception): """ @@ -9,12 +16,20 @@ class AbortTransaction(Exception): pass +class AbortRequest(Exception): + """ + Raised to cleanly abort a request (for example, by a pre_save signal receiver). + """ + def __init__(self, message): + self.message = message + + class PermissionsViolation(Exception): """ Raised when an operation was prevented because it would violate the allowed permissions. """ - pass + message = "Operation failed due to object-level permissions violation" class RQWorkerNotRunningException(APIException): From be778353b7b97b779261f7c06aa9a3d823ff49e4 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 30 Jun 2022 17:13:26 -0400 Subject: [PATCH 119/245] #1099: Restore PoE fields on interface edit form --- netbox/templates/dcim/interface_edit.html | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/netbox/templates/dcim/interface_edit.html b/netbox/templates/dcim/interface_edit.html index ddda1ae31..d6fdfd0e1 100644 --- a/netbox/templates/dcim/interface_edit.html +++ b/netbox/templates/dcim/interface_edit.html @@ -72,6 +72,14 @@ {% endif %} +
    +
    +
    Power over Ethernet (PoE)
    +
    + {% render_field form.poe_mode %} + {% render_field form.poe_type %} +
    +
    802.1Q Switching
    From c6dfdf10e5938e8ee7af18e31663023fb4b8390d Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 1 Jul 2022 11:38:39 -0400 Subject: [PATCH 120/245] Introduce qs_filter_from_constraints() for constructing object permission QS filters --- netbox/netbox/authentication.py | 22 +++++++++------------- netbox/utilities/permissions.py | 24 ++++++++++++++++++++++++ netbox/utilities/querysets.py | 27 +++++++-------------------- 3 files changed, 40 insertions(+), 33 deletions(-) diff --git a/netbox/netbox/authentication.py b/netbox/netbox/authentication.py index 00fb3ee66..c16095fdc 100644 --- a/netbox/netbox/authentication.py +++ b/netbox/netbox/authentication.py @@ -9,7 +9,9 @@ from django.core.exceptions import ImproperlyConfigured from django.db.models import Q from users.models import ObjectPermission -from utilities.permissions import permission_is_exempt, resolve_permission, resolve_permission_ct +from utilities.permissions import ( + permission_is_exempt, qs_filter_from_constraints, resolve_permission, resolve_permission_ct, +) UserModel = get_user_model() @@ -99,8 +101,10 @@ class ObjectPermissionMixin: if not user_obj.is_active or user_obj.is_anonymous: return False + object_permissions = self.get_all_permissions(user_obj) + # If no applicable ObjectPermissions have been created for this user/permission, deny permission - if perm not in self.get_all_permissions(user_obj): + if perm not in object_permissions: return False # If no object has been specified, grant permission. (The presence of a permission in this set tells @@ -113,21 +117,13 @@ class ObjectPermissionMixin: if model._meta.label_lower != '.'.join((app_label, model_name)): raise ValueError(f"Invalid permission {perm} for model {model}") - # Compile a query filter that matches all instances of the specified model - obj_perm_constraints = self.get_all_permissions(user_obj)[perm] - constraints = Q() - for perm_constraints in obj_perm_constraints: - if perm_constraints: - constraints |= Q(**perm_constraints) - else: - # Found ObjectPermission with null constraints; allow model-level access - constraints = Q() - break + # Compile a QuerySet filter that matches all instances of the specified model + qs_filter = qs_filter_from_constraints(object_permissions[perm]) # Permission to perform the requested action on the object depends on whether the specified object matches # the specified constraints. Note that this check is made against the *database* record representing the object, # not the instance itself. - return model.objects.filter(constraints, pk=obj.pk).exists() + return model.objects.filter(qs_filter, pk=obj.pk).exists() class ObjectPermissionBackend(ObjectPermissionMixin, ModelBackend): diff --git a/netbox/utilities/permissions.py b/netbox/utilities/permissions.py index b11bf504a..123df9e45 100644 --- a/netbox/utilities/permissions.py +++ b/netbox/utilities/permissions.py @@ -1,5 +1,14 @@ from django.conf import settings from django.contrib.contenttypes.models import ContentType +from django.db.models import Q + +__all__ = ( + 'get_permission_for_model', + 'permission_is_exempt', + 'qs_filter_from_constraints', + 'resolve_permission', + 'resolve_permission_ct', +) def get_permission_for_model(model, action): @@ -69,3 +78,18 @@ def permission_is_exempt(name): return True return False + + +def qs_filter_from_constraints(constraints): + """ + Construct a Q filter object from an iterable of ObjectPermission constraints. + """ + params = Q() + for constraint in constraints: + if constraint: + params |= Q(**constraint) + else: + # Found null constraint; permit model-level access + return Q() + + return params diff --git a/netbox/utilities/querysets.py b/netbox/utilities/querysets.py index 97d2e8779..8ec6012bf 100644 --- a/netbox/utilities/querysets.py +++ b/netbox/utilities/querysets.py @@ -1,6 +1,6 @@ -from django.db.models import Q, QuerySet +from django.db.models import QuerySet -from utilities.permissions import permission_is_exempt +from utilities.permissions import permission_is_exempt, qs_filter_from_constraints class RestrictedQuerySet(QuerySet): @@ -28,23 +28,10 @@ class RestrictedQuerySet(QuerySet): # Filter the queryset to include only objects with allowed attributes else: - attrs = Q() - for perm_attrs in user._object_perm_cache[permission_required]: - if type(perm_attrs) is list: - for p in perm_attrs: - attrs |= Q(**p) - elif perm_attrs: - attrs |= Q(**perm_attrs) - else: - # Any permission with null constraints grants access to _all_ instances - attrs = Q() - break - else: - # for else, when no break - # avoid duplicates when JOIN on many-to-many fields without using DISTINCT. - # DISTINCT acts globally on the entire request, which may not be desirable. - allowed_objects = self.model.objects.filter(attrs) - attrs = Q(pk__in=allowed_objects) - qs = self.filter(attrs) + attrs = qs_filter_from_constraints(user._object_perm_cache[permission_required]) + # #8715: Avoid duplicates when JOIN on many-to-many fields without using DISTINCT. + # DISTINCT acts globally on the entire request, which may not be desirable. + allowed_objects = self.model.objects.filter(attrs) + qs = self.filter(pk__in=allowed_objects) return qs From 12c138b341faff6d2413c620488e124cbbacf8ec Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 1 Jul 2022 13:34:10 -0400 Subject: [PATCH 121/245] Closes #9074: Enable referencing the current user when evaluating permission constraints --- docs/administration/permissions.md | 2 +- docs/models/users/objectpermission.md | 14 ++++++++++++++ docs/release-notes/version-3.3.md | 2 ++ netbox/netbox/authentication.py | 6 +++++- netbox/users/admin/forms.py | 9 ++++++--- netbox/users/constants.py | 2 ++ netbox/utilities/permissions.py | 15 +++++++++++++-- netbox/utilities/querysets.py | 6 +++++- 8 files changed, 48 insertions(+), 8 deletions(-) diff --git a/docs/administration/permissions.md b/docs/administration/permissions.md index f859266af..60717c28a 100644 --- a/docs/administration/permissions.md +++ b/docs/administration/permissions.md @@ -4,7 +4,7 @@ NetBox v2.9 introduced a new object-based permissions framework, which replaces {!models/users/objectpermission.md!} -### Example Constraint Definitions +#### Example Constraint Definitions | Constraints | Description | | ----------- | ----------- | diff --git a/docs/models/users/objectpermission.md b/docs/models/users/objectpermission.md index 48970dd05..075a2cae5 100644 --- a/docs/models/users/objectpermission.md +++ b/docs/models/users/objectpermission.md @@ -53,3 +53,17 @@ To achieve a logical OR with a different set of constraints, define multiple obj ``` Additionally, where multiple permissions have been assigned for an object type, their collective constraints will be merged using a logical "OR" operation. + +### Tokens + +!!! info "This feature was introduced in NetBox v3.3" + +When defining a permission constraint, administrators may use the special token `$user` to reference the current user at the time of evaluation. This can be helpful to restrict users to editing only their own journal entries, for example. Such a constraint might be defined as: + +```json +{ + "created_by": "$user" +} +``` + +The `$user` token can be used only as a constraint value, or as an item within a list of values. It cannot be modified or extended to reference specific user attributes. diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index a0abb81c4..ea9e67a38 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -15,6 +15,8 @@ #### Restrict API Tokens by Client IP ([#8233](https://github.com/netbox-community/netbox/issues/8233)) +#### Reference User in Permission Constraints ([#9074](https://github.com/netbox-community/netbox/issues/9074)) + ### Enhancements * [#1202](https://github.com/netbox-community/netbox/issues/1202) - Support overlapping assignment of NAT IP addresses diff --git a/netbox/netbox/authentication.py b/netbox/netbox/authentication.py index c16095fdc..62512943e 100644 --- a/netbox/netbox/authentication.py +++ b/netbox/netbox/authentication.py @@ -8,6 +8,7 @@ from django.contrib.auth.models import Group, AnonymousUser from django.core.exceptions import ImproperlyConfigured from django.db.models import Q +from users.constants import CONSTRAINT_TOKEN_USER from users.models import ObjectPermission from utilities.permissions import ( permission_is_exempt, qs_filter_from_constraints, resolve_permission, resolve_permission_ct, @@ -118,7 +119,10 @@ class ObjectPermissionMixin: raise ValueError(f"Invalid permission {perm} for model {model}") # Compile a QuerySet filter that matches all instances of the specified model - qs_filter = qs_filter_from_constraints(object_permissions[perm]) + tokens = { + CONSTRAINT_TOKEN_USER: user_obj, + } + qs_filter = qs_filter_from_constraints(object_permissions[perm], tokens) # Permission to perform the requested action on the object depends on whether the specified object matches # the specified constraints. Note that this check is made against the *database* record representing the object, diff --git a/netbox/users/admin/forms.py b/netbox/users/admin/forms.py index bc3d44862..540735ecc 100644 --- a/netbox/users/admin/forms.py +++ b/netbox/users/admin/forms.py @@ -3,11 +3,11 @@ from django.contrib.auth.models import Group, User from django.contrib.admin.widgets import FilteredSelectMultiple from django.contrib.contenttypes.models import ContentType from django.core.exceptions import FieldError, ValidationError -from django.db.models import Q -from users.constants import OBJECTPERMISSION_OBJECT_TYPES +from users.constants import CONSTRAINT_TOKEN_USER, OBJECTPERMISSION_OBJECT_TYPES from users.models import ObjectPermission, Token from utilities.forms.fields import ContentTypeMultipleChoiceField +from utilities.permissions import qs_filter_from_constraints __all__ = ( 'GroupAdminForm', @@ -125,7 +125,10 @@ class ObjectPermissionForm(forms.ModelForm): for ct in object_types: model = ct.model_class() try: - model.objects.filter(*[Q(**c) for c in constraints]).exists() + tokens = { + CONSTRAINT_TOKEN_USER: 0, # Replace token with a null user ID + } + model.objects.filter(qs_filter_from_constraints(constraints, tokens)).exists() except FieldError as e: raise ValidationError({ 'constraints': f'Invalid filter for {model}: {e}' diff --git a/netbox/users/constants.py b/netbox/users/constants.py index e6917c482..1e6e7c71c 100644 --- a/netbox/users/constants.py +++ b/netbox/users/constants.py @@ -6,3 +6,5 @@ OBJECTPERMISSION_OBJECT_TYPES = Q( Q(app_label='auth', model__in=['group', 'user']) | Q(app_label='users', model__in=['objectpermission', 'token']) ) + +CONSTRAINT_TOKEN_USER = '$user' diff --git a/netbox/utilities/permissions.py b/netbox/utilities/permissions.py index 123df9e45..b20aafce0 100644 --- a/netbox/utilities/permissions.py +++ b/netbox/utilities/permissions.py @@ -80,14 +80,25 @@ def permission_is_exempt(name): return False -def qs_filter_from_constraints(constraints): +def qs_filter_from_constraints(constraints, tokens=None): """ Construct a Q filter object from an iterable of ObjectPermission constraints. + + Args: + tokens: A dictionary mapping string tokens to be replaced with a value. """ + if tokens is None: + tokens = {} + + def _replace_tokens(value, tokens): + if type(value) is list: + return list(map(lambda v: tokens.get(v, v), value)) + return tokens.get(value, value) + params = Q() for constraint in constraints: if constraint: - params |= Q(**constraint) + params |= Q(**{k: _replace_tokens(v, tokens) for k, v in constraint.items()}) else: # Found null constraint; permit model-level access return Q() diff --git a/netbox/utilities/querysets.py b/netbox/utilities/querysets.py index 8ec6012bf..955a10d64 100644 --- a/netbox/utilities/querysets.py +++ b/netbox/utilities/querysets.py @@ -1,5 +1,6 @@ from django.db.models import QuerySet +from users.constants import CONSTRAINT_TOKEN_USER from utilities.permissions import permission_is_exempt, qs_filter_from_constraints @@ -28,7 +29,10 @@ class RestrictedQuerySet(QuerySet): # Filter the queryset to include only objects with allowed attributes else: - attrs = qs_filter_from_constraints(user._object_perm_cache[permission_required]) + tokens = { + CONSTRAINT_TOKEN_USER: user, + } + attrs = qs_filter_from_constraints(user._object_perm_cache[permission_required], tokens) # #8715: Avoid duplicates when JOIN on many-to-many fields without using DISTINCT. # DISTINCT acts globally on the entire request, which may not be desirable. allowed_objects = self.model.objects.filter(attrs) From c11af40a061ac5346d7d44579dd2decad4826001 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 1 Jul 2022 13:52:37 -0400 Subject: [PATCH 122/245] prepare_cloned_fields() should always return a QueryDict --- netbox/utilities/utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/utilities/utils.py b/netbox/utilities/utils.py index 731b67e43..51c411004 100644 --- a/netbox/utilities/utils.py +++ b/netbox/utilities/utils.py @@ -286,7 +286,7 @@ def prepare_cloned_fields(instance): """ # Generate the clone attributes from the instance if not hasattr(instance, 'clone'): - return None + return QueryDict() attrs = instance.clone() # Prepare querydict parameters From a57398b0d678405d68f785f08d0e2a393eb21768 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 1 Jul 2022 14:45:22 -0400 Subject: [PATCH 123/245] Closes #9647: Introduce customfield_value template tag --- docs/plugins/development/templates.md | 2 ++ docs/release-notes/version-3.3.md | 1 + .../templates/inc/panels/custom_fields.html | 28 +------------------ .../templates/builtins/customfield_value.html | 27 ++++++++++++++++++ .../utilities/templatetags/builtins/tags.py | 15 ++++++++++ 5 files changed, 46 insertions(+), 27 deletions(-) create mode 100644 netbox/utilities/templates/builtins/customfield_value.html diff --git a/docs/plugins/development/templates.md b/docs/plugins/development/templates.md index 64616c442..20838149f 100644 --- a/docs/plugins/development/templates.md +++ b/docs/plugins/development/templates.md @@ -215,6 +215,8 @@ The following custom template tags are available in NetBox. ::: utilities.templatetags.builtins.tags.checkmark +::: utilities.templatetags.builtins.tags.customfield_value + ::: utilities.templatetags.builtins.tags.tag ## Filters diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index ea9e67a38..f5cb8eee1 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -40,6 +40,7 @@ * [#9075](https://github.com/netbox-community/netbox/issues/9075) - Introduce `AbortRequest` exception for cleanly interrupting object mutations * [#9092](https://github.com/netbox-community/netbox/issues/9092) - Add support for `ObjectChildrenView` generic view * [#9414](https://github.com/netbox-community/netbox/issues/9414) - Add `clone()` method to NetBoxModel for copying instance attributes +* [#9647](https://github.com/netbox-community/netbox/issues/9647) - Introduce `customfield_value` template tag ### Other Changes diff --git a/netbox/templates/inc/panels/custom_fields.html b/netbox/templates/inc/panels/custom_fields.html index b18d44030..90059447f 100644 --- a/netbox/templates/inc/panels/custom_fields.html +++ b/netbox/templates/inc/panels/custom_fields.html @@ -16,33 +16,7 @@ {{ field }} - {% if field.type == 'integer' and value is not None %} - {{ value }} - {% elif field.type == 'longtext' and value %} - {{ value|markdown }} - {% elif field.type == 'boolean' and value == True %} - {% checkmark value true="True" %} - {% elif field.type == 'boolean' and value == False %} - {% checkmark value false="False" %} - {% elif field.type == 'url' and value %} - {{ value|truncatechars:70 }} - {% elif field.type == 'json' and value %} - 
    {{ value|json }}
    - {% elif field.type == 'multiselect' and value %} - {{ value|join:", " }} - {% elif field.type == 'object' and value %} - {{ value|linkify }} - {% elif field.type == 'multiobject' and value %} - {% for obj in value %} - {{ obj|linkify }}{% if not forloop.last %}
    {% endif %} - {% endfor %} - {% elif value %} - {{ value }} - {% elif field.required %} - Not defined - {% else %} - {{ ''|placeholder }} - {% endif %} + {% customfield_value field value %} {% endfor %} diff --git a/netbox/utilities/templates/builtins/customfield_value.html b/netbox/utilities/templates/builtins/customfield_value.html new file mode 100644 index 000000000..8fedb03d5 --- /dev/null +++ b/netbox/utilities/templates/builtins/customfield_value.html @@ -0,0 +1,27 @@ +{% if field.type == 'integer' and value is not None %} + {{ value }} +{% elif field.type == 'longtext' and value %} + {{ value|markdown }} +{% elif field.type == 'boolean' and value == True %} + {% checkmark value true="True" %} +{% elif field.type == 'boolean' and value == False %} + {% checkmark value false="False" %} +{% elif field.type == 'url' and value %} + {{ value|truncatechars:70 }} +{% elif field.type == 'json' and value %} + 
    {{ value|json }}
    +{% elif field.type == 'multiselect' and value %} + {{ value|join:", " }} +{% elif field.type == 'object' and value %} + {{ value|linkify }} +{% elif field.type == 'multiobject' and value %} + {% for object in value %} + {{ object|linkify }}{% if not forloop.last %}
    {% endif %} + {% endfor %} +{% elif value %} + {{ value }} +{% elif field.required %} + Not defined +{% else %} + {{ ''|placeholder }} +{% endif %} diff --git a/netbox/utilities/templatetags/builtins/tags.py b/netbox/utilities/templatetags/builtins/tags.py index 666b6a31c..ed464b332 100644 --- a/netbox/utilities/templatetags/builtins/tags.py +++ b/netbox/utilities/templatetags/builtins/tags.py @@ -18,6 +18,21 @@ def tag(value, viewname=None): } +@register.inclusion_tag('builtins/customfield_value.html') +def customfield_value(customfield, value): + """ + Render a custom field value according to the field type. + + Args: + customfield: A CustomField instance + value: The custom field value applied to an object + """ + return { + 'customfield': customfield, + 'value': value, + } + + @register.inclusion_tag('builtins/badge.html') def badge(value, bg_color=None, show_empty=False): """ From a5124ab9c835896ff434812bf870d1add82a3afe Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 1 Jul 2022 15:10:31 -0400 Subject: [PATCH 124/245] Closes #8511: Enable custom fields and tags for circuit terminations --- docs/release-notes/version-3.3.md | 3 + netbox/circuits/api/serializers.py | 4 +- netbox/circuits/filtersets.py | 2 +- netbox/circuits/forms/models.py | 4 +- netbox/circuits/graphql/types.py | 3 +- ...7_circuittermination_tags_custom_fields.py | 24 +++ netbox/circuits/models/circuits.py | 13 +- netbox/templates/circuits/circuit.html | 140 +++++++++--------- .../circuits/circuittermination_edit.html | 8 + .../circuits/inc/circuit_termination.html | 33 ++++- 10 files changed, 155 insertions(+), 79 deletions(-) create mode 100644 netbox/circuits/migrations/0037_circuittermination_tags_custom_fields.py diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index f5cb8eee1..d158e6cf9 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -28,6 +28,7 @@ * [#8222](https://github.com/netbox-community/netbox/issues/8222) - Enable the assignment of a VM to a specific host device within a cluster * [#8471](https://github.com/netbox-community/netbox/issues/8471) - Add `status` field to Cluster * [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping +* [#8511](https://github.com/netbox-community/netbox/issues/8511) - Enable custom fields and tags for circuit terminations * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results * [#9070](https://github.com/netbox-community/netbox/issues/9070) - Hide navigation menu items based on user permissions * [#9166](https://github.com/netbox-community/netbox/issues/9166) - Add UI visibility toggle for custom fields @@ -51,6 +52,8 @@ * circuits.Circuit * Added optional `termination_date` field +* circuits.CircuitTermination + * Added 'custom_fields' and 'tags' fields * dcim.Device * The `position` field has been changed from an integer to a decimal * dcim.DeviceType diff --git a/netbox/circuits/api/serializers.py b/netbox/circuits/api/serializers.py index 2bb3cd266..844cfce89 100644 --- a/netbox/circuits/api/serializers.py +++ b/netbox/circuits/api/serializers.py @@ -98,7 +98,7 @@ class CircuitSerializer(NetBoxModelSerializer): ] -class CircuitTerminationSerializer(ValidatedModelSerializer, LinkTerminationSerializer): +class CircuitTerminationSerializer(NetBoxModelSerializer, LinkTerminationSerializer): url = serializers.HyperlinkedIdentityField(view_name='circuits-api:circuittermination-detail') circuit = NestedCircuitSerializer() site = NestedSiteSerializer(required=False, allow_null=True) @@ -110,5 +110,5 @@ class CircuitTerminationSerializer(ValidatedModelSerializer, LinkTerminationSeri fields = [ 'id', 'url', 'display', 'circuit', 'term_side', 'site', 'provider_network', 'port_speed', 'upstream_speed', 'xconnect_id', 'pp_info', 'description', 'mark_connected', 'cable', 'link_peer', 'link_peer_type', - '_occupied', 'created', 'last_updated', + '_occupied', 'tags', 'custom_fields', 'created', 'last_updated', ] diff --git a/netbox/circuits/filtersets.py b/netbox/circuits/filtersets.py index 67a0d1b02..a74ff5c5a 100644 --- a/netbox/circuits/filtersets.py +++ b/netbox/circuits/filtersets.py @@ -198,7 +198,7 @@ class CircuitFilterSet(NetBoxModelFilterSet, TenancyFilterSet, ContactModelFilte ).distinct() -class CircuitTerminationFilterSet(ChangeLoggedModelFilterSet, CableTerminationFilterSet): +class CircuitTerminationFilterSet(NetBoxModelFilterSet, CableTerminationFilterSet): q = django_filters.CharFilter( method='search', label='Search', diff --git a/netbox/circuits/forms/models.py b/netbox/circuits/forms/models.py index 907c39586..7bd7abbbf 100644 --- a/netbox/circuits/forms/models.py +++ b/netbox/circuits/forms/models.py @@ -116,7 +116,7 @@ class CircuitForm(TenancyForm, NetBoxModelForm): } -class CircuitTerminationForm(BootstrapMixin, forms.ModelForm): +class CircuitTerminationForm(NetBoxModelForm): provider = DynamicModelChoiceField( queryset=Provider.objects.all(), required=False, @@ -161,7 +161,7 @@ class CircuitTerminationForm(BootstrapMixin, forms.ModelForm): model = CircuitTermination fields = [ 'provider', 'circuit', 'term_side', 'region', 'site_group', 'site', 'provider_network', 'mark_connected', - 'port_speed', 'upstream_speed', 'xconnect_id', 'pp_info', 'description', + 'port_speed', 'upstream_speed', 'xconnect_id', 'pp_info', 'description', 'tags', ] help_texts = { 'port_speed': "Physical circuit speed", diff --git a/netbox/circuits/graphql/types.py b/netbox/circuits/graphql/types.py index 027b53203..094b78d07 100644 --- a/netbox/circuits/graphql/types.py +++ b/netbox/circuits/graphql/types.py @@ -1,4 +1,5 @@ from circuits import filtersets, models +from extras.graphql.mixins import CustomFieldsMixin, TagsMixin from netbox.graphql.types import ObjectType, OrganizationalObjectType, NetBoxObjectType __all__ = ( @@ -10,7 +11,7 @@ __all__ = ( ) -class CircuitTerminationType(ObjectType): +class CircuitTerminationType(CustomFieldsMixin, TagsMixin, ObjectType): class Meta: model = models.CircuitTermination diff --git a/netbox/circuits/migrations/0037_circuittermination_tags_custom_fields.py b/netbox/circuits/migrations/0037_circuittermination_tags_custom_fields.py new file mode 100644 index 000000000..c87bc4219 --- /dev/null +++ b/netbox/circuits/migrations/0037_circuittermination_tags_custom_fields.py @@ -0,0 +1,24 @@ +import django.core.serializers.json +from django.db import migrations, models +import taggit.managers + + +class Migration(migrations.Migration): + + dependencies = [ + ('extras', '0076_configcontext_locations'), + ('circuits', '0036_circuit_termination_date'), + ] + + operations = [ + migrations.AddField( + model_name='circuittermination', + name='custom_field_data', + field=models.JSONField(blank=True, default=dict, encoder=django.core.serializers.json.DjangoJSONEncoder), + ), + migrations.AddField( + model_name='circuittermination', + name='tags', + field=taggit.managers.TaggableManager(through='extras.TaggedItem', to='extras.Tag'), + ), + ] diff --git a/netbox/circuits/models/circuits.py b/netbox/circuits/models/circuits.py index 5df6f1b85..cf6ffc503 100644 --- a/netbox/circuits/models/circuits.py +++ b/netbox/circuits/models/circuits.py @@ -5,7 +5,9 @@ from django.urls import reverse from circuits.choices import * from dcim.models import LinkTermination -from netbox.models import ChangeLoggedModel, OrganizationalModel, NetBoxModel +from netbox.models import ( + ChangeLoggedModel, CustomFieldsMixin, CustomLinksMixin, OrganizationalModel, NetBoxModel, TagsMixin, +) from netbox.models.features import WebhooksMixin __all__ = ( @@ -141,7 +143,14 @@ class Circuit(NetBoxModel): return CircuitStatusChoices.colors.get(self.status) -class CircuitTermination(WebhooksMixin, ChangeLoggedModel, LinkTermination): +class CircuitTermination( + CustomFieldsMixin, + CustomLinksMixin, + TagsMixin, + WebhooksMixin, + ChangeLoggedModel, + LinkTermination +): circuit = models.ForeignKey( to='circuits.Circuit', on_delete=models.CASCADE, diff --git a/netbox/templates/circuits/circuit.html b/netbox/templates/circuits/circuit.html index a4c41f871..a11139032 100644 --- a/netbox/templates/circuits/circuit.html +++ b/netbox/templates/circuits/circuit.html @@ -8,74 +8,78 @@ {% endblock %} {% block content %} -
    -
    -
    -
    - Circuit -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Provider{{ object.provider|linkify }}
    Circuit ID{{ object.cid }}
    Type{{ object.type|linkify }}
    Status{% badge object.get_status_display bg_color=object.get_status_color %}
    Tenant - {% if object.tenant.group %} - {{ object.tenant.group|linkify }} / - {% endif %} - {{ object.tenant|linkify|placeholder }} -
    Install Date{{ object.install_date|annotated_date|placeholder }}
    Termination Date{{ object.termination_date|annotated_date|placeholder }}
    Commit Rate{{ object.commit_rate|humanize_speed|placeholder }}
    Description{{ object.description|placeholder }}
    -
    +
    +
    +
    +
    Circuit
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Provider{{ object.provider|linkify }}
    Circuit ID{{ object.cid }}
    Type{{ object.type|linkify }}
    Status{% badge object.get_status_display bg_color=object.get_status_color %}
    Tenant + {% if object.tenant.group %} + {{ object.tenant.group|linkify }} / + {% endif %} + {{ object.tenant|linkify|placeholder }} +
    Install Date{{ object.install_date|annotated_date|placeholder }}
    Termination Date{{ object.termination_date|annotated_date|placeholder }}
    Commit Rate{{ object.commit_rate|humanize_speed|placeholder }}
    Description{{ object.description|placeholder }}
    - {% include 'inc/panels/custom_fields.html' %} - {% include 'inc/panels/tags.html' %} - {% include 'inc/panels/comments.html' %} - {% plugin_left_page object %} -
    -
    - {% include 'circuits/inc/circuit_termination.html' with termination=object.termination_a side='A' %} - {% include 'circuits/inc/circuit_termination.html' with termination=object.termination_z side='Z' %} - {% include 'inc/panels/contacts.html' %} - {% include 'inc/panels/image_attachments.html' %} - {% plugin_right_page object %} -
    -
    -
    -
    - {% plugin_full_width_page object %} +
    + {% include 'inc/panels/custom_fields.html' %} + {% include 'inc/panels/tags.html' %} + {% plugin_left_page object %}
    -
    +
    + {% include 'inc/panels/comments.html' %} + {% include 'inc/panels/contacts.html' %} + {% include 'inc/panels/image_attachments.html' %} + {% plugin_right_page object %} +
    +
    +
    +
    + {% include 'circuits/inc/circuit_termination.html' with termination=object.termination_a side='A' %} +
    +
    + {% include 'circuits/inc/circuit_termination.html' with termination=object.termination_z side='Z' %} +
    +
    +
    +
    + {% plugin_full_width_page object %} +
    +
    {% endblock %} diff --git a/netbox/templates/circuits/circuittermination_edit.html b/netbox/templates/circuits/circuittermination_edit.html index f8393f945..606e12b5e 100644 --- a/netbox/templates/circuits/circuittermination_edit.html +++ b/netbox/templates/circuits/circuittermination_edit.html @@ -10,6 +10,7 @@ {% render_field form.provider %} {% render_field form.circuit %} {% render_field form.term_side %} + {% render_field form.tags %} {% render_field form.mark_connected %} {% with providernetwork_tab_active=form.initial.provider_network %}
    @@ -47,6 +48,13 @@ {% render_field form.pp_info %} {% render_field form.description %}
    + +
    +
    +
    Custom Fields
    +
    + {% render_custom_fields form %} +
    {% endblock %} {# Override buttons block, 'Create & Add Another'/'_addanother' is not needed on a circuit. #} diff --git a/netbox/templates/circuits/inc/circuit_termination.html b/netbox/templates/circuits/inc/circuit_termination.html index b673cd4a3..f6bb377ec 100644 --- a/netbox/templates/circuits/inc/circuit_termination.html +++ b/netbox/templates/circuits/inc/circuit_termination.html @@ -2,7 +2,6 @@
    - Termination - {{ side }} Side
    {% if not termination and perms.circuits.add_circuittermination %} @@ -10,10 +9,10 @@ {% endif %} {% if termination and perms.circuits.change_circuittermination %} - + Edit - + Swap {% endif %} @@ -23,6 +22,7 @@ {% endif %}
    +
    Termination {{ side }}
    {% if termination %} @@ -110,6 +110,33 @@ Description {{ termination.description|placeholder }} + + Tags + + {% for tag in termination.tags.all %} + {% tag tag %} + {% empty %} + {{ ''|placeholder }} + {% endfor %} + + + {% for group_name, fields in termination.get_custom_fields_by_group.items %} + + + {{ group_name|default:"Custom Fields" }} + + + {% for field, value in fields.items %} + + + {{ field }} + + + {% customfield_value field value %} + + + {% endfor %} + {% endfor %} {% else %} None From 23f391c5b59d5e01321cf5b83e5337c45f9a09ac Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 1 Jul 2022 15:52:16 -0400 Subject: [PATCH 125/245] Closes #9228: Add serialize_object() method to ChangeLoggingMixin --- docs/release-notes/version-3.3.md | 1 + netbox/extras/webhooks.py | 13 ++++++++++--- netbox/netbox/models/features.py | 14 +++++++++++--- 3 files changed, 22 insertions(+), 6 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index d158e6cf9..0e3cfd35f 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -40,6 +40,7 @@ * [#9075](https://github.com/netbox-community/netbox/issues/9075) - Introduce `AbortRequest` exception for cleanly interrupting object mutations * [#9092](https://github.com/netbox-community/netbox/issues/9092) - Add support for `ObjectChildrenView` generic view +* [#9228](https://github.com/netbox-community/netbox/issues/9228) - Subclasses of `ChangeLoggingMixin` can override `serialize_object()` to control JSON serialization for change logging * [#9414](https://github.com/netbox-community/netbox/issues/9414) - Add `clone()` method to NetBoxModel for copying instance attributes * [#9647](https://github.com/netbox-community/netbox/issues/9647) - Introduce `customfield_value` template tag diff --git a/netbox/extras/webhooks.py b/netbox/extras/webhooks.py index d8739cb55..334539026 100644 --- a/netbox/extras/webhooks.py +++ b/netbox/extras/webhooks.py @@ -1,6 +1,5 @@ import hashlib import hmac -from collections import defaultdict from django.contrib.contenttypes.models import ContentType from django.utils import timezone @@ -27,10 +26,18 @@ def serialize_for_webhook(instance): def get_snapshots(instance, action): - return { + snapshots = { 'prechange': getattr(instance, '_prechange_snapshot', None), - 'postchange': serialize_object(instance) if action != ObjectChangeActionChoices.ACTION_DELETE else None, + 'postchange': None, } + if action != ObjectChangeActionChoices.ACTION_DELETE: + # Use model's serialize() method if defined; fall back to serialize_object + if hasattr(instance, 'serialize_object'): + snapshots['postchange'] = instance.serialize_object() + else: + snapshots['postchange'] = serialize_object(instance) + + return snapshots def generate_signature(request_body, secret): diff --git a/netbox/netbox/models/features.py b/netbox/netbox/models/features.py index 817da526b..6b2ee1f94 100644 --- a/netbox/netbox/models/features.py +++ b/netbox/netbox/models/features.py @@ -49,11 +49,19 @@ class ChangeLoggingMixin(models.Model): class Meta: abstract = True + def serialize_object(self): + """ + Return a JSON representation of the instance. Models can override this method to replace or extend the default + serialization logic provided by the `serialize_object()` utility function. + """ + return serialize_object(self) + def snapshot(self): """ - Save a snapshot of the object's current state in preparation for modification. + Save a snapshot of the object's current state in preparation for modification. The snapshot is saved as + `_prechange_snapshot` on the instance. """ - self._prechange_snapshot = serialize_object(self) + self._prechange_snapshot = self.serialize_object() def to_objectchange(self, action): """ @@ -69,7 +77,7 @@ class ChangeLoggingMixin(models.Model): if hasattr(self, '_prechange_snapshot'): objectchange.prechange_data = self._prechange_snapshot if action in (ObjectChangeActionChoices.ACTION_CREATE, ObjectChangeActionChoices.ACTION_UPDATE): - objectchange.postchange_data = serialize_object(self) + objectchange.postchange_data = self.serialize_object() return objectchange From 277c2ff8697ea85854bee0cb56a8964331331069 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 1 Jul 2022 16:36:24 -0400 Subject: [PATCH 126/245] Closes #8171: Populate next available address when cloning an IP --- docs/release-notes/version-3.3.md | 1 + netbox/ipam/models/ip.py | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 0e3cfd35f..92401c217 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -25,6 +25,7 @@ * [#5303](https://github.com/netbox-community/netbox/issues/5303) - A virtual machine may be assigned to a site and/or cluster * [#7120](https://github.com/netbox-community/netbox/issues/7120) - Add `termination_date` field to Circuit * [#7744](https://github.com/netbox-community/netbox/issues/7744) - Add `status` field to Location +* [#8171](https://github.com/netbox-community/netbox/issues/8171) - Populate next available address when cloning an IP * [#8222](https://github.com/netbox-community/netbox/issues/8222) - Enable the assignment of a VM to a specific host device within a cluster * [#8471](https://github.com/netbox-community/netbox/issues/8471) - Add `status` field to Cluster * [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping diff --git a/netbox/ipam/models/ip.py b/netbox/ipam/models/ip.py index db662f49c..0bc0e2364 100644 --- a/netbox/ipam/models/ip.py +++ b/netbox/ipam/models/ip.py @@ -857,6 +857,25 @@ class IPAddress(NetBoxModel): address__net_host=str(self.address.ip) ).exclude(pk=self.pk) + def get_next_available_ip(self): + """ + Return the next available IP address within this IP's network (if any) + """ + if self.address and self.address.broadcast: + start_ip = self.address.ip + 1 + end_ip = self.address.broadcast - 1 + if start_ip <= end_ip: + available_ips = netaddr.IPSet(netaddr.IPRange(start_ip, end_ip)) + available_ips -= netaddr.IPSet([ + address.ip for address in IPAddress.objects.filter( + vrf=self.vrf, + address__gt=self.address, + address__net_contained_or_equal=self.address.cidr + ).values_list('address', flat=True) + ]) + if available_ips: + return next(iter(available_ips)) + def clean(self): super().clean() @@ -907,6 +926,15 @@ class IPAddress(NetBoxModel): super().save(*args, **kwargs) + def clone(self): + attrs = super().clone() + + # Populate the address field with the next available IP (if any) + if next_available_ip := self.get_next_available_ip(): + attrs['address'] = next_available_ip + + return attrs + def to_objectchange(self, action): objectchange = super().to_objectchange(action) objectchange.related_object = self.assigned_object From b1729f212799a468184ddf65faedb14a4a9555c3 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 08:02:29 -0500 Subject: [PATCH 127/245] Change Virtual Circuits to L2VPN Co-authored-by: Jeremy Stretch --- netbox/ipam/api/serializers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/ipam/api/serializers.py b/netbox/ipam/api/serializers.py index 36102f853..d331a0f7d 100644 --- a/netbox/ipam/api/serializers.py +++ b/netbox/ipam/api/serializers.py @@ -439,7 +439,7 @@ class ServiceSerializer(NetBoxModelSerializer): ] # -# Virtual Circuits +# L2VPN # From aa856e75e8897d8a4a32b571ae7f44521b0f8695 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 08:02:44 -0500 Subject: [PATCH 128/245] Change Virtual Circuits to L2VPN Co-authored-by: Jeremy Stretch --- netbox/ipam/api/nested_serializers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/ipam/api/nested_serializers.py b/netbox/ipam/api/nested_serializers.py index 07a7c9598..e74d60fb2 100644 --- a/netbox/ipam/api/nested_serializers.py +++ b/netbox/ipam/api/nested_serializers.py @@ -195,7 +195,7 @@ class NestedServiceSerializer(WritableNestedSerializer): fields = ['id', 'url', 'display', 'name', 'protocol', 'ports'] # -# Virtual Circuits +# L2VPN # From 8e39e7f8306f96080d6d13ce829b4376402bc094 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 08:03:07 -0500 Subject: [PATCH 129/245] Change API urls to plural form Co-authored-by: Jeremy Stretch --- netbox/ipam/api/urls.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/netbox/ipam/api/urls.py b/netbox/ipam/api/urls.py index b588b6974..20e31f4d4 100644 --- a/netbox/ipam/api/urls.py +++ b/netbox/ipam/api/urls.py @@ -46,8 +46,8 @@ router.register('service-templates', views.ServiceTemplateViewSet) router.register('services', views.ServiceViewSet) # L2VPN -router.register('l2vpn', views.L2VPNViewSet) -router.register('l2vpn-termination', views.L2VPNTerminationViewSet) +router.register('l2vpns', views.L2VPNViewSet) +router.register('l2vpn-terminations', views.L2VPNTerminationViewSet) app_name = 'ipam-api' From dbb1773e158d3243bcbcf9a950ab266ac1fa7a1b Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 08:04:33 -0500 Subject: [PATCH 130/245] Remove extraneous imports Co-authored-by: Jeremy Stretch --- netbox/ipam/forms/models.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/netbox/ipam/forms/models.py b/netbox/ipam/forms/models.py index 7ef47ed2f..5f4b37729 100644 --- a/netbox/ipam/forms/models.py +++ b/netbox/ipam/forms/models.py @@ -8,8 +8,6 @@ from ipam.choices import * from ipam.constants import * from ipam.formfields import IPNetworkFormField from ipam.models import * -from ipam.models import ASN -from ipam.models.l2vpn import L2VPN, L2VPNTermination from netbox.forms import NetBoxModelForm from tenancy.forms import TenancyForm from tenancy.models import Tenant From 0004b834fb21230c0a494d262138495fd9bc03d3 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 08:17:50 -0500 Subject: [PATCH 131/245] Commit fixes Jeremy suggested Co-authored-by: Jeremy Stretch --- netbox/ipam/api/serializers.py | 1 - netbox/ipam/api/views.py | 4 ++-- netbox/ipam/forms/models.py | 3 +++ netbox/ipam/models/l2vpn.py | 12 ++++++++---- netbox/netbox/navigation_menu.py | 2 +- 5 files changed, 14 insertions(+), 8 deletions(-) diff --git a/netbox/ipam/api/serializers.py b/netbox/ipam/api/serializers.py index d331a0f7d..c6e0027f1 100644 --- a/netbox/ipam/api/serializers.py +++ b/netbox/ipam/api/serializers.py @@ -483,7 +483,6 @@ class L2VPNTerminationSerializer(NetBoxModelSerializer): fields = [ 'id', 'url', 'display', 'l2vpn', 'assigned_object_type', 'assigned_object_id', 'assigned_object', - # Extra Fields 'tags', 'custom_fields', 'created', 'last_updated' ] diff --git a/netbox/ipam/api/views.py b/netbox/ipam/api/views.py index f5a61c031..0407c6d39 100644 --- a/netbox/ipam/api/views.py +++ b/netbox/ipam/api/views.py @@ -18,7 +18,7 @@ from netbox.config import get_config from utilities.constants import ADVISORY_LOCK_KEYS from utilities.utils import count_related from . import serializers -from ..models.l2vpn import L2VPN, L2VPNTermination +from ipam.models import L2VPN, L2VPNTermination class IPAMRootView(APIRootView): @@ -159,7 +159,7 @@ class ServiceViewSet(NetBoxModelViewSet): class L2VPNViewSet(NetBoxModelViewSet): - queryset = L2VPN.objects + queryset = L2VPN.objects.prefetch_related('import_targets', 'export_targets', 'tenant', 'tags') serializer_class = serializers.L2VPNSerializer filterset_class = filtersets.L2VPNFilterSet diff --git a/netbox/ipam/forms/models.py b/netbox/ipam/forms/models.py index 5f4b37729..bd1dce6fd 100644 --- a/netbox/ipam/forms/models.py +++ b/netbox/ipam/forms/models.py @@ -893,6 +893,9 @@ class L2VPNForm(TenancyForm, NetBoxModelForm): fields = ( 'name', 'slug', 'type', 'identifier', 'description', 'import_targets', 'export_targets', 'tenant', 'tags' ) + widgets = { + 'type': StaticSelect(), + } class L2VPNTerminationForm(NetBoxModelForm): diff --git a/netbox/ipam/models/l2vpn.py b/netbox/ipam/models/l2vpn.py index b086fa109..46cad72f8 100644 --- a/netbox/ipam/models/l2vpn.py +++ b/netbox/ipam/models/l2vpn.py @@ -34,7 +34,7 @@ class L2VPN(NetBoxModel): description = models.TextField(null=True, blank=True) tenant = models.ForeignKey( to='tenancy.Tenant', - on_delete=models.SET_NULL, + on_delete=models.PROTECT, related_name='l2vpns', blank=True, null=True @@ -85,7 +85,6 @@ class L2VPNTermination(NetBoxModel): class Meta: ordering = ('l2vpn',) verbose_name = 'L2VPN Termination' - constraints = ( models.UniqueConstraint( fields=('assigned_object_type', 'assigned_object_id'), @@ -112,5 +111,10 @@ class L2VPNTermination(NetBoxModel): # Only check if L2VPN is set and is of type P2P if self.l2vpn and self.l2vpn.type in L2VPNTypeChoices.P2P: - if L2VPNTermination.objects.filter(l2vpn=self.l2vpn).exclude(pk=self.pk).count() >= 2: - raise ValidationError(f'P2P Type L2VPNs can only have 2 terminations; first delete a termination') + terminations_count = L2VPNTermination.objects.filter(l2vpn=self.l2vpn).exclude(pk=self.pk).count() + if terminations_count >= 2: + l2vpn_type = self.l2vpn.get_type_display() + raise ValidationError( + f'{l2vpn_type} L2VPNs cannot have more than two terminations; found {terminations_count} already ' + f'defined.' + ) diff --git a/netbox/netbox/navigation_menu.py b/netbox/netbox/navigation_menu.py index f2245f68b..513cf4d9e 100644 --- a/netbox/netbox/navigation_menu.py +++ b/netbox/netbox/navigation_menu.py @@ -263,7 +263,7 @@ IPAM_MENU = Menu( MenuGroup( label='L2VPNs', items=( - get_model_item('ipam', 'l2vpn', 'L2VPN'), + get_model_item('ipam', 'l2vpn', 'L2VPNs'), get_model_item('ipam', 'l2vpntermination', 'Terminations'), ), ), From 30350e3b40dbf699fd9d9ae1c8998e41dae2d6fb Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 08:57:15 -0500 Subject: [PATCH 132/245] More fixes as a result of code review --- netbox/ipam/api/serializers.py | 7 +--- netbox/ipam/choices.py | 16 ++++---- netbox/ipam/forms/models.py | 32 +++++++++++++-- netbox/ipam/models/l2vpn.py | 18 +++------ netbox/ipam/tables/l2vpn.py | 23 ++++++++++- netbox/ipam/urls.py | 40 +++++++++---------- .../templates/ipam/l2vpntermination_edit.html | 16 ++++++-- 7 files changed, 98 insertions(+), 54 deletions(-) diff --git a/netbox/ipam/api/serializers.py b/netbox/ipam/api/serializers.py index c6e0027f1..9cde08374 100644 --- a/netbox/ipam/api/serializers.py +++ b/netbox/ipam/api/serializers.py @@ -464,9 +464,7 @@ class L2VPNSerializer(NetBoxModelSerializer): model = L2VPN fields = [ 'id', 'url', 'display', 'identifier', 'name', 'slug', 'type', 'import_targets', 'export_targets', - 'description', 'tenant', - # Extra Fields - 'tags', 'custom_fields', 'created', 'last_updated' + 'description', 'tenant', 'tags', 'custom_fields', 'created', 'last_updated' ] @@ -482,8 +480,7 @@ class L2VPNTerminationSerializer(NetBoxModelSerializer): model = L2VPNTermination fields = [ 'id', 'url', 'display', 'l2vpn', 'assigned_object_type', 'assigned_object_id', - 'assigned_object', - 'tags', 'custom_fields', 'created', 'last_updated' + 'assigned_object', 'tags', 'custom_fields', 'created', 'last_updated' ] @swagger_serializer_method(serializer_or_field=serializers.DictField) diff --git a/netbox/ipam/choices.py b/netbox/ipam/choices.py index 72cd4ff73..298baa643 100644 --- a/netbox/ipam/choices.py +++ b/netbox/ipam/choices.py @@ -191,6 +191,14 @@ class L2VPNTypeChoices(ChoiceSet): (TYPE_VPWS, 'VPWS'), (TYPE_VPLS, 'VPLS'), )), + ('VXLAN', ( + (TYPE_VXLAN, 'VXLAN'), + (TYPE_VXLAN_EVPN, 'VXLAN-EVPN'), + )), + ('L2VPN E-VPN', ( + (TYPE_MPLS_EVPN, 'MPLS EVPN'), + (TYPE_PBB_EVPN, 'PBB EVPN'), + )), ('E-Line', ( (TYPE_EPL, 'EPL'), (TYPE_EVPL, 'EVPL'), @@ -203,14 +211,6 @@ class L2VPNTypeChoices(ChoiceSet): (TYPE_EPTREE, 'Ethernet Private Tree'), (TYPE_EVPTREE, 'Ethernet Virtual Private Tree'), )), - ('VXLAN', ( - (TYPE_VXLAN, 'VXLAN'), - (TYPE_VXLAN_EVPN, 'VXLAN-EVPN'), - )), - ('L2VPN E-VPN', ( - (TYPE_MPLS_EVPN, 'MPLS EVPN'), - (TYPE_PBB_EVPN, 'PBB EVPN'), - )) ) P2P = ( diff --git a/netbox/ipam/forms/models.py b/netbox/ipam/forms/models.py index bd1dce6fd..d2797c1cf 100644 --- a/netbox/ipam/forms/models.py +++ b/netbox/ipam/forms/models.py @@ -929,6 +929,20 @@ class L2VPNTerminationForm(NetBoxModelForm): } ) + virtual_machine = DynamicModelChoiceField( + queryset=VirtualMachine.objects.all(), + required=False, + query_params={} + ) + + vminterface = DynamicModelChoiceField( + queryset=VMInterface.objects.all(), + required=False, + query_params={ + 'virtual_machine_id': '$virtual_machine' + } + ) + class Meta: model = L2VPNTermination fields = ('l2vpn', ) @@ -943,6 +957,8 @@ class L2VPNTerminationForm(NetBoxModelForm): initial['interface'] = instance.assigned_object elif type(instance.assigned_object) is VLAN: initial['vlan'] = instance.assigned_object + elif type(instance.assigned_object) is VMInterface: + initial['vminterface'] = instance.assigned_object kwargs['initial'] = initial super().__init__(*args, **kwargs) @@ -950,11 +966,21 @@ class L2VPNTerminationForm(NetBoxModelForm): def clean(self): super().clean() - if not (self.cleaned_data.get('interface') or self.cleaned_data.get('vlan')): + interface = self.cleaned_data.get('interface') + vlan = self.cleaned_data.get('vlan') + vminterface = self.cleaned_data.get('vminterface') + + if not (interface or vlan or vminterface): raise ValidationError('You must have either a interface or a VLAN') - if self.cleaned_data.get('interface') and self.cleaned_data.get('vlan'): + if interface and vlan and vminterface: + raise ValidationError('Cannot assign a interface, vlan and vminterface') + elif interface and vlan: raise ValidationError('Cannot assign both a interface and vlan') + elif interface and vminterface: + raise ValidationError('Cannot assign both a interface and vminterface') + elif vlan and vminterface: + raise ValidationError('Cannot assign both a vlan and vminterface') - obj = self.cleaned_data.get('interface') or self.cleaned_data.get('vlan') + obj = interface or vlan or vminterface self.instance.assigned_object = obj diff --git a/netbox/ipam/models/l2vpn.py b/netbox/ipam/models/l2vpn.py index 46cad72f8..dd8c51984 100644 --- a/netbox/ipam/models/l2vpn.py +++ b/netbox/ipam/models/l2vpn.py @@ -60,23 +60,15 @@ class L2VPNTermination(NetBoxModel): l2vpn = models.ForeignKey( to='ipam.L2VPN', on_delete=models.CASCADE, - related_name='terminations', - blank=False, - null=False + related_name='terminations' ) - assigned_object_type = models.ForeignKey( to=ContentType, limit_choices_to=L2VPN_ASSIGNMENT_MODELS, on_delete=models.PROTECT, - related_name='+', - blank=True, - null=True - ) - assigned_object_id = models.PositiveBigIntegerField( - blank=True, - null=True + related_name='+' ) + assigned_object_id = models.PositiveBigIntegerField() assigned_object = GenericForeignKey( ct_field='assigned_object_type', fk_field='assigned_object_id' @@ -95,13 +87,13 @@ class L2VPNTermination(NetBoxModel): def __str__(self): if self.pk is not None: return f'{self.assigned_object} <> {self.l2vpn}' - return '' + return super().__str__() def get_absolute_url(self): return reverse('ipam:l2vpntermination', args=[self.pk]) def clean(self): - # Only check is assigned_object is set + # Only check is assigned_object is set. Required otherwise we have an Integrity Error thrown. if self.assigned_object: obj_id = self.assigned_object.pk obj_type = ContentType.objects.get_for_model(self.assigned_object) diff --git a/netbox/ipam/tables/l2vpn.py b/netbox/ipam/tables/l2vpn.py index 551f692bb..a0e2f5d67 100644 --- a/netbox/ipam/tables/l2vpn.py +++ b/netbox/ipam/tables/l2vpn.py @@ -9,25 +9,44 @@ __all__ = ( 'L2VPNTerminationTable', ) +L2VPN_TARGETS = """ +{% for rt in value.all %} + {{ rt }}{% if not forloop.last %}
    {% endif %} +{% endfor %} +""" + class L2VPNTable(NetBoxTable): pk = columns.ToggleColumn() name = tables.Column( linkify=True ) + import_targets = columns.TemplateColumn( + template_code=L2VPN_TARGETS, + orderable=False + ) + export_targets = columns.TemplateColumn( + template_code=L2VPN_TARGETS, + orderable=False + ) class Meta(NetBoxTable.Meta): model = L2VPN - fields = ('pk', 'name', 'description', 'slug', 'type', 'tenant', 'actions') - default_columns = ('pk', 'name', 'description', 'actions') + fields = ('pk', 'name', 'slug', 'type', 'description', 'import_targets', 'export_targets', 'tenant', 'actions') + default_columns = ('pk', 'name', 'type', 'description', 'actions') class L2VPNTerminationTable(NetBoxTable): pk = columns.ToggleColumn() + l2vpn = tables.Column( + verbose_name='L2VPN', + linkify=True + ) assigned_object_type = columns.ContentTypeColumn( verbose_name='Object Type' ) assigned_object = tables.Column( + verbose_name='Assigned Object', linkify=True, orderable=False ) diff --git a/netbox/ipam/urls.py b/netbox/ipam/urls.py index e00b0365f..d27209fd2 100644 --- a/netbox/ipam/urls.py +++ b/netbox/ipam/urls.py @@ -187,25 +187,25 @@ urlpatterns = [ path('services//journal/', ObjectJournalView.as_view(), name='service_journal', kwargs={'model': Service}), # L2VPN - path('l2vpn/', views.L2VPNListView.as_view(), name='l2vpn_list'), - path('l2vpn/add/', views.L2VPNEditView.as_view(), name='l2vpn_add'), - path('l2vpn/import/', views.L2VPNBulkImportView.as_view(), name='l2vpn_import'), - path('l2vpn/edit/', views.L2VPNBulkEditView.as_view(), name='l2vpn_bulk_edit'), - path('l2vpn/delete/', views.L2VPNBulkDeleteView.as_view(), name='l2vpn_bulk_delete'), - path('l2vpn//', views.L2VPNView.as_view(), name='l2vpn'), - path('l2vpn//edit/', views.L2VPNEditView.as_view(), name='l2vpn_edit'), - path('l2vpn//delete/', views.L2VPNDeleteView.as_view(), name='l2vpn_delete'), - path('l2vpn//changelog/', ObjectChangeLogView.as_view(), name='l2vpn_changelog', kwargs={'model': L2VPN}), - path('l2vpn//journal/', ObjectJournalView.as_view(), name='l2vpn_journal', kwargs={'model': L2VPN}), + path('l2vpns/', views.L2VPNListView.as_view(), name='l2vpn_list'), + path('l2vpns/add/', views.L2VPNEditView.as_view(), name='l2vpn_add'), + path('l2vpns/import/', views.L2VPNBulkImportView.as_view(), name='l2vpn_import'), + path('l2vpns/edit/', views.L2VPNBulkEditView.as_view(), name='l2vpn_bulk_edit'), + path('l2vpns/delete/', views.L2VPNBulkDeleteView.as_view(), name='l2vpn_bulk_delete'), + path('l2vpns//', views.L2VPNView.as_view(), name='l2vpn'), + path('l2vpns//edit/', views.L2VPNEditView.as_view(), name='l2vpn_edit'), + path('l2vpns//delete/', views.L2VPNDeleteView.as_view(), name='l2vpn_delete'), + path('l2vpns//changelog/', ObjectChangeLogView.as_view(), name='l2vpn_changelog', kwargs={'model': L2VPN}), + path('l2vpns//journal/', ObjectJournalView.as_view(), name='l2vpn_journal', kwargs={'model': L2VPN}), - path('l2vpn-termination/', views.L2VPNTerminationListView.as_view(), name='l2vpntermination_list'), - path('l2vpn-termination/add/', views.L2VPNTerminationEditView.as_view(), name='l2vpntermination_add'), - path('l2vpn-termination/import/', views.L2VPNTerminationBulkImportView.as_view(), name='l2vpntermination_import'), - path('l2vpn-termination/edit/', views.L2VPNTerminationBulkEditView.as_view(), name='l2vpntermination_bulk_edit'), - path('l2vpn-termination/delete/', views.L2VPNTerminationBulkDeleteView.as_view(), name='l2vpntermination_bulk_delete'), - path('l2vpn-termination//', views.L2VPNTerminationView.as_view(), name='l2vpntermination'), - path('l2vpn-termination//edit/', views.L2VPNTerminationEditView.as_view(), name='l2vpntermination_edit'), - path('l2vpn-termination//delete/', views.L2VPNTerminationDeleteView.as_view(), name='l2vpntermination_delete'), - path('l2vpn-termination//changelog/', ObjectChangeLogView.as_view(), name='l2vpntermination_changelog', kwargs={'model': L2VPNTermination}), - path('l2vpn-termination//journal/', ObjectJournalView.as_view(), name='l2vpntermination_journal', kwargs={'model': L2VPNTermination}), + path('l2vpn-terminations/', views.L2VPNTerminationListView.as_view(), name='l2vpntermination_list'), + path('l2vpn-terminations/add/', views.L2VPNTerminationEditView.as_view(), name='l2vpntermination_add'), + path('l2vpn-terminations/import/', views.L2VPNTerminationBulkImportView.as_view(), name='l2vpntermination_import'), + path('l2vpn-terminations/edit/', views.L2VPNTerminationBulkEditView.as_view(), name='l2vpntermination_bulk_edit'), + path('l2vpn-terminations/delete/', views.L2VPNTerminationBulkDeleteView.as_view(), name='l2vpntermination_bulk_delete'), + path('l2vpn-terminations//', views.L2VPNTerminationView.as_view(), name='l2vpntermination'), + path('l2vpn-terminations//edit/', views.L2VPNTerminationEditView.as_view(), name='l2vpntermination_edit'), + path('l2vpn-terminations//delete/', views.L2VPNTerminationDeleteView.as_view(), name='l2vpntermination_delete'), + path('l2vpn-terminations//changelog/', ObjectChangeLogView.as_view(), name='l2vpntermination_changelog', kwargs={'model': L2VPNTermination}), + path('l2vpn-terminations//journal/', ObjectJournalView.as_view(), name='l2vpntermination_journal', kwargs={'model': L2VPNTermination}), ] diff --git a/netbox/templates/ipam/l2vpntermination_edit.html b/netbox/templates/ipam/l2vpntermination_edit.html index 3fb0460b5..4ba079eb5 100644 --- a/netbox/templates/ipam/l2vpntermination_edit.html +++ b/netbox/templates/ipam/l2vpntermination_edit.html @@ -12,7 +12,7 @@
      @@ -21,18 +21,28 @@ Interface +
    - {% render_field form.device %} -
    +
    + {% render_field form.device %} {% render_field form.vlan %}
    + {% render_field form.device %} {% render_field form.interface %}
    +
    + {% render_field form.virtual_machine %} + {% render_field form.vminterface %} +
    From 5bcc3a3fb9636d0b24c42a46383dc964f01287e3 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 09:00:33 -0500 Subject: [PATCH 133/245] Update docs --- docs/models/ipam/l2vpn.md | 2 ++ docs/models/ipam/l2vpntermination.md | 5 ++++- netbox/ipam/forms/models.py | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/models/ipam/l2vpn.md b/docs/models/ipam/l2vpn.md index 9c50a6407..9f9b4703c 100644 --- a/docs/models/ipam/l2vpn.md +++ b/docs/models/ipam/l2vpn.md @@ -17,3 +17,5 @@ Each L2VPN instance must have one of the following type associated with it: * MPLS-EVPN * PBB-EVPN +!!!note + Choosing VPWS, EPL, EP-LAN, EP-TREE will result in only being able to add 2 terminations to a given L2VPN. diff --git a/docs/models/ipam/l2vpntermination.md b/docs/models/ipam/l2vpntermination.md index 9135f72a3..cc1843639 100644 --- a/docs/models/ipam/l2vpntermination.md +++ b/docs/models/ipam/l2vpntermination.md @@ -9,4 +9,7 @@ The following types of L2VPN's are considered point-to-point: * VPWS * EPL * EP-LAN -* EP-TREE \ No newline at end of file +* EP-TREE + +!!!note + Choosing any of the above types of L2VPN's will result in only being able to add 2 terminations to a given L2VPN. diff --git a/netbox/ipam/forms/models.py b/netbox/ipam/forms/models.py index d2797c1cf..43e33dd4d 100644 --- a/netbox/ipam/forms/models.py +++ b/netbox/ipam/forms/models.py @@ -976,7 +976,7 @@ class L2VPNTerminationForm(NetBoxModelForm): if interface and vlan and vminterface: raise ValidationError('Cannot assign a interface, vlan and vminterface') elif interface and vlan: - raise ValidationError('Cannot assign both a interface and vlan') + raise Validatio`nError('Cannot assign both a interface and vlan') elif interface and vminterface: raise ValidationError('Cannot assign both a interface and vminterface') elif vlan and vminterface: From f1c8926252e923589161ede1cc7b4cd6432806c1 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 09:01:08 -0500 Subject: [PATCH 134/245] Fix error --- netbox/ipam/forms/models.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/ipam/forms/models.py b/netbox/ipam/forms/models.py index 43e33dd4d..d2797c1cf 100644 --- a/netbox/ipam/forms/models.py +++ b/netbox/ipam/forms/models.py @@ -976,7 +976,7 @@ class L2VPNTerminationForm(NetBoxModelForm): if interface and vlan and vminterface: raise ValidationError('Cannot assign a interface, vlan and vminterface') elif interface and vlan: - raise Validatio`nError('Cannot assign both a interface and vlan') + raise ValidationError('Cannot assign both a interface and vlan') elif interface and vminterface: raise ValidationError('Cannot assign both a interface and vminterface') elif vlan and vminterface: From 878c465c56b5a656c4f99ebc9499d11274a7692e Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Wed, 6 Jul 2022 09:10:10 -0500 Subject: [PATCH 135/245] Update Termination table rendering on L2VPN View --- netbox/templates/ipam/l2vpn.html | 34 ++------------------------------ 1 file changed, 2 insertions(+), 32 deletions(-) diff --git a/netbox/templates/ipam/l2vpn.html b/netbox/templates/ipam/l2vpn.html index 59cc6234b..130940b02 100644 --- a/netbox/templates/ipam/l2vpn.html +++ b/netbox/templates/ipam/l2vpn.html @@ -59,39 +59,9 @@
    -
    L2VPN Terminations
    +
    Terminations
    - {% with terminations=object.terminations.all %} - {% if terminations.exists %} - - - - - - - {% for termination in terminations %} - - - - - - {% endfor %} -
    Termination TypeTermination
    {{ termination.assigned_object|meta:"verbose_name" }}{{ termination.assigned_object|linkify }} - {% if perms.ipam.change_l2vpntermination %} - - - - {% endif %} - {% if perms.ipam.delete_l2vpntermination %} - - - - {% endif %} -
    - {% else %} -
    None
    - {% endif %} - {% endwith %} + {% render_table terminations_table 'inc/table.html' %}
    {% if perms.ipam.add_l2vpntermination %}
    From 29a46d2c18091b48d9d99a51ba31e62b1c8063c7 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 6 Jul 2022 12:46:26 -0400 Subject: [PATCH 136/245] Add support for VM interface termination via bulk import --- netbox/ipam/forms/bulk_import.py | 37 ++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/netbox/ipam/forms/bulk_import.py b/netbox/ipam/forms/bulk_import.py index 5b94f6c8e..b8dd1c54c 100644 --- a/netbox/ipam/forms/bulk_import.py +++ b/netbox/ipam/forms/bulk_import.py @@ -453,49 +453,58 @@ class L2VPNTerminationCSVForm(NetBoxModelCSVForm): to_field_name='name', label='L2VPN', ) - device = CSVModelChoiceField( queryset=Device.objects.all(), required=False, to_field_name='name', - help_text='Required if assigned to a interface' + help_text='Parent device (for interface)' ) - - interface = CSVModelChoiceField( - queryset=Interface.objects.all(), + virtual_machine = CSVModelChoiceField( + queryset=VirtualMachine.objects.all(), required=False, to_field_name='name', - help_text='Required if not assigned to a vlan' + help_text='Parent virtual machine (for interface)' + ) + interface = CSVModelChoiceField( + queryset=Interface.objects.none(), # Can also refer to VMInterface + required=False, + to_field_name='name', + help_text='Assigned interface (device or VM)' ) - vlan = CSVModelChoiceField( queryset=VLAN.objects.all(), required=False, to_field_name='name', - help_text='Required if not assigned to a interface' + help_text='Assigned VLAN' ) class Meta: model = L2VPNTermination - fields = ('l2vpn', 'device', 'interface', 'vlan') + fields = ('l2vpn', 'device', 'virtual_machine', 'interface', 'vlan') def __init__(self, data=None, *args, **kwargs): super().__init__(data, *args, **kwargs) + if data: - # Limit interface queryset by assigned device + + # Limit interface queryset by device or VM if data.get('device'): self.fields['interface'].queryset = Interface.objects.filter( **{f"device__{self.fields['device'].to_field_name}": data['device']} ) + elif data.get('virtual_machine'): + self.fields['interface'].queryset = VMInterface.objects.filter( + **{f"virtual_machine__{self.fields['virtual_machine'].to_field_name}": data['virtual_machine']} + ) def clean(self): super().clean() + if self.cleaned_data.get('device') and self.cleaned_data.get('virtual_machine'): + raise ValidationError('Cannot import device and VM interface terminations simultaneously.') if not (self.cleaned_data.get('interface') or self.cleaned_data.get('vlan')): - raise ValidationError('You must have either a interface or a VLAN') - + raise ValidationError('Each termination must specify either an interface or a VLAN.') if self.cleaned_data.get('interface') and self.cleaned_data.get('vlan'): - raise ValidationError('Cannot assign both a interface and vlan') + raise ValidationError('Cannot assign both an interface and a VLAN.') - # Set Assigned Object self.instance.assigned_object = self.cleaned_data.get('interface') or self.cleaned_data.get('vlan') From 4bb4bbce1461bee0644e97900006e3fe6d71a3e4 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 6 Jul 2022 12:49:00 -0400 Subject: [PATCH 137/245] Clean up validation --- netbox/ipam/forms/models.py | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/netbox/ipam/forms/models.py b/netbox/ipam/forms/models.py index d2797c1cf..3986eee32 100644 --- a/netbox/ipam/forms/models.py +++ b/netbox/ipam/forms/models.py @@ -906,13 +906,11 @@ class L2VPNTerminationForm(NetBoxModelForm): label='L2VPN', fetch_trigger='open' ) - device = DynamicModelChoiceField( queryset=Device.objects.all(), required=False, query_params={} ) - vlan = DynamicModelChoiceField( queryset=VLAN.objects.all(), required=False, @@ -920,7 +918,6 @@ class L2VPNTerminationForm(NetBoxModelForm): 'available_on_device': '$device' } ) - interface = DynamicModelChoiceField( queryset=Interface.objects.all(), required=False, @@ -928,13 +925,11 @@ class L2VPNTerminationForm(NetBoxModelForm): 'device_id': '$device' } ) - virtual_machine = DynamicModelChoiceField( queryset=VirtualMachine.objects.all(), required=False, query_params={} ) - vminterface = DynamicModelChoiceField( queryset=VMInterface.objects.all(), required=False, @@ -967,20 +962,12 @@ class L2VPNTerminationForm(NetBoxModelForm): super().clean() interface = self.cleaned_data.get('interface') - vlan = self.cleaned_data.get('vlan') vminterface = self.cleaned_data.get('vminterface') + vlan = self.cleaned_data.get('vlan') - if not (interface or vlan or vminterface): - raise ValidationError('You must have either a interface or a VLAN') + if not (interface or vminterface or vlan): + raise ValidationError('A termination must specify an interface or VLAN.') + if len([x for x in (interface, vminterface, vlan) if x]) > 1: + raise ValidationError('A termination can only have one terminating object (an interface or VLAN).') - if interface and vlan and vminterface: - raise ValidationError('Cannot assign a interface, vlan and vminterface') - elif interface and vlan: - raise ValidationError('Cannot assign both a interface and vlan') - elif interface and vminterface: - raise ValidationError('Cannot assign both a interface and vminterface') - elif vlan and vminterface: - raise ValidationError('Cannot assign both a vlan and vminterface') - - obj = interface or vlan or vminterface - self.instance.assigned_object = obj + self.instance.assigned_object = interface or vminterface or vlan From 1e1ce550c02e5b2e3761450252193bc6abadd82e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 6 Jul 2022 12:53:10 -0400 Subject: [PATCH 138/245] Update L2VPN migration --- ...2vpn_l2vpntermination_and_more.py => 0059_l2vpn.py} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename netbox/ipam/migrations/{0059_l2vpn_l2vpntermination_and_more.py => 0059_l2vpn.py} (83%) diff --git a/netbox/ipam/migrations/0059_l2vpn_l2vpntermination_and_more.py b/netbox/ipam/migrations/0059_l2vpn.py similarity index 83% rename from netbox/ipam/migrations/0059_l2vpn_l2vpntermination_and_more.py rename to netbox/ipam/migrations/0059_l2vpn.py index a8e5ace25..5662049c3 100644 --- a/netbox/ipam/migrations/0059_l2vpn_l2vpntermination_and_more.py +++ b/netbox/ipam/migrations/0059_l2vpn.py @@ -1,4 +1,4 @@ -# Generated by Django 4.0.5 on 2022-06-28 04:57 +# Generated by Django 4.0.5 on 2022-07-06 16:51 import django.core.serializers.json from django.db import migrations, models @@ -9,9 +9,9 @@ import taggit.managers class Migration(migrations.Migration): dependencies = [ + ('extras', '0076_configcontext_locations'), ('contenttypes', '0002_remove_content_type_name'), ('tenancy', '0007_contact_link'), - ('extras', '0076_configcontext_locations'), ('ipam', '0058_ipaddress_nat_inside_nonunique'), ] @@ -31,7 +31,7 @@ class Migration(migrations.Migration): ('export_targets', models.ManyToManyField(blank=True, related_name='exporting_l2vpns', to='ipam.routetarget')), ('import_targets', models.ManyToManyField(blank=True, related_name='importing_l2vpns', to='ipam.routetarget')), ('tags', taggit.managers.TaggableManager(through='extras.TaggedItem', to='extras.Tag')), - ('tenant', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='l2vpns', to='tenancy.tenant')), + ('tenant', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='l2vpns', to='tenancy.tenant')), ], options={ 'verbose_name': 'L2VPN', @@ -45,8 +45,8 @@ class Migration(migrations.Migration): ('created', models.DateTimeField(auto_now_add=True, null=True)), ('last_updated', models.DateTimeField(auto_now=True, null=True)), ('custom_field_data', models.JSONField(blank=True, default=dict, encoder=django.core.serializers.json.DjangoJSONEncoder)), - ('assigned_object_id', models.PositiveBigIntegerField(blank=True, null=True)), - ('assigned_object_type', models.ForeignKey(blank=True, limit_choices_to=models.Q(models.Q(models.Q(('app_label', 'dcim'), ('model', 'interface')), models.Q(('app_label', 'ipam'), ('model', 'vlan')), models.Q(('app_label', 'virtualization'), ('model', 'vminterface')), _connector='OR')), null=True, on_delete=django.db.models.deletion.PROTECT, related_name='+', to='contenttypes.contenttype')), + ('assigned_object_id', models.PositiveBigIntegerField()), + ('assigned_object_type', models.ForeignKey(limit_choices_to=models.Q(models.Q(models.Q(('app_label', 'dcim'), ('model', 'interface')), models.Q(('app_label', 'ipam'), ('model', 'vlan')), models.Q(('app_label', 'virtualization'), ('model', 'vminterface')), _connector='OR')), on_delete=django.db.models.deletion.PROTECT, related_name='+', to='contenttypes.contenttype')), ('l2vpn', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='terminations', to='ipam.l2vpn')), ('tags', taggit.managers.TaggableManager(through='extras.TaggedItem', to='extras.Tag')), ], From 4d3278cb52500b1ff64a4d92e5eb5ddcd43f89c0 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 6 Jul 2022 13:31:31 -0400 Subject: [PATCH 139/245] #8157: Clean up L2VPN assignment for VM interfaces --- netbox/dcim/api/serializers.py | 4 ++-- netbox/templates/ipam/l2vpntermination.html | 6 +++--- netbox/virtualization/api/serializers.py | 9 ++++++--- netbox/virtualization/models.py | 10 ++++++++++ 4 files changed, 21 insertions(+), 8 deletions(-) diff --git a/netbox/dcim/api/serializers.py b/netbox/dcim/api/serializers.py index fcee81615..4cb988c42 100644 --- a/netbox/dcim/api/serializers.py +++ b/netbox/dcim/api/serializers.py @@ -9,8 +9,8 @@ from dcim.choices import * from dcim.constants import * from dcim.models import * from ipam.api.nested_serializers import ( - NestedASNSerializer, NestedIPAddressSerializer, NestedVLANSerializer, NestedVRFSerializer, - NestedL2VPNTerminationSerializer, + NestedASNSerializer, NestedIPAddressSerializer, NestedL2VPNTerminationSerializer, NestedVLANSerializer, + NestedVRFSerializer, ) from ipam.models import ASN, VLAN from netbox.api import ChoiceField, ContentTypeField, SerializedPKRelatedField diff --git a/netbox/templates/ipam/l2vpntermination.html b/netbox/templates/ipam/l2vpntermination.html index 22e0cc324..b34d1a710 100644 --- a/netbox/templates/ipam/l2vpntermination.html +++ b/netbox/templates/ipam/l2vpntermination.html @@ -11,12 +11,12 @@
    - - + + - +
    L2vPN{{ object.l2vpn.name|placeholder }}L2VPN{{ object.l2vpn|linkify }}
    Assigned Object{{ object.assigned_object.name|placeholder }}{{ object.assigned_object|linkify }}
    diff --git a/netbox/virtualization/api/serializers.py b/netbox/virtualization/api/serializers.py index bd01b5533..c5816dca8 100644 --- a/netbox/virtualization/api/serializers.py +++ b/netbox/virtualization/api/serializers.py @@ -5,7 +5,9 @@ from dcim.api.nested_serializers import ( NestedDeviceSerializer, NestedDeviceRoleSerializer, NestedPlatformSerializer, NestedSiteSerializer, ) from dcim.choices import InterfaceModeChoices -from ipam.api.nested_serializers import NestedIPAddressSerializer, NestedVLANSerializer, NestedVRFSerializer +from ipam.api.nested_serializers import ( + NestedIPAddressSerializer, NestedL2VPNTerminationSerializer, NestedVLANSerializer, NestedVRFSerializer, +) from ipam.models import VLAN from netbox.api import ChoiceField, SerializedPKRelatedField from netbox.api.serializers import NetBoxModelSerializer @@ -121,6 +123,7 @@ class VMInterfaceSerializer(NetBoxModelSerializer): many=True ) vrf = NestedVRFSerializer(required=False, allow_null=True) + l2vpn_termination = NestedL2VPNTerminationSerializer(read_only=True) count_ipaddresses = serializers.IntegerField(read_only=True) count_fhrp_groups = serializers.IntegerField(read_only=True) @@ -128,8 +131,8 @@ class VMInterfaceSerializer(NetBoxModelSerializer): model = VMInterface fields = [ 'id', 'url', 'display', 'virtual_machine', 'name', 'enabled', 'parent', 'bridge', 'mtu', 'mac_address', - 'description', 'mode', 'untagged_vlan', 'tagged_vlans', 'vrf', 'tags', 'custom_fields', 'created', - 'last_updated', 'count_ipaddresses', 'count_fhrp_groups', + 'description', 'mode', 'untagged_vlan', 'tagged_vlans', 'vrf', 'l2vpn_termination', 'tags', 'custom_fields', + 'created', 'last_updated', 'count_ipaddresses', 'count_fhrp_groups', ] def validate(self, data): diff --git a/netbox/virtualization/models.py b/netbox/virtualization/models.py index 02560a962..98321976f 100644 --- a/netbox/virtualization/models.py +++ b/netbox/virtualization/models.py @@ -440,6 +440,12 @@ class VMInterface(NetBoxModel, BaseInterface): object_id_field='interface_id', related_query_name='+' ) + l2vpn_terminations = GenericRelation( + to='ipam.L2VPNTermination', + content_type_field='assigned_object_type', + object_id_field='assigned_object_id', + related_query_name='vminterface', + ) class Meta: verbose_name = 'interface' @@ -498,3 +504,7 @@ class VMInterface(NetBoxModel, BaseInterface): @property def parent_object(self): return self.virtual_machine + + @property + def l2vpn_termination(self): + return self.l2vpn_terminations.first() From 78a3dfc5d97e1fb856116d7db7c31f1a85985f3a Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 6 Jul 2022 13:38:25 -0400 Subject: [PATCH 140/245] Changelog for #8157 --- docs/release-notes/version-3.3.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 92401c217..456afd765 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -13,6 +13,8 @@ #### PoE Interface Attributes ([#1099](https://github.com/netbox-community/netbox/issues/1099)) +#### L2VPN Modeling ([#8157](https://github.com/netbox-community/netbox/issues/8157)) + #### Restrict API Tokens by Client IP ([#8233](https://github.com/netbox-community/netbox/issues/8233)) #### Reference User in Permission Constraints ([#9074](https://github.com/netbox-community/netbox/issues/9074)) @@ -52,6 +54,9 @@ ### REST API Changes +* Added the following endpoints: + * `/api/ipam/l2vpns/` + * `/api/ipam/l2vpn-terminations/` * circuits.Circuit * Added optional `termination_date` field * circuits.CircuitTermination @@ -62,6 +67,7 @@ * The `u_height` field has been changed from an integer to a decimal * dcim.Interface * Added the optional `poe_mode` and `poe_type` fields + * Added the `l2vpn_termination` read-only field * dcim.Location * Added required `status` field (default value: `active`) * dcim.Rack @@ -73,15 +79,18 @@ * ipam.IPAddress * The `nat_inside` field no longer requires a unique value * The `nat_outside` field has changed from a single IP address instance to a list of multiple IP addresses +* ipam.VLAN + * Added the `l2vpn_termination` read-only field * users.Token * Added the `allowed_ips` array field * Added the read-only `last_used` datetime field * virtualization.Cluster * Added required `status` field (default value: `active`) * virtualization.VirtualMachine - * Added `device` field * The `site` field is now directly writable (rather than being inferred from the assigned cluster) * The `cluster` field is now optional. A virtual machine must have a site and/or cluster assigned. + * Added the `device` field + * Added the `l2vpn_termination` read-only field wireless.WirelessLAN * Added `tenant` field wireless.WirelessLink From af14bfdd84ada7a4a099e660fb666d7d9f6a6c84 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 6 Jul 2022 15:56:10 -0400 Subject: [PATCH 141/245] Rename LinkTermination to CabledObjectModel --- netbox/circuits/api/serializers.py | 11 ++- netbox/circuits/models/circuits.py | 4 +- netbox/dcim/api/serializers.py | 98 ++++++++----------------- netbox/dcim/models/device_components.py | 20 ++--- netbox/dcim/models/power.py | 4 +- 5 files changed, 49 insertions(+), 88 deletions(-) diff --git a/netbox/circuits/api/serializers.py b/netbox/circuits/api/serializers.py index ab72ffcdd..6b09cd531 100644 --- a/netbox/circuits/api/serializers.py +++ b/netbox/circuits/api/serializers.py @@ -3,11 +3,11 @@ from rest_framework import serializers from circuits.choices import CircuitStatusChoices from circuits.models import * from dcim.api.nested_serializers import NestedCableSerializer, NestedSiteSerializer -from dcim.api.serializers import LinkTerminationSerializer +from dcim.api.serializers import CabledObjectSerializer from ipam.models import ASN from ipam.api.nested_serializers import NestedASNSerializer from netbox.api import ChoiceField, SerializedPKRelatedField -from netbox.api.serializers import NetBoxModelSerializer, ValidatedModelSerializer, WritableNestedSerializer +from netbox.api.serializers import NetBoxModelSerializer, WritableNestedSerializer from tenancy.api.nested_serializers import NestedTenantSerializer from .nested_serializers import * @@ -98,17 +98,16 @@ class CircuitSerializer(NetBoxModelSerializer): ] -class CircuitTerminationSerializer(NetBoxModelSerializer, LinkTerminationSerializer): +class CircuitTerminationSerializer(NetBoxModelSerializer, CabledObjectSerializer): url = serializers.HyperlinkedIdentityField(view_name='circuits-api:circuittermination-detail') circuit = NestedCircuitSerializer() site = NestedSiteSerializer(required=False, allow_null=True) provider_network = NestedProviderNetworkSerializer(required=False, allow_null=True) - cable = NestedCableSerializer(read_only=True) class Meta: model = CircuitTermination fields = [ 'id', 'url', 'display', 'circuit', 'term_side', 'site', 'provider_network', 'port_speed', 'upstream_speed', - 'xconnect_id', 'pp_info', 'description', 'mark_connected', 'cable', 'link_peers', 'link_peers_type', - '_occupied', 'tags', 'custom_fields', 'created', 'last_updated', + 'xconnect_id', 'pp_info', 'description', 'mark_connected', 'cable', 'cable_end', 'link_peers', + 'link_peers_type', 'tags', 'custom_fields', 'created', 'last_updated', '_occupied', ] diff --git a/netbox/circuits/models/circuits.py b/netbox/circuits/models/circuits.py index cf6ffc503..d82878cde 100644 --- a/netbox/circuits/models/circuits.py +++ b/netbox/circuits/models/circuits.py @@ -4,7 +4,7 @@ from django.db import models from django.urls import reverse from circuits.choices import * -from dcim.models import LinkTermination +from dcim.models import CabledObjectModel from netbox.models import ( ChangeLoggedModel, CustomFieldsMixin, CustomLinksMixin, OrganizationalModel, NetBoxModel, TagsMixin, ) @@ -149,7 +149,7 @@ class CircuitTermination( TagsMixin, WebhooksMixin, ChangeLoggedModel, - LinkTermination + CabledObjectModel ): circuit = models.ForeignKey( to='circuits.Circuit', diff --git a/netbox/dcim/api/serializers.py b/netbox/dcim/api/serializers.py index 57b32bfc6..9938bb2e9 100644 --- a/netbox/dcim/api/serializers.py +++ b/netbox/dcim/api/serializers.py @@ -8,7 +8,6 @@ from timezone_field.rest_framework import TimeZoneSerializerField from dcim.choices import * from dcim.constants import * from dcim.models import * -from extras.api.serializers import ContentTypeSerializer from ipam.api.nested_serializers import ( NestedASNSerializer, NestedIPAddressSerializer, NestedL2VPNTerminationSerializer, NestedVLANSerializer, NestedVRFSerializer, @@ -29,7 +28,9 @@ from wireless.models import WirelessLAN from .nested_serializers import * -class LinkTerminationSerializer(serializers.ModelSerializer): +class CabledObjectSerializer(serializers.ModelSerializer): + cable = NestedCableSerializer(read_only=True) + cable_end = serializers.CharField(read_only=True) link_peers_type = serializers.SerializerMethodField(read_only=True) link_peers = serializers.SerializerMethodField(read_only=True) _occupied = serializers.SerializerMethodField(read_only=True) @@ -67,37 +68,6 @@ class LinkTerminationSerializer(serializers.ModelSerializer): return obj._occupied -# class ConnectedEndpointSerializer(serializers.ModelSerializer): -# """ -# Legacy serializer for pre-v3.3 connections -# """ -# connected_endpoint_type = serializers.SerializerMethodField(read_only=True) -# connected_endpoint = serializers.SerializerMethodField(read_only=True) -# connected_endpoint_reachable = serializers.SerializerMethodField(read_only=True) -# -# def get_connected_endpoint_type(self, obj): -# if obj._path is not None and obj._path.destination is not None: -# return f'{obj._path.destination._meta.app_label}.{obj._path.destination._meta.model_name}' -# return None -# -# @swagger_serializer_method(serializer_or_field=serializers.DictField) -# def get_connected_endpoint(self, obj): -# """ -# Return the appropriate serializer for the type of connected object. -# """ -# if obj._path is not None and obj._path.destination is not None: -# serializer = get_serializer_for_model(obj._path.destination, prefix='Nested') -# context = {'request': self.context['request']} -# return serializer(obj._path.destination, context=context).data -# return None -# -# @swagger_serializer_method(serializer_or_field=serializers.BooleanField) -# def get_connected_endpoint_reachable(self, obj): -# if obj._path is not None: -# return obj._path.is_active -# return None - - class ConnectedEndpointsSerializer(serializers.ModelSerializer): """ Legacy serializer for pre-v3.3 connections @@ -729,7 +699,7 @@ class DeviceNAPALMSerializer(serializers.Serializer): # Device components # -class ConsoleServerPortSerializer(NetBoxModelSerializer, LinkTerminationSerializer, ConnectedEndpointsSerializer): +class ConsoleServerPortSerializer(NetBoxModelSerializer, CabledObjectSerializer, ConnectedEndpointsSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:consoleserverport-detail') device = NestedDeviceSerializer() module = ComponentNestedModuleSerializer( @@ -746,18 +716,18 @@ class ConsoleServerPortSerializer(NetBoxModelSerializer, LinkTerminationSerializ allow_null=True, required=False ) - cable = NestedCableSerializer(read_only=True) class Meta: model = ConsoleServerPort fields = [ 'id', 'url', 'display', 'device', 'module', 'name', 'label', 'type', 'speed', 'description', - 'mark_connected', 'cable', 'link_peers', 'link_peers_type', 'connected_endpoints', 'connected_endpoints_type', - 'connected_endpoints_reachable', 'tags', 'custom_fields', 'created', 'last_updated', '_occupied', + 'mark_connected', 'cable', 'cable_end', 'link_peers', 'link_peers_type', 'connected_endpoints', + 'connected_endpoints_type', 'connected_endpoints_reachable', 'tags', 'custom_fields', 'created', + 'last_updated', '_occupied', ] -class ConsolePortSerializer(NetBoxModelSerializer, LinkTerminationSerializer, ConnectedEndpointsSerializer): +class ConsolePortSerializer(NetBoxModelSerializer, CabledObjectSerializer, ConnectedEndpointsSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:consoleport-detail') device = NestedDeviceSerializer() module = ComponentNestedModuleSerializer( @@ -774,18 +744,18 @@ class ConsolePortSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Co allow_null=True, required=False ) - cable = NestedCableSerializer(read_only=True) class Meta: model = ConsolePort fields = [ 'id', 'url', 'display', 'device', 'module', 'name', 'label', 'type', 'speed', 'description', - 'mark_connected', 'cable', 'link_peers', 'link_peers_type', 'connected_endpoints', 'connected_endpoints_type', - 'connected_endpoints_reachable', 'tags', 'custom_fields', 'created', 'last_updated', '_occupied', + 'mark_connected', 'cable', 'cable_end', 'link_peers', 'link_peers_type', 'connected_endpoints', + 'connected_endpoints_type', 'connected_endpoints_reachable', 'tags', 'custom_fields', 'created', + 'last_updated', '_occupied', ] -class PowerOutletSerializer(NetBoxModelSerializer, LinkTerminationSerializer, ConnectedEndpointsSerializer): +class PowerOutletSerializer(NetBoxModelSerializer, CabledObjectSerializer, ConnectedEndpointsSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:poweroutlet-detail') device = NestedDeviceSerializer() module = ComponentNestedModuleSerializer( @@ -806,21 +776,18 @@ class PowerOutletSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Co allow_blank=True, required=False ) - cable = NestedCableSerializer( - read_only=True - ) class Meta: model = PowerOutlet fields = [ 'id', 'url', 'display', 'device', 'module', 'name', 'label', 'type', 'power_port', 'feed_leg', - 'description', 'mark_connected', 'cable', 'link_peers', 'link_peers_type', 'connected_endpoints', - 'connected_endpoints_type', 'connected_endpoints_reachable', 'tags', 'custom_fields', 'created', - 'last_updated', '_occupied', + 'description', 'mark_connected', 'cable', 'cable_end', 'link_peers', 'link_peers_type', + 'connected_endpoints', 'connected_endpoints_type', 'connected_endpoints_reachable', 'tags', 'custom_fields', + 'created', 'last_updated', '_occupied', ] -class PowerPortSerializer(NetBoxModelSerializer, LinkTerminationSerializer, ConnectedEndpointsSerializer): +class PowerPortSerializer(NetBoxModelSerializer, CabledObjectSerializer, ConnectedEndpointsSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:powerport-detail') device = NestedDeviceSerializer() module = ComponentNestedModuleSerializer( @@ -832,19 +799,18 @@ class PowerPortSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Conn allow_blank=True, required=False ) - cable = NestedCableSerializer(read_only=True) class Meta: model = PowerPort fields = [ 'id', 'url', 'display', 'device', 'module', 'name', 'label', 'type', 'maximum_draw', 'allocated_draw', - 'description', 'mark_connected', 'cable', 'link_peers', 'link_peers_type', 'connected_endpoints', - 'connected_endpoints_type', 'connected_endpoints_reachable', 'tags', 'custom_fields', 'created', - 'last_updated', '_occupied', + 'description', 'mark_connected', 'cable', 'cable_end', 'link_peers', 'link_peers_type', + 'connected_endpoints', 'connected_endpoints_type', 'connected_endpoints_reachable', 'tags', 'custom_fields', + 'created', 'last_updated', '_occupied', ] -class InterfaceSerializer(NetBoxModelSerializer, LinkTerminationSerializer, ConnectedEndpointsSerializer): +class InterfaceSerializer(NetBoxModelSerializer, CabledObjectSerializer, ConnectedEndpointsSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:interface-detail') device = NestedDeviceSerializer() module = ComponentNestedModuleSerializer( @@ -870,7 +836,6 @@ class InterfaceSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Conn ) vrf = NestedVRFSerializer(required=False, allow_null=True) l2vpn_termination = NestedL2VPNTerminationSerializer(read_only=True) - cable = NestedCableSerializer(read_only=True) wireless_link = NestedWirelessLinkSerializer(read_only=True) wireless_lans = SerializedPKRelatedField( queryset=WirelessLAN.objects.all(), @@ -887,7 +852,7 @@ class InterfaceSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Conn 'id', 'url', 'display', 'device', 'module', 'name', 'label', 'type', 'enabled', 'parent', 'bridge', 'lag', 'mtu', 'mac_address', 'speed', 'duplex', 'wwn', 'mgmt_only', 'description', 'mode', 'rf_role', 'rf_channel', 'poe_mode', 'poe_type', 'rf_channel_frequency', 'rf_channel_width', 'tx_power', 'untagged_vlan', - 'tagged_vlans', 'mark_connected', 'cable', 'wireless_link', 'link_peers', 'link_peers_type', + 'tagged_vlans', 'mark_connected', 'cable', 'cable_end', 'wireless_link', 'link_peers', 'link_peers_type', 'wireless_lans', 'vrf', 'l2vpn_termination', 'connected_endpoints', 'connected_endpoints_type', 'connected_endpoints_reachable', 'tags', 'custom_fields', 'created', 'last_updated', 'count_ipaddresses', 'count_fhrp_groups', '_occupied', @@ -907,7 +872,7 @@ class InterfaceSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Conn return super().validate(data) -class RearPortSerializer(NetBoxModelSerializer, LinkTerminationSerializer): +class RearPortSerializer(NetBoxModelSerializer, CabledObjectSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:rearport-detail') device = NestedDeviceSerializer() module = ComponentNestedModuleSerializer( @@ -915,13 +880,12 @@ class RearPortSerializer(NetBoxModelSerializer, LinkTerminationSerializer): allow_null=True ) type = ChoiceField(choices=PortTypeChoices) - cable = NestedCableSerializer(read_only=True) class Meta: model = RearPort fields = [ 'id', 'url', 'display', 'device', 'module', 'name', 'label', 'type', 'color', 'positions', 'description', - 'mark_connected', 'cable', 'link_peers', 'link_peers_type', 'tags', 'custom_fields', 'created', + 'mark_connected', 'cable', 'cable_end', 'link_peers', 'link_peers_type', 'tags', 'custom_fields', 'created', 'last_updated', '_occupied', ] @@ -937,7 +901,7 @@ class FrontPortRearPortSerializer(WritableNestedSerializer): fields = ['id', 'url', 'display', 'name', 'label'] -class FrontPortSerializer(NetBoxModelSerializer, LinkTerminationSerializer): +class FrontPortSerializer(NetBoxModelSerializer, CabledObjectSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:frontport-detail') device = NestedDeviceSerializer() module = ComponentNestedModuleSerializer( @@ -946,14 +910,13 @@ class FrontPortSerializer(NetBoxModelSerializer, LinkTerminationSerializer): ) type = ChoiceField(choices=PortTypeChoices) rear_port = FrontPortRearPortSerializer() - cable = NestedCableSerializer(read_only=True) class Meta: model = FrontPort fields = [ 'id', 'url', 'display', 'device', 'module', 'name', 'label', 'type', 'color', 'rear_port', - 'rear_port_position', 'description', 'mark_connected', 'cable', 'link_peers', 'link_peers_type', 'tags', - 'custom_fields', 'created', 'last_updated', '_occupied', + 'rear_port_position', 'description', 'mark_connected', 'cable', 'cable_end', 'link_peers', + 'link_peers_type', 'tags', 'custom_fields', 'created', 'last_updated', '_occupied', ] @@ -1204,7 +1167,7 @@ class PowerPanelSerializer(NetBoxModelSerializer): ] -class PowerFeedSerializer(NetBoxModelSerializer, LinkTerminationSerializer, ConnectedEndpointsSerializer): +class PowerFeedSerializer(NetBoxModelSerializer, CabledObjectSerializer, ConnectedEndpointsSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:powerfeed-detail') power_panel = NestedPowerPanelSerializer() rack = NestedRackSerializer( @@ -1228,13 +1191,12 @@ class PowerFeedSerializer(NetBoxModelSerializer, LinkTerminationSerializer, Conn choices=PowerFeedPhaseChoices, default=PowerFeedPhaseChoices.PHASE_SINGLE ) - cable = NestedCableSerializer(read_only=True) class Meta: model = PowerFeed fields = [ 'id', 'url', 'display', 'power_panel', 'rack', 'name', 'status', 'type', 'supply', 'phase', 'voltage', - 'amperage', 'max_utilization', 'comments', 'mark_connected', 'cable', 'link_peers', 'link_peers_type', - 'connected_endpoints', 'connected_endpoints_type', 'connected_endpoints_reachable', 'tags', 'custom_fields', - 'created', 'last_updated', '_occupied', + 'amperage', 'max_utilization', 'comments', 'mark_connected', 'cable', 'cable_end', 'link_peers', + 'link_peers_type', 'connected_endpoints', 'connected_endpoints_type', 'connected_endpoints_reachable', + 'tags', 'custom_fields', 'created', 'last_updated', '_occupied', ] diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 67af3a7f8..d54ad8384 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -3,7 +3,7 @@ from django.contrib.contenttypes.models import ContentType from django.core.exceptions import ValidationError from django.core.validators import MaxValueValidator, MinValueValidator from django.db import models -from django.db.models import Q, Sum +from django.db.models import Sum from django.urls import reverse from mptt.models import MPTTModel, TreeForeignKey @@ -23,7 +23,7 @@ from wireless.utils import get_channel_attr __all__ = ( 'BaseInterface', - 'LinkTermination', + 'CabledObjectModel', 'ConsolePort', 'ConsoleServerPort', 'DeviceBay', @@ -103,7 +103,7 @@ class ModularComponentModel(ComponentModel): abstract = True -class LinkTermination(models.Model): +class CabledObjectModel(models.Model): """ An abstract model inherited by all models to which a Cable can terminate. """ @@ -237,7 +237,7 @@ class PathEndpoint(models.Model): # Console components # -class ConsolePort(ModularComponentModel, LinkTermination, PathEndpoint): +class ConsolePort(ModularComponentModel, CabledObjectModel, PathEndpoint): """ A physical console port within a Device. ConsolePorts connect to ConsoleServerPorts. """ @@ -264,7 +264,7 @@ class ConsolePort(ModularComponentModel, LinkTermination, PathEndpoint): return reverse('dcim:consoleport', kwargs={'pk': self.pk}) -class ConsoleServerPort(ModularComponentModel, LinkTermination, PathEndpoint): +class ConsoleServerPort(ModularComponentModel, CabledObjectModel, PathEndpoint): """ A physical port within a Device (typically a designated console server) which provides access to ConsolePorts. """ @@ -295,7 +295,7 @@ class ConsoleServerPort(ModularComponentModel, LinkTermination, PathEndpoint): # Power components # -class PowerPort(ModularComponentModel, LinkTermination, PathEndpoint): +class PowerPort(ModularComponentModel, CabledObjectModel, PathEndpoint): """ A physical power supply (intake) port within a Device. PowerPorts connect to PowerOutlets. """ @@ -400,7 +400,7 @@ class PowerPort(ModularComponentModel, LinkTermination, PathEndpoint): } -class PowerOutlet(ModularComponentModel, LinkTermination, PathEndpoint): +class PowerOutlet(ModularComponentModel, CabledObjectModel, PathEndpoint): """ A physical power outlet (output) within a Device which provides power to a PowerPort. """ @@ -512,7 +512,7 @@ class BaseInterface(models.Model): return self.fhrp_group_assignments.count() -class Interface(ModularComponentModel, BaseInterface, LinkTermination, PathEndpoint): +class Interface(ModularComponentModel, BaseInterface, CabledObjectModel, PathEndpoint): """ A network interface within a Device. A physical Interface can connect to exactly one other Interface. """ @@ -837,7 +837,7 @@ class Interface(ModularComponentModel, BaseInterface, LinkTermination, PathEndpo # Pass-through ports # -class FrontPort(ModularComponentModel, LinkTermination): +class FrontPort(ModularComponentModel, CabledObjectModel): """ A pass-through port on the front of a Device. """ @@ -890,7 +890,7 @@ class FrontPort(ModularComponentModel, LinkTermination): }) -class RearPort(ModularComponentModel, LinkTermination): +class RearPort(ModularComponentModel, CabledObjectModel): """ A pass-through port on the rear of a Device. """ diff --git a/netbox/dcim/models/power.py b/netbox/dcim/models/power.py index 5978d86bd..94767c6c4 100644 --- a/netbox/dcim/models/power.py +++ b/netbox/dcim/models/power.py @@ -9,7 +9,7 @@ from dcim.constants import * from netbox.config import ConfigItem from netbox.models import NetBoxModel from utilities.validators import ExclusionValidator -from .device_components import LinkTermination, PathEndpoint +from .device_components import CabledObjectModel, PathEndpoint __all__ = ( 'PowerFeed', @@ -67,7 +67,7 @@ class PowerPanel(NetBoxModel): ) -class PowerFeed(NetBoxModel, PathEndpoint, LinkTermination): +class PowerFeed(NetBoxModel, PathEndpoint, CabledObjectModel): """ An electrical circuit delivered from a PowerPanel. """ From 1beb8522b976d83935ee07f21ad6972f79eccd09 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 6 Jul 2022 16:02:53 -0400 Subject: [PATCH 142/245] #9102: Document API changes --- docs/release-notes/version-3.3.md | 84 ++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 456afd765..e5f999048 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -6,6 +6,26 @@ * Device position and rack unit values are now reported as decimals (e.g. `1.0` or `1.5`) to support modeling half-height rack units. * The `nat_outside` relation on the IP address model now returns a list of zero or more related IP addresses, rather than a single instance (or None). +* Several fields on the cable API serializers have been altered to support multiple-object cable terminations: + +| Old Name | Old Type | New Name | New Type | +|----------------------|----------|-----------------------|----------| +| `termination_a_type` | string | `a_terminations_type` | string | +| `termination_b_type` | string | `b_terminations_type` | string | +| `termination_a_id` | integer | _Removed_ | - | +| `termination_b_id` | integer | _Removed_ | - | +| `termination_a` | object | `a_terminations` | list | +| `termination_b` | object | `b_terminations` | list | + +* As with the cable model, several API fields on all objects to which cables can be connected (interfaces, circuit terminations, etc.) have been changed: + +| Old Name | Old Type | New Name | New Type | +|--------------------------------|----------|---------------------------------|----------| +| `link_peer` | object | `link_peers` | list | +| `link_peer_type` | string | `link_peers_type` | string | +| `connected_endpoint` | object | `connected_endpoints` | list | +| `connected_endpoint_type` | string | `connected_endpoints_type` | string | +| `connected_endpoint_reachable` | boolean | `connected_endpoints_reachable` | boolean | ### New Features @@ -19,6 +39,8 @@ #### Reference User in Permission Constraints ([#9074](https://github.com/netbox-community/netbox/issues/9074)) +#### Multi-object Cable Terminations ([#9102](https://github.com/netbox-community/netbox/issues/9102)) + ### Enhancements * [#1202](https://github.com/netbox-community/netbox/issues/1202) - Support overlapping assignment of NAT IP addresses @@ -55,23 +77,83 @@ ### REST API Changes * Added the following endpoints: + * `/api/dcim/cable-terminations/` * `/api/ipam/l2vpns/` * `/api/ipam/l2vpn-terminations/` * circuits.Circuit * Added optional `termination_date` field * circuits.CircuitTermination - * Added 'custom_fields' and 'tags' fields + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` + * Added `custom_fields` and `tags` fields +* dcim.Cable + * `termination_a_type` has been renamed to `a_terminations_type` + * `termination_b_type` has been renamed to `b_terminations_type` + * `termination_a` renamed to `a_terminations` and now returns a list of objects + * `termination_b` renamed to `b_terminations` and now returns a list of objects + * `termination_a_id` has been removed + * `termination_b_id` has been removed +* dcim.ConsolePort + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` +* dcim.ConsoleServerPort + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` * dcim.Device * The `position` field has been changed from an integer to a decimal * dcim.DeviceType * The `u_height` field has been changed from an integer to a decimal +* dcim.FrontPort + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` * dcim.Interface + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` * Added the optional `poe_mode` and `poe_type` fields * Added the `l2vpn_termination` read-only field * dcim.Location * Added required `status` field (default value: `active`) +* dcim.PowerOutlet + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` +* dcim.PowerFeed + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` +* dcim.PowerPort + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` * dcim.Rack * The `elevation` endpoint now includes half-height rack units, and utilizes decimal values for the ID and name of each unit +* dcim.RearPort + * `link_peer` has been renamed to `link_peers` and now returns a list of objects + * `link_peer_type` has been renamed to `link_peers_type` + * `connected_endpoint` has been renamed to `connected_endpoints` and now returns a list of objects + * `connected_endpoint_type` has been renamed to `connected_endpoints_type` + * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` * extras.ConfigContext * Added the `locations` many-to-many field to track the assignment of ConfigContexts to Locations * extras.CustomField From 9a7f3f8c1a11ba429cf733b0f441df94dc14fdf9 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 7 Jul 2022 12:48:44 -0400 Subject: [PATCH 143/245] Cleanup for #9102 --- netbox/circuits/graphql/types.py | 3 +- netbox/dcim/api/serializers.py | 35 +++--- netbox/dcim/api/views.py | 34 +++--- netbox/dcim/choices.py | 2 +- netbox/dcim/graphql/mixins.py | 5 + netbox/dcim/graphql/types.py | 17 +-- .../migrations/0157_new_cabling_models.py | 2 +- netbox/dcim/models/cables.py | 103 ++++++++++-------- netbox/dcim/models/device_components.py | 32 +++--- netbox/dcim/models/racks.py | 6 +- netbox/dcim/signals.py | 4 +- netbox/dcim/tables/template_code.py | 26 ++--- netbox/dcim/tests/test_cablepaths.py | 13 ++- netbox/dcim/utils.py | 14 +-- netbox/dcim/views.py | 32 +++--- netbox/netbox/middleware.py | 4 +- netbox/netbox/views/__init__.py | 7 +- 17 files changed, 169 insertions(+), 170 deletions(-) create mode 100644 netbox/dcim/graphql/mixins.py diff --git a/netbox/circuits/graphql/types.py b/netbox/circuits/graphql/types.py index 094b78d07..e96fe98a5 100644 --- a/netbox/circuits/graphql/types.py +++ b/netbox/circuits/graphql/types.py @@ -1,4 +1,5 @@ from circuits import filtersets, models +from dcim.graphql.mixins import CabledObjectMixin from extras.graphql.mixins import CustomFieldsMixin, TagsMixin from netbox.graphql.types import ObjectType, OrganizationalObjectType, NetBoxObjectType @@ -11,7 +12,7 @@ __all__ = ( ) -class CircuitTerminationType(CustomFieldsMixin, TagsMixin, ObjectType): +class CircuitTerminationType(CustomFieldsMixin, TagsMixin, CabledObjectMixin, ObjectType): class Meta: model = models.CircuitTermination diff --git a/netbox/dcim/api/serializers.py b/netbox/dcim/api/serializers.py index 9938bb2e9..53205e162 100644 --- a/netbox/dcim/api/serializers.py +++ b/netbox/dcim/api/serializers.py @@ -52,16 +52,13 @@ class CabledObjectSerializer(serializers.ModelSerializer): """ Return the appropriate serializer for the link termination model. """ - if not obj.cable: + if not obj.link_peers: return [] # Return serialized peer termination objects - if obj.link_peers: - serializer = get_serializer_for_model(obj.link_peers[0], prefix='Nested') - context = {'request': self.context['request']} - return serializer(obj.link_peers, context=context, many=True).data - - return [] + serializer = get_serializer_for_model(obj.link_peers[0], prefix='Nested') + context = {'request': self.context['request']} + return serializer(obj.link_peers, context=context, many=True).data @swagger_serializer_method(serializer_or_field=serializers.BooleanField) def get__occupied(self, obj): @@ -77,8 +74,7 @@ class ConnectedEndpointsSerializer(serializers.ModelSerializer): connected_endpoints_reachable = serializers.SerializerMethodField(read_only=True) def get_connected_endpoints_type(self, obj): - endpoints = obj.connected_endpoints - if endpoints: + if endpoints := obj.connected_endpoints: return f'{endpoints[0]._meta.app_label}.{endpoints[0]._meta.model_name}' @swagger_serializer_method(serializer_or_field=serializers.ListField) @@ -86,8 +82,7 @@ class ConnectedEndpointsSerializer(serializers.ModelSerializer): """ Return the appropriate serializer for the type of connected object. """ - endpoints = obj.connected_endpoints - if endpoints: + if endpoints := obj.connected_endpoints: serializer = get_serializer_for_model(endpoints[0], prefix='Nested') context = {'request': self.context['request']} return serializer(endpoints, many=True, context=context).data @@ -1016,15 +1011,15 @@ class CableSerializer(NetBoxModelSerializer): ] def _get_terminations_type(self, obj, side): - assert side.lower() in ('a', 'b') - terms = [t.termination for t in obj.terminations.all() if t.cable_end == side.upper()] + assert side in CableEndChoices.values() + terms = getattr(obj, f'get_{side.lower()}_terminations')() if terms: ct = ContentType.objects.get_for_model(terms[0]) return f"{ct.app_label}.{ct.model}" def _get_terminations(self, obj, side): - assert side.lower() in ('a', 'b') - terms = [t.termination for t in obj.terminations.all() if t.cable_end == side.upper()] + assert side in CableEndChoices.values() + terms = getattr(obj, f'get_{side.lower()}_terminations')() if not terms: return [] @@ -1037,19 +1032,19 @@ class CableSerializer(NetBoxModelSerializer): @swagger_serializer_method(serializer_or_field=serializers.CharField) def get_a_terminations_type(self, obj): - return self._get_terminations_type(obj, 'a') + return self._get_terminations_type(obj, CableEndChoices.SIDE_A) @swagger_serializer_method(serializer_or_field=serializers.CharField) def get_b_terminations_type(self, obj): - return self._get_terminations_type(obj, 'b') + return self._get_terminations_type(obj, CableEndChoices.SIDE_B) @swagger_serializer_method(serializer_or_field=serializers.DictField) def get_a_terminations(self, obj): - return self._get_terminations(obj, 'a') + return self._get_terminations(obj, CableEndChoices.SIDE_A) @swagger_serializer_method(serializer_or_field=serializers.DictField) def get_b_terminations(self, obj): - return self._get_terminations(obj, 'b') + return self._get_terminations(obj, CableEndChoices.SIDE_B) class TracedCableSerializer(serializers.ModelSerializer): @@ -1066,7 +1061,7 @@ class TracedCableSerializer(serializers.ModelSerializer): class CableTerminationSerializer(NetBoxModelSerializer): - url = serializers.HyperlinkedIdentityField(view_name='dcim-api:cable-detail') + url = serializers.HyperlinkedIdentityField(view_name='dcim-api:cabletermination-detail') termination_type = ContentTypeField( queryset=ContentType.objects.filter(CABLE_TERMINATION_MODELS) ) diff --git a/netbox/dcim/api/views.py b/netbox/dcim/api/views.py index e6f7605ef..e71a6500d 100644 --- a/netbox/dcim/api/views.py +++ b/netbox/dcim/api/views.py @@ -15,6 +15,7 @@ from circuits.models import Circuit from dcim import filtersets from dcim.constants import CABLE_TRACE_SVG_DEFAULT_WIDTH from dcim.models import * +from dcim.svg import CableTraceSVG from extras.api.views import ConfigContextQuerySetMixin from ipam.models import Prefix, VLAN from netbox.api.authentication import IsAuthenticatedOrLoginNotRequired @@ -52,37 +53,30 @@ class PathEndpointMixin(object): # Initialize the path array path = [] + # Render SVG image if requested if request.GET.get('render', None) == 'svg': - # Render SVG try: width = int(request.GET.get('width', CABLE_TRACE_SVG_DEFAULT_WIDTH)) except (ValueError, TypeError): width = CABLE_TRACE_SVG_DEFAULT_WIDTH - drawing = obj.get_trace_svg( - base_url=request.build_absolute_uri('/'), - width=width - ) - return HttpResponse(drawing.tostring(), content_type='image/svg+xml') + drawing = CableTraceSVG(self, base_url=request.build_absolute_uri('/'), width=width) + return HttpResponse(drawing.render().tostring(), content_type='image/svg+xml') + # Serialize path objects, iterating over each three-tuple in the path for near_end, cable, far_end in obj.trace(): - if near_end is None: - # Split paths - break - - # Serialize each object - serializer_a = get_serializer_for_model(near_end[0], prefix='Nested') - x = serializer_a(near_end, many=True, context={'request': request}).data - if cable is not None: - y = serializers.TracedCableSerializer(cable[0], context={'request': request}).data + if near_end is not None: + serializer_a = get_serializer_for_model(near_end[0], prefix='Nested') + near_end = serializer_a(near_end, many=True, context={'request': request}).data else: - y = None + # Path is split; stop here + break + if cable is not None: + cable = serializers.TracedCableSerializer(cable[0], context={'request': request}).data if far_end is not None: serializer_b = get_serializer_for_model(far_end[0], prefix='Nested') - z = serializer_b(far_end, many=True, context={'request': request}).data - else: - z = None + far_end = serializer_b(far_end, many=True, context={'request': request}).data - path.append((x, y, z)) + path.append((near_end, cable, far_end)) return Response(path) diff --git a/netbox/dcim/choices.py b/netbox/dcim/choices.py index dbbc60a93..1a66312da 100644 --- a/netbox/dcim/choices.py +++ b/netbox/dcim/choices.py @@ -1294,7 +1294,7 @@ class CableEndChoices(ChoiceSet): CHOICES = ( (SIDE_A, 'A'), (SIDE_B, 'B'), - ('', ''), + # ('', ''), ) diff --git a/netbox/dcim/graphql/mixins.py b/netbox/dcim/graphql/mixins.py new file mode 100644 index 000000000..d8488aa5f --- /dev/null +++ b/netbox/dcim/graphql/mixins.py @@ -0,0 +1,5 @@ +class CabledObjectMixin: + + def resolve_cable_end(self, info): + # Handle empty values + return self.cable_end or None diff --git a/netbox/dcim/graphql/types.py b/netbox/dcim/graphql/types.py index 31589dae3..a43b293a4 100644 --- a/netbox/dcim/graphql/types.py +++ b/netbox/dcim/graphql/types.py @@ -7,6 +7,7 @@ from extras.graphql.mixins import ( from ipam.graphql.mixins import IPAddressesMixin, VLANGroupsMixin from netbox.graphql.scalars import BigInt from netbox.graphql.types import BaseObjectType, OrganizationalObjectType, NetBoxObjectType +from .mixins import CabledObjectMixin __all__ = ( 'CableType', @@ -107,7 +108,7 @@ class CableTerminationType(NetBoxObjectType): filterset_class = filtersets.CableTerminationFilterSet -class ConsolePortType(ComponentObjectType): +class ConsolePortType(ComponentObjectType, CabledObjectMixin): class Meta: model = models.ConsolePort @@ -129,7 +130,7 @@ class ConsolePortTemplateType(ComponentTemplateObjectType): return self.type or None -class ConsoleServerPortType(ComponentObjectType): +class ConsoleServerPortType(ComponentObjectType, CabledObjectMixin): class Meta: model = models.ConsoleServerPort @@ -211,7 +212,7 @@ class DeviceTypeType(NetBoxObjectType): return self.airflow or None -class FrontPortType(ComponentObjectType): +class FrontPortType(ComponentObjectType, CabledObjectMixin): class Meta: model = models.FrontPort @@ -227,7 +228,7 @@ class FrontPortTemplateType(ComponentTemplateObjectType): filterset_class = filtersets.FrontPortTemplateFilterSet -class InterfaceType(IPAddressesMixin, ComponentObjectType): +class InterfaceType(IPAddressesMixin, ComponentObjectType, CabledObjectMixin): class Meta: model = models.Interface @@ -330,7 +331,7 @@ class PlatformType(OrganizationalObjectType): filterset_class = filtersets.PlatformFilterSet -class PowerFeedType(NetBoxObjectType): +class PowerFeedType(NetBoxObjectType, CabledObjectMixin): class Meta: model = models.PowerFeed @@ -338,7 +339,7 @@ class PowerFeedType(NetBoxObjectType): filterset_class = filtersets.PowerFeedFilterSet -class PowerOutletType(ComponentObjectType): +class PowerOutletType(ComponentObjectType, CabledObjectMixin): class Meta: model = models.PowerOutlet @@ -374,7 +375,7 @@ class PowerPanelType(NetBoxObjectType): filterset_class = filtersets.PowerPanelFilterSet -class PowerPortType(ComponentObjectType): +class PowerPortType(ComponentObjectType, CabledObjectMixin): class Meta: model = models.PowerPort @@ -426,7 +427,7 @@ class RackRoleType(OrganizationalObjectType): filterset_class = filtersets.RackRoleFilterSet -class RearPortType(ComponentObjectType): +class RearPortType(ComponentObjectType, CabledObjectMixin): class Meta: model = models.RearPort diff --git a/netbox/dcim/migrations/0157_new_cabling_models.py b/netbox/dcim/migrations/0157_new_cabling_models.py index def63d8bd..e7c55997c 100644 --- a/netbox/dcim/migrations/0157_new_cabling_models.py +++ b/netbox/dcim/migrations/0157_new_cabling_models.py @@ -27,7 +27,7 @@ class Migration(migrations.Migration): ), migrations.AddConstraint( model_name='cabletermination', - constraint=models.UniqueConstraint(fields=('termination_type', 'termination_id'), name='unique_termination'), + constraint=models.UniqueConstraint(fields=('termination_type', 'termination_id'), name='dcim_cable_termination_unique_termination'), ), # Update CablePath model diff --git a/netbox/dcim/models/cables.py b/netbox/dcim/models/cables.py index 8f31c77f2..cf9f6064d 100644 --- a/netbox/dcim/models/cables.py +++ b/netbox/dcim/models/cables.py @@ -1,3 +1,4 @@ +import itertools from collections import defaultdict from django.contrib.contenttypes.fields import GenericForeignKey @@ -11,15 +12,14 @@ from django.urls import reverse from dcim.choices import * from dcim.constants import * from dcim.fields import PathField -from dcim.utils import decompile_path_node, flatten_path, object_to_path_node, path_node_to_object +from dcim.utils import decompile_path_node, object_to_path_node, path_node_to_object from netbox.models import NetBoxModel from utilities.fields import ColorField from utilities.querysets import RestrictedQuerySet from utilities.utils import to_meters from wireless.models import WirelessLink -from .devices import Device from .device_components import FrontPort, RearPort - +from .devices import Device __all__ = ( 'Cable', @@ -110,7 +110,8 @@ class Cable(NetBoxModel): # Cache the original status so we can check later if it's been changed self._orig_status = self.status - # Assign associated CableTerminations (if any) + # Assign any *new* CableTerminations for the instance. These will replace any existing + # terminations on save(). if a_terminations is not None: self.a_terminations = a_terminations if b_terminations is not None: @@ -133,28 +134,25 @@ class Cable(NetBoxModel): self.length_unit = '' a_terminations = [ - CableTermination(cable=self, cable_end='A', termination=t) for t in getattr(self, 'a_terminations', []) + CableTermination(cable=self, cable_end='A', termination=t) + for t in getattr(self, 'a_terminations', []) ] b_terminations = [ - CableTermination(cable=self, cable_end='B', termination=t) for t in getattr(self, 'b_terminations', []) + CableTermination(cable=self, cable_end='B', termination=t) + for t in getattr(self, 'b_terminations', []) ] # Check that all termination objects for either end are of the same type for terms in (a_terminations, b_terminations): - if terms and len(terms) > 1: - if not all(t.termination_type == terms[0].termination_type for t in terms[1:]): - raise ValidationError( - "Cannot connect different termination types to same end of cable." - ) + if len(terms) > 1 and not all(t.termination_type == terms[0].termination_type for t in terms[1:]): + raise ValidationError("Cannot connect different termination types to same end of cable.") # Check that termination types are compatible if a_terminations and b_terminations: a_type = a_terminations[0].termination_type.model b_type = b_terminations[0].termination_type.model if b_type not in COMPATIBLE_TERMINATION_TYPES.get(a_type): - raise ValidationError( - f"Incompatible termination types: {a_type} and {b_type}" - ) + raise ValidationError(f"Incompatible termination types: {a_type} and {b_type}") # Run clean() on any new CableTerminations for cabletermination in [*a_terminations, *b_terminations]: @@ -169,6 +167,7 @@ class Cable(NetBoxModel): else: self._abs_length = None + # TODO: Need to come with a proper solution for filtering by termination parent # Store the parent Device for the A and B terminations (if applicable) to enable filtering if hasattr(self, 'a_terminations'): self._termination_a_device = getattr(self.a_terminations[0], 'device', None) @@ -210,13 +209,15 @@ class Cable(NetBoxModel): return LinkStatusChoices.colors.get(self.status) def get_a_terminations(self): + # Query self.terminations.all() to leverage cached results return [ - term.termination for term in CableTermination.objects.filter(cable=self, cable_end='A') + ct.termination for ct in self.terminations.all() if ct.cable_end == CableEndChoices.SIDE_A ] def get_b_terminations(self): + # Query self.terminations.all() to leverage cached results return [ - term.termination for term in CableTermination.objects.filter(cable=self, cable_end='B') + ct.termination for ct in self.terminations.all() if ct.cable_end == CableEndChoices.SIDE_B ] @@ -253,7 +254,7 @@ class CableTermination(models.Model): constraints = ( models.UniqueConstraint( fields=('termination_type', 'termination_id'), - name='unique_termination' + name='dcim_cable_termination_unique_termination' ), ) @@ -289,34 +290,48 @@ class CableTermination(models.Model): # Delete the cable association on the terminating object termination_model = self.termination._meta.model - termination_model.objects.filter(pk=self.termination_id).update(cable=None, cable_end='', _path=None) + termination_model.objects.filter(pk=self.termination_id).update( + cable=None, + cable_end='' + ) super().delete(*args, **kwargs) class CablePath(models.Model): """ - A CablePath instance represents the physical path from an origin to a destination, including all intermediate - elements in the path. Every instance must specify an `origin`, whereas `destination` may be null (for paths which do - not terminate on a PathEndpoint). + A CablePath instance represents the physical path from a set of origin nodes to a set of destination nodes, + including all intermediate elements. - `path` contains a list of nodes within the path, each represented by a tuple of (type, ID). The first element in the - path must be a Cable instance, followed by a pair of pass-through ports. For example, consider the following + `path` contains the ordered set of nodes, arranged in lists of (type, ID) tuples. (Each cable in the path can + terminate to one or more objects.) For example, consider the following topology: - 1 2 3 - Interface A --- Front Port A | Rear Port A --- Rear Port B | Front Port B --- Interface B + A B C + Interface 1 --- Front Port 1 | Rear Port 1 --- Rear Port 2 | Front Port 3 --- Interface 2 + Front Port 2 Front Port 4 This path would be expressed as: CablePath( - origin = Interface A - destination = Interface B - path = [Cable 1, Front Port A, Rear Port A, Cable 2, Rear Port B, Front Port B, Cable 3] + path = [ + [Interface 1], + [Cable A], + [Front Port 1, Front Port 2], + [Rear Port 1], + [Cable B], + [Rear Port 2], + [Front Port 3, Front Port 4], + [Cable C], + [Interface 2], + ] ) - `is_active` is set to True only if 1) `destination` is not null, and 2) every Cable within the path has a status of - "connected". + `is_active` is set to True only if every Cable within the path has a status of "connected". `is_complete` is True + if the instance represents a complete end-to-end path from origin(s) to destination(s). `is_split` is True if the + path diverges across multiple cables. + + `_nodes` retains a flattened list of all nodes within the path to enable simple filtering. """ path = models.JSONField( default=list @@ -332,36 +347,32 @@ class CablePath(models.Model): ) _nodes = PathField() - class Meta: - pass - def __str__(self): - status = ' (active)' if self.is_active else ' (split)' if self.is_split else '' - return f"Path #{self.pk}: {len(self.path)} nodes{status}" + return f"Path #{self.pk}: {len(self.path)} hops" def save(self, *args, **kwargs): # Save the flattened nodes list - self._nodes = flatten_path(self.path) + self._nodes = list(itertools.chain(*self.path)) super().save(*args, **kwargs) # Record a direct reference to this CablePath on its originating object(s) - origin_model = self.origins[0]._meta.model - origin_ids = [o.id for o in self.origins] + origin_model = self.origin_type.model_class() + origin_ids = [decompile_path_node(node)[1] for node in self.path[0]] origin_model.objects.filter(pk__in=origin_ids).update(_path=self.pk) @property def origin_type(self): - ct_id, _ = decompile_path_node(self.path[0][0]) - return ContentType.objects.get_for_id(ct_id) + if self.path: + ct_id, _ = decompile_path_node(self.path[0][0]) + return ContentType.objects.get_for_id(ct_id) @property def destination_type(self): - if not self.is_complete: - return None - ct_id, _ = decompile_path_node(self.path[-1][0]) - return ContentType.objects.get_for_id(ct_id) + if self.is_complete: + ct_id, _ = decompile_path_node(self.path[-1][0]) + return ContentType.objects.get_for_id(ct_id) @property def path_objects(self): @@ -375,7 +386,7 @@ class CablePath(models.Model): @property def origins(self): """ - Return the list of originating objects (from cache, if available). + Return the list of originating objects. """ if hasattr(self, '_path_objects'): return self.path_objects[0] @@ -386,7 +397,7 @@ class CablePath(models.Model): @property def destinations(self): """ - Return the list of destination objects (from cache, if available), if the path is complete. + Return the list of destination objects, if the path is complete. """ if not self.is_complete: return [] diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index d54ad8384..d1bdd757e 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -10,7 +10,6 @@ from mptt.models import MPTTModel, TreeForeignKey from dcim.choices import * from dcim.constants import * from dcim.fields import MACAddressField, WWNField -from dcim.svg import CableTraceSVG from netbox.models import OrganizationalModel, NetBoxModel from utilities.choices import ColorChoices from utilities.fields import ColorField, NaturalOrderingField @@ -105,7 +104,8 @@ class ModularComponentModel(ComponentModel): class CabledObjectModel(models.Model): """ - An abstract model inherited by all models to which a Cable can terminate. + An abstract model inherited by all models to which a Cable can terminate. Provides the `cable` and `cable_end` + fields for caching cable associations, as well as `mark_connected` to designate "fake" connections. """ cable = models.ForeignKey( to='dcim.Cable', @@ -134,8 +134,11 @@ class CabledObjectModel(models.Model): raise ValidationError({ "cable_end": "Must specify cable end (A or B) when attaching a cable." }) - - if self.mark_connected and self.cable_id: + if self.cable_end and not self.cable: + raise ValidationError({ + "cable_end": "Cable end must not be set without a cable." + }) + if self.mark_connected and self.cable: raise ValidationError({ "mark_connected": "Cannot mark as connected with a cable attached." }) @@ -167,12 +170,13 @@ class CabledObjectModel(models.Model): """ Generic wrapper for a Cable, WirelessLink, or some other relation to a connected termination. """ + # TODO: Support WirelessLinks return self.cable class PathEndpoint(models.Model): """ - An abstract model inherited by any CableTermination subclass which represents the end of a CablePath; specifically, + An abstract model inherited by any CabledObjectModel subclass which represents the end of a CablePath; specifically, these include ConsolePort, ConsoleServerPort, PowerPort, PowerOutlet, Interface, and PowerFeed. `_path` references the CablePath originating from this instance, if any. It is set or cleared by the receivers in @@ -215,14 +219,6 @@ class PathEndpoint(models.Model): # Return the path as a list of three-tuples (A termination(s), cable(s), B termination(s)) return list(zip(*[iter(path)] * 3)) - def get_trace_svg(self, base_url=None, width=CABLE_TRACE_SVG_DEFAULT_WIDTH): - trace = CableTraceSVG(self, base_url=base_url, width=width) - return trace.render() - - @property - def path(self): - return self._path - @property def connected_endpoints(self): """ @@ -338,7 +334,15 @@ class PowerPort(ModularComponentModel, CabledObjectModel, PathEndpoint): def get_downstream_powerports(self, leg=None): """ - Return a queryset of all PowerPorts connected via cable to a child PowerOutlet. + Return a queryset of all PowerPorts connected via cable to a child PowerOutlet. For example, in the topology + below, PP1.get_downstream_powerports() would return PP2-4. + + ---- PO1 <---> PP2 + / + PP1 ------- PO2 <---> PP3 + \ + ---- PO3 <---> PP4 + """ poweroutlets = self.poweroutlets.filter(cable__isnull=False) if leg: diff --git a/netbox/dcim/models/racks.py b/netbox/dcim/models/racks.py index 3bbf38b6a..2039def09 100644 --- a/netbox/dcim/models/racks.py +++ b/netbox/dcim/models/racks.py @@ -438,9 +438,9 @@ class Rack(NetBoxModel): peer for peer in powerfeed.link_peers if isinstance(peer, PowerPort) ]) - allocated_draw = 0 - for powerport in powerports: - allocated_draw += powerport.get_power_draw()['allocated'] + allocated_draw = sum([ + powerport.get_power_draw()['allocated'] for powerport in powerports + ]) return int(allocated_draw / available_power_total * 100) diff --git a/netbox/dcim/signals.py b/netbox/dcim/signals.py index cb6b32de3..7cfdc823d 100644 --- a/netbox/dcim/signals.py +++ b/netbox/dcim/signals.py @@ -3,7 +3,7 @@ import logging from django.db.models.signals import post_save, post_delete, pre_delete from django.dispatch import receiver -from .choices import LinkStatusChoices +from .choices import CableEndChoices, LinkStatusChoices from .models import Cable, CablePath, CableTermination, Device, PathEndpoint, PowerPanel, Rack, Location, VirtualChassis from .models.cables import trace_paths from .utils import create_cablepath, rebuild_paths @@ -83,7 +83,7 @@ def update_connected_endpoints(instance, created, raw=False, **kwargs): a_terminations = [] b_terminations = [] for t in instance.terminations.all(): - if t.cable_end == 'A': + if t.cable_end == CableEndChoices.SIDE_A: a_terminations.append(t.termination) else: b_terminations.append(t.termination) diff --git a/netbox/dcim/tables/template_code.py b/netbox/dcim/tables/template_code.py index 39f40c816..a07186973 100644 --- a/netbox/dcim/tables/template_code.py +++ b/netbox/dcim/tables/template_code.py @@ -13,21 +13,17 @@ CABLE_LENGTH = """ {% if record.length %}{{ record.length|simplify_decimal }} {{ record.length_unit }}{% endif %} """ -CABLE_TERMINATION = """ -{{ value|join:", " }} -""" - -CABLE_TERMINATION_PARENT = """ -{% with value.0 as termination %} - {% if termination.device %} - {{ termination.device }} - {% elif termination.circuit %} - {{ termination.circuit }} - {% elif termination.power_panel %} - {{ termination.power_panel }} - {% endif %} -{% endwith %} -""" +# CABLE_TERMINATION_PARENT = """ +# {% with value.0 as termination %} +# {% if termination.device %} +# {{ termination.device }} +# {% elif termination.circuit %} +# {{ termination.circuit }} +# {% elif termination.power_panel %} +# {{ termination.power_panel }} +# {% endif %} +# {% endwith %} +# """ DEVICE_LINK = """ diff --git a/netbox/dcim/tests/test_cablepaths.py b/netbox/dcim/tests/test_cablepaths.py index e5b441c51..cfbbbc63b 100644 --- a/netbox/dcim/tests/test_cablepaths.py +++ b/netbox/dcim/tests/test_cablepaths.py @@ -3,6 +3,7 @@ from django.test import TestCase from circuits.models import * from dcim.choices import LinkStatusChoices from dcim.models import * +from dcim.svg import CableTraceSVG from dcim.utils import object_to_path_node @@ -107,7 +108,7 @@ class CablePathTestCase(TestCase): self.assertPathIsSet(interface2, path2) # Test SVG generation - interface1.get_trace_svg() + CableTraceSVG(interface1).render() # Delete cable 1 cable1.delete() @@ -146,7 +147,7 @@ class CablePathTestCase(TestCase): self.assertPathIsSet(consoleserverport1, path2) # Test SVG generation - consoleport1.get_trace_svg() + CableTraceSVG(consoleport1).render() # Delete cable 1 cable1.delete() @@ -185,7 +186,7 @@ class CablePathTestCase(TestCase): self.assertPathIsSet(poweroutlet1, path2) # Test SVG generation - powerport1.get_trace_svg() + CableTraceSVG(powerport1).render() # Delete cable 1 cable1.delete() @@ -224,7 +225,7 @@ class CablePathTestCase(TestCase): self.assertPathIsSet(powerfeed1, path2) # Test SVG generation - powerport1.get_trace_svg() + CableTraceSVG(powerport1).render() # Delete cable 1 cable1.delete() @@ -267,7 +268,7 @@ class CablePathTestCase(TestCase): self.assertPathIsSet(interface3, path2) # Test SVG generation - interface1.get_trace_svg() + CableTraceSVG(interface1).render() # Delete cable 1 cable1.delete() @@ -319,7 +320,7 @@ class CablePathTestCase(TestCase): self.assertPathIsSet(interface4, path2) # Test SVG generation - interface1.get_trace_svg() + CableTraceSVG(interface1).render() # Delete cable 1 cable1.delete() diff --git a/netbox/dcim/utils.py b/netbox/dcim/utils.py index e773dacc0..26b6e2e25 100644 --- a/netbox/dcim/utils.py +++ b/netbox/dcim/utils.py @@ -1,3 +1,5 @@ +import itertools + from django.contrib.contenttypes.models import ContentType from django.db import transaction @@ -29,16 +31,6 @@ def path_node_to_object(repr): return ct.model_class().objects.get(pk=object_id) -def flatten_path(path): - """ - Flatten a two-dimensional array (list of lists) into a flat list. - """ - ret = [] - for step in path: - ret.extend(step) - return ret - - def create_cablepath(terminations): """ Create CablePaths for all paths originating from the specified set of nodes. @@ -54,7 +46,7 @@ def create_cablepath(terminations): def rebuild_paths(terminations): """ - Rebuild all CablePaths which traverse the specified node + Rebuild all CablePaths which traverse the specified nodes. """ from dcim.models import CablePath diff --git a/netbox/dcim/views.py b/netbox/dcim/views.py index f6262c789..5619329ac 100644 --- a/netbox/dcim/views.py +++ b/netbox/dcim/views.py @@ -28,6 +28,18 @@ from .choices import DeviceFaceChoices from .constants import NONCONNECTABLE_IFACE_TYPES from .models import * +CABLE_TERMINATION_TYPES = { + 'dcim.consoleport': ConsolePort, + 'dcim.consoleserverport': ConsoleServerPort, + 'dcim.powerport': PowerPort, + 'dcim.poweroutlet': PowerOutlet, + 'dcim.interface': Interface, + 'dcim.frontport': FrontPort, + 'dcim.rearport': RearPort, + 'dcim.powerfeed': PowerFeed, + 'circuits.circuittermination': CircuitTermination, +} + class DeviceComponentsView(generic.ObjectChildrenView): queryset = Device.objects.all() @@ -2818,22 +2830,10 @@ class CableEditView(generic.ObjectEditView): # If creating a new Cable, initialize the form class using URL query params if 'pk' not in kwargs: - termination_types = { - 'dcim.consoleport': ConsolePort, - 'dcim.consoleserverport': ConsoleServerPort, - 'dcim.powerport': PowerPort, - 'dcim.poweroutlet': PowerOutlet, - 'dcim.interface': Interface, - 'dcim.frontport': FrontPort, - 'dcim.rearport': RearPort, - 'dcim.powerfeed': PowerFeed, - 'circuits.circuittermination': CircuitTermination, - } - - a_type = termination_types.get(request.GET.get('a_terminations_type')) - b_type = termination_types.get(request.GET.get('b_terminations_type')) - - self.form = forms.get_cable_form(a_type, b_type) + self.form = forms.get_cable_form( + a_type=CABLE_TERMINATION_TYPES.get(request.GET.get('a_terminations_type')), + b_type=CABLE_TERMINATION_TYPES.get(request.GET.get('b_terminations_type')) + ) return super().dispatch(request, *args, **kwargs) diff --git a/netbox/netbox/middleware.py b/netbox/netbox/middleware.py index cc768cbdc..5c4b2813d 100644 --- a/netbox/netbox/middleware.py +++ b/netbox/netbox/middleware.py @@ -179,8 +179,8 @@ class ExceptionHandlingMiddleware: def process_exception(self, request, exception): # Handle exceptions that occur from REST API requests - if is_api_request(request): - return rest_api_server_error(request) + # if is_api_request(request): + # return rest_api_server_error(request) # Don't catch exceptions when in debug mode if settings.DEBUG: diff --git a/netbox/netbox/views/__init__.py b/netbox/netbox/views/__init__.py index 5528faec2..666e3d28a 100644 --- a/netbox/netbox/views/__init__.py +++ b/netbox/netbox/views/__init__.py @@ -3,7 +3,6 @@ import sys from django.conf import settings from django.core.cache import cache -from django.db.models import F from django.http import HttpResponseServerError from django.shortcuts import redirect, render from django.template import loader @@ -37,13 +36,13 @@ class HomeView(View): return redirect("login") connected_consoleports = ConsolePort.objects.restrict(request.user, 'view').prefetch_related('_path').filter( - _path__is_active=True + _path__is_complete=True ) connected_powerports = PowerPort.objects.restrict(request.user, 'view').prefetch_related('_path').filter( - _path__is_active=True + _path__is_complete=True ) connected_interfaces = Interface.objects.restrict(request.user, 'view').prefetch_related('_path').filter( - _path__is_active=True + _path__is_complete=True ) def build_stats(): From 13ef5dc0b32047ac93aa671b64174e636370b065 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 7 Jul 2022 13:57:39 -0400 Subject: [PATCH 144/245] Extend Interface.link_peers() to support WirelessLinks --- netbox/dcim/models/device_components.py | 36 ++++++++++++++++--------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index d1bdd757e..85665bb43 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -143,13 +143,19 @@ class CabledObjectModel(models.Model): "mark_connected": "Cannot mark as connected with a cable attached." }) + @property + def link(self): + """ + Generic wrapper for a Cable, WirelessLink, or some other relation to a connected termination. + """ + return self.cable + @property def link_peers(self): - # TODO: Support WirelessLinks - if not self.cable: - return [] - peer_terminations = self.cable.terminations.exclude(cable_end=self.cable_end).prefetch_related('termination') - return [ct.termination for ct in peer_terminations] + if self.cable: + peers = self.cable.terminations.exclude(cable_end=self.cable_end).prefetch_related('termination') + return [peer.termination for peer in peers] + return [] @property def _occupied(self): @@ -165,14 +171,6 @@ class CabledObjectModel(models.Model): return None return CableEndChoices.SIDE_A if self.cable_end == CableEndChoices.SIDE_B else CableEndChoices.SIDE_B - @property - def link(self): - """ - Generic wrapper for a Cable, WirelessLink, or some other relation to a connected termination. - """ - # TODO: Support WirelessLinks - return self.cable - class PathEndpoint(models.Model): """ @@ -832,6 +830,18 @@ class Interface(ModularComponentModel, BaseInterface, CabledObjectModel, PathEnd def link(self): return self.cable or self.wireless_link + @property + def link_peers(self): + if self.cable: + return super().link_peers + if self.wireless_link: + # Return the opposite side of the attached wireless link + if self.wireless_link.interface_a == self: + return [self.wireless_link.interface_b] + else: + return [self.wireless_link.interface_a] + return [] + @property def l2vpn_termination(self): return self.l2vpn_terminations.first() From a858e041e4dbfaaa3d42e481e21ba033316fe5e7 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 7 Jul 2022 14:23:05 -0400 Subject: [PATCH 145/245] Cache properties which return related objects --- netbox/dcim/models/device_components.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 85665bb43..5bc3e00ff 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -1,3 +1,5 @@ +from functools import cached_property + from django.contrib.contenttypes.fields import GenericForeignKey, GenericRelation from django.contrib.contenttypes.models import ContentType from django.core.exceptions import ValidationError @@ -150,7 +152,7 @@ class CabledObjectModel(models.Model): """ return self.cable - @property + @cached_property def link_peers(self): if self.cable: peers = self.cable.terminations.exclude(cable_end=self.cable_end).prefetch_related('termination') @@ -217,14 +219,12 @@ class PathEndpoint(models.Model): # Return the path as a list of three-tuples (A termination(s), cable(s), B termination(s)) return list(zip(*[iter(path)] * 3)) - @property + @cached_property def connected_endpoints(self): """ Caching accessor for the attached CablePath's destination (if any) """ - if not hasattr(self, '_connected_endpoints'): - self._connected_endpoints = self._path.destinations if self._path else [] - return self._connected_endpoints + return self._path.destinations if self._path else [] # @@ -830,7 +830,7 @@ class Interface(ModularComponentModel, BaseInterface, CabledObjectModel, PathEnd def link(self): return self.cable or self.wireless_link - @property + @cached_property def link_peers(self): if self.cable: return super().link_peers From d444aa11101a8ed298fd1533f8c12e6925d149df Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 7 Jul 2022 14:35:02 -0400 Subject: [PATCH 146/245] Fix support for tracing across bridge relationships --- netbox/dcim/api/views.py | 2 +- netbox/dcim/models/device_components.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/netbox/dcim/api/views.py b/netbox/dcim/api/views.py index e71a6500d..cff337fcf 100644 --- a/netbox/dcim/api/views.py +++ b/netbox/dcim/api/views.py @@ -59,7 +59,7 @@ class PathEndpointMixin(object): width = int(request.GET.get('width', CABLE_TRACE_SVG_DEFAULT_WIDTH)) except (ValueError, TypeError): width = CABLE_TRACE_SVG_DEFAULT_WIDTH - drawing = CableTraceSVG(self, base_url=request.build_absolute_uri('/'), width=width) + drawing = CableTraceSVG(obj, base_url=request.build_absolute_uri('/'), width=width) return HttpResponse(drawing.render().tostring(), content_type='image/svg+xml') # Serialize path objects, iterating over each three-tuple in the path diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 5bc3e00ff..1105724c9 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -211,10 +211,10 @@ class PathEndpoint(models.Model): # by inserting empty entries immediately prior to the path's destination node(s) path.append([]) - # TODO: Add bridging support - # # Check for bridge interface to continue the trace - # origin = getattr(origin._path.destination, 'bridge', None) - origin = None + # Check for a bridged relationship to continue the trace + destinations = origin._path.destinations + if len(destinations) == 1: + origin = getattr(destinations[0], 'bridge', None) # Return the path as a list of three-tuples (A termination(s), cable(s), B termination(s)) return list(zip(*[iter(path)] * 3)) From 11707cb3b14eabec580adafb411d0ce2d2017d3f Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 7 Jul 2022 19:08:20 -0400 Subject: [PATCH 147/245] Fix trace() loop --- netbox/dcim/models/device_components.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 1105724c9..203b4469e 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -215,6 +215,8 @@ class PathEndpoint(models.Model): destinations = origin._path.destinations if len(destinations) == 1: origin = getattr(destinations[0], 'bridge', None) + else: + origin = None # Return the path as a list of three-tuples (A termination(s), cable(s), B termination(s)) return list(zip(*[iter(path)] * 3)) From 42e5282283484a20a0bde9ac860abb2579657b00 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 8 Jul 2022 11:44:28 -0400 Subject: [PATCH 148/245] Improve filtering cables by termination device/rack/site --- netbox/dcim/filtersets.py | 38 +++++---- netbox/dcim/forms/filtersets.py | 17 +++- .../migrations/0157_new_cabling_models.py | 4 + .../0158_populate_cable_terminations.py | 55 +++++++++---- .../dcim/migrations/0161_cabling_cleanup.py | 8 ++ netbox/dcim/models/cables.py | 78 +++++++++++++------ netbox/dcim/models/device_components.py | 7 ++ netbox/dcim/tests/test_filtersets.py | 41 ++++++---- 8 files changed, 177 insertions(+), 71 deletions(-) diff --git a/netbox/dcim/filtersets.py b/netbox/dcim/filtersets.py index e30ab4f04..f55b3301e 100644 --- a/netbox/dcim/filtersets.py +++ b/netbox/dcim/filtersets.py @@ -1537,27 +1537,35 @@ class CableFilterSet(TenancyFilterSet, NetBoxModelFilterSet): choices=ColorChoices ) device_id = MultiValueNumberFilter( - method='filter_device' + method='filter_by_termination' ) device = MultiValueCharFilter( - method='filter_device', + method='filter_by_termination', field_name='device__name' ) rack_id = MultiValueNumberFilter( - method='filter_device', - field_name='device__rack_id' + method='filter_by_termination', + field_name='rack_id' ) rack = MultiValueCharFilter( - method='filter_device', - field_name='device__rack__name' + method='filter_by_termination', + field_name='rack__name' + ) + location_id = MultiValueNumberFilter( + method='filter_by_termination', + field_name='location_id' + ) + location = MultiValueCharFilter( + method='filter_by_termination', + field_name='location__name' ) site_id = MultiValueNumberFilter( - method='filter_device', - field_name='device__site_id' + method='filter_by_termination', + field_name='site_id' ) site = MultiValueCharFilter( - method='filter_device', - field_name='device__site__slug' + method='filter_by_termination', + field_name='site__slug' ) class Meta: @@ -1569,12 +1577,10 @@ class CableFilterSet(TenancyFilterSet, NetBoxModelFilterSet): return queryset return queryset.filter(label__icontains=value) - def filter_device(self, queryset, name, value): - queryset = queryset.filter( - Q(**{f'_termination_a_{name}__in': value}) | - Q(**{f'_termination_b_{name}__in': value}) - ) - return queryset + def filter_by_termination(self, queryset, name, value): + # Filter by a related object cached on CableTermination. Note the underscore preceding the field name. + # Supported objects: device, rack, location, site + return queryset.filter(**{f'terminations___{name}__in': value}).distinct() class CableTerminationFilterSet(BaseFilterSet): diff --git a/netbox/dcim/forms/filtersets.py b/netbox/dcim/forms/filtersets.py index d9bc79fb5..bd64e02b4 100644 --- a/netbox/dcim/forms/filtersets.py +++ b/netbox/dcim/forms/filtersets.py @@ -730,7 +730,7 @@ class CableFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm): model = Cable fieldsets = ( (None, ('q', 'tag')), - ('Location', ('site_id', 'rack_id', 'device_id')), + ('Location', ('site_id', 'location_id', 'rack_id', 'device_id')), ('Attributes', ('type', 'status', 'color', 'length', 'length_unit')), ('Tenant', ('tenant_group_id', 'tenant_id')), ) @@ -747,13 +747,23 @@ class CableFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm): }, label=_('Site') ) + location_id = DynamicModelMultipleChoiceField( + queryset=Location.objects.all(), + required=False, + label=_('Location'), + null_option='None', + query_params={ + 'site_id': '$site_id' + } + ) rack_id = DynamicModelMultipleChoiceField( queryset=Rack.objects.all(), required=False, label=_('Rack'), null_option='None', query_params={ - 'site_id': '$site_id' + 'site_id': '$site_id', + 'location_id': '$location_id', } ) device_id = DynamicModelMultipleChoiceField( @@ -761,8 +771,9 @@ class CableFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm): required=False, query_params={ 'site_id': '$site_id', - 'tenant_id': '$tenant_id', + 'location_id': '$location_id', 'rack_id': '$rack_id', + 'tenant_id': '$tenant_id', }, label=_('Device') ) diff --git a/netbox/dcim/migrations/0157_new_cabling_models.py b/netbox/dcim/migrations/0157_new_cabling_models.py index e7c55997c..a3a650086 100644 --- a/netbox/dcim/migrations/0157_new_cabling_models.py +++ b/netbox/dcim/migrations/0157_new_cabling_models.py @@ -20,6 +20,10 @@ class Migration(migrations.Migration): ('termination_id', models.PositiveBigIntegerField()), ('cable', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='terminations', to='dcim.cable')), ('termination_type', models.ForeignKey(limit_choices_to=models.Q(models.Q(models.Q(('app_label', 'circuits'), ('model__in', ('circuittermination',))), models.Q(('app_label', 'dcim'), ('model__in', ('consoleport', 'consoleserverport', 'frontport', 'interface', 'powerfeed', 'poweroutlet', 'powerport', 'rearport'))), _connector='OR')), on_delete=django.db.models.deletion.PROTECT, related_name='+', to='contenttypes.contenttype')), + ('_device', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to='dcim.device')), + ('_rack', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to='dcim.rack')), + ('_location', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to='dcim.location')), + ('_site', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to='dcim.site')), ], options={ 'ordering': ('cable', 'cable_end', 'pk'), diff --git a/netbox/dcim/migrations/0158_populate_cable_terminations.py b/netbox/dcim/migrations/0158_populate_cable_terminations.py index c35c39a40..82f8cd359 100644 --- a/netbox/dcim/migrations/0158_populate_cable_terminations.py +++ b/netbox/dcim/migrations/0158_populate_cable_terminations.py @@ -1,10 +1,37 @@ from django.db import migrations +def cache_related_objects(termination): + """ + Replicate caching logic from CableTermination.cache_related_objects() + """ + attrs = {} + + # Device components + if getattr(termination, 'device', None): + attrs['_device'] = termination.device + attrs['_rack'] = termination.device.rack + attrs['_location'] = termination.device.location + attrs['_site'] = termination.device.site + + # Power feeds + elif getattr(termination, 'rack', None): + attrs['_rack'] = termination.rack + attrs['_location'] = termination.rack.location + attrs['_site'] = termination.rack.site + + # Circuit terminations + elif getattr(termination, 'site', None): + attrs['_site'] = termination.site + + return attrs + + def populate_cable_terminations(apps, schema_editor): """ Replicate terminations from the Cable model into CableTermination instances. """ + ContentType = apps.get_model('contenttypes', 'ContentType') Cable = apps.get_model('dcim', 'Cable') CableTermination = apps.get_model('dcim', 'CableTermination') @@ -16,22 +43,20 @@ def populate_cable_terminations(apps, schema_editor): # Queue CableTerminations to be created cable_terminations = [] for i, cable in enumerate(cables, start=1): - cable_terminations.append( - CableTermination( + for cable_end in ('a', 'b'): + # We must manually instantiate the termination object, because GFK fields are not + # supported within migrations. + termination_ct = ContentType.objects.get(pk=cable[f'termination_{cable_end}_type']) + termination_model = apps.get_model(termination_ct.app_label, termination_ct.model) + termination = termination_model.objects.get(pk=cable[f'termination_{cable_end}_id']) + + cable_terminations.append(CableTermination( cable_id=cable['id'], - cable_end='A', - termination_type_id=cable['termination_a_type'], - termination_id=cable['termination_a_id'] - ) - ) - cable_terminations.append( - CableTermination( - cable_id=cable['id'], - cable_end='B', - termination_type_id=cable['termination_b_type'], - termination_id=cable['termination_b_id'] - ) - ) + cable_end=cable_end.upper(), + termination_type_id=cable[f'termination_{cable_end}_type'], + termination_id=cable[f'termination_{cable_end}_id'], + **cache_related_objects(termination) + )) # Bulk create the termination objects CableTermination.objects.bulk_create(cable_terminations, batch_size=100) diff --git a/netbox/dcim/migrations/0161_cabling_cleanup.py b/netbox/dcim/migrations/0161_cabling_cleanup.py index db2a9b73e..8a1b7a09e 100644 --- a/netbox/dcim/migrations/0161_cabling_cleanup.py +++ b/netbox/dcim/migrations/0161_cabling_cleanup.py @@ -34,6 +34,14 @@ class Migration(migrations.Migration): model_name='cable', name='termination_b_type', ), + migrations.RemoveField( + model_name='cable', + name='_termination_a_device', + ), + migrations.RemoveField( + model_name='cable', + name='_termination_b_device', + ), # Remove old fields from CablePath migrations.AlterUniqueTogether( diff --git a/netbox/dcim/models/cables.py b/netbox/dcim/models/cables.py index cf9f6064d..551521c26 100644 --- a/netbox/dcim/models/cables.py +++ b/netbox/dcim/models/cables.py @@ -19,7 +19,6 @@ from utilities.querysets import RestrictedQuerySet from utilities.utils import to_meters from wireless.models import WirelessLink from .device_components import FrontPort, RearPort -from .devices import Device __all__ = ( 'Cable', @@ -81,22 +80,6 @@ class Cable(NetBoxModel): blank=True, null=True ) - # Cache the associated device (where applicable) for the A and B terminations. This enables filtering of Cables by - # their associated Devices. - _termination_a_device = models.ForeignKey( - to=Device, - on_delete=models.CASCADE, - related_name='+', - blank=True, - null=True - ) - _termination_b_device = models.ForeignKey( - to=Device, - on_delete=models.CASCADE, - related_name='+', - blank=True, - null=True - ) class Meta: ordering = ('pk',) @@ -167,13 +150,6 @@ class Cable(NetBoxModel): else: self._abs_length = None - # TODO: Need to come with a proper solution for filtering by termination parent - # Store the parent Device for the A and B terminations (if applicable) to enable filtering - if hasattr(self, 'a_terminations'): - self._termination_a_device = getattr(self.a_terminations[0], 'device', None) - if hasattr(self, 'b_terminations'): - self._termination_b_device = getattr(self.b_terminations[0], 'device', None) - super().save(*args, **kwargs) # Update the private pk used in __str__ in case this is a new object (i.e. just got its pk) @@ -247,6 +223,32 @@ class CableTermination(models.Model): fk_field='termination_id' ) + # Cached associations to enable efficient filtering + _device = models.ForeignKey( + to='dcim.Device', + on_delete=models.CASCADE, + blank=True, + null=True + ) + _rack = models.ForeignKey( + to='dcim.Rack', + on_delete=models.CASCADE, + blank=True, + null=True + ) + _location = models.ForeignKey( + to='dcim.Location', + on_delete=models.CASCADE, + blank=True, + null=True + ) + _site = models.ForeignKey( + to='dcim.Site', + on_delete=models.CASCADE, + blank=True, + null=True + ) + objects = RestrictedQuerySet.as_manager() class Meta: @@ -277,6 +279,10 @@ class CableTermination(models.Model): }) def save(self, *args, **kwargs): + + # Cache objects associated with the terminating object (for filtering) + self.cache_related_objects() + super().save(*args, **kwargs) # Set the cable on the terminating object @@ -297,6 +303,30 @@ class CableTermination(models.Model): super().delete(*args, **kwargs) + def cache_related_objects(self): + """ + Cache objects related to the termination (e.g. device, rack, site) directly on the object to + enable efficient filtering. + """ + assert self.termination is not None + + # Device components + if getattr(self.termination, 'device', None): + self._device = self.termination.device + self._rack = self.termination.device.rack + self._location = self.termination.device.location + self._site = self.termination.device.site + + # Power feeds + elif getattr(self.termination, 'rack', None): + self._rack = self.termination.rack + self._location = self.termination.rack.location + self._site = self.termination.rack.site + + # Circuit terminations + elif getattr(self.termination, 'site', None): + self._site = self.termination.site + class CablePath(models.Model): """ diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 203b4469e..82dacbff6 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -126,6 +126,13 @@ class CabledObjectModel(models.Model): help_text="Treat as if a cable is connected" ) + cable_terminations = GenericRelation( + to='dcim.CableTermination', + content_type_field='termination_type', + object_id_field='termination_id', + related_query_name='%(class)s', + ) + class Meta: abstract = True diff --git a/netbox/dcim/tests/test_filtersets.py b/netbox/dcim/tests/test_filtersets.py index 2d3b57d01..24c45dd7f 100644 --- a/netbox/dcim/tests/test_filtersets.py +++ b/netbox/dcim/tests/test_filtersets.py @@ -3663,6 +3663,21 @@ class CableTestCase(TestCase, ChangeLoggedFilterSetTests): ) Site.objects.bulk_create(sites) + locations = ( + Location(name='Location 1', site=sites[0], slug='location-1'), + Location(name='Location 2', site=sites[1], slug='location-1'), + Location(name='Location 3', site=sites[2], slug='location-1'), + ) + for location in locations: + location.save() + + racks = ( + Rack(name='Rack 1', site=sites[0], location=locations[0]), + Rack(name='Rack 2', site=sites[1], location=locations[1]), + Rack(name='Rack 3', site=sites[2], location=locations[2]), + ) + Rack.objects.bulk_create(racks) + tenants = ( Tenant(name='Tenant 1', slug='tenant-1'), Tenant(name='Tenant 2', slug='tenant-2'), @@ -3670,24 +3685,17 @@ class CableTestCase(TestCase, ChangeLoggedFilterSetTests): ) Tenant.objects.bulk_create(tenants) - racks = ( - Rack(name='Rack 1', site=sites[0]), - Rack(name='Rack 2', site=sites[1]), - Rack(name='Rack 3', site=sites[2]), - ) - Rack.objects.bulk_create(racks) - manufacturer = Manufacturer.objects.create(name='Manufacturer 1', slug='manufacturer-1') device_type = DeviceType.objects.create(manufacturer=manufacturer, model='Model 1', slug='model-1') device_role = DeviceRole.objects.create(name='Device Role 1', slug='device-role-1') devices = ( - Device(name='Device 1', device_type=device_type, device_role=device_role, site=sites[0], rack=racks[0], position=1), - Device(name='Device 2', device_type=device_type, device_role=device_role, site=sites[0], rack=racks[0], position=2), - Device(name='Device 3', device_type=device_type, device_role=device_role, site=sites[1], rack=racks[1], position=1), - Device(name='Device 4', device_type=device_type, device_role=device_role, site=sites[1], rack=racks[1], position=2), - Device(name='Device 5', device_type=device_type, device_role=device_role, site=sites[2], rack=racks[2], position=1), - Device(name='Device 6', device_type=device_type, device_role=device_role, site=sites[2], rack=racks[2], position=2), + Device(name='Device 1', device_type=device_type, device_role=device_role, site=sites[0], rack=racks[0], location=locations[0], position=1), + Device(name='Device 2', device_type=device_type, device_role=device_role, site=sites[0], rack=racks[0], location=locations[0], position=2), + Device(name='Device 3', device_type=device_type, device_role=device_role, site=sites[1], rack=racks[1], location=locations[1], position=1), + Device(name='Device 4', device_type=device_type, device_role=device_role, site=sites[1], rack=racks[1], location=locations[1], position=2), + Device(name='Device 5', device_type=device_type, device_role=device_role, site=sites[2], rack=racks[2], location=locations[2], position=1), + Device(name='Device 6', device_type=device_type, device_role=device_role, site=sites[2], rack=racks[2], location=locations[2], position=2), ) Device.objects.bulk_create(devices) @@ -3759,6 +3767,13 @@ class CableTestCase(TestCase, ChangeLoggedFilterSetTests): params = {'rack': [racks[0].name, racks[1].name]} self.assertEqual(self.filterset(params, self.queryset).qs.count(), 6) + def test_location(self): + locations = Location.objects.all()[:2] + params = {'location_id': [locations[0].pk, locations[1].pk]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 6) + params = {'location': [locations[0].name, locations[1].name]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 6) + def test_site(self): site = Site.objects.all()[:2] params = {'site_id': [site[0].pk, site[1].pk]} From ac4a87de1345291742b05988ca99cef074d5fd2d Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 8 Jul 2022 13:33:43 -0400 Subject: [PATCH 149/245] Improve display of related objects in cables list --- netbox/dcim/tables/cables.py | 120 +++++++++++++++++++++++------------ netbox/dcim/views.py | 5 +- 2 files changed, 83 insertions(+), 42 deletions(-) diff --git a/netbox/dcim/tables/cables.py b/netbox/dcim/tables/cables.py index f3643dd1b..ff2a672ca 100644 --- a/netbox/dcim/tables/cables.py +++ b/netbox/dcim/tables/cables.py @@ -1,5 +1,6 @@ import django_tables2 as tables from django_tables2.utils import Accessor +from django.utils.safestring import mark_safe from dcim.models import Cable from netbox.tables import NetBoxTable, columns @@ -11,20 +12,34 @@ __all__ = ( ) -class CableTerminationsColumn(tables.TemplateColumn): +class CableTerminationsColumn(tables.Column): + """ + Args: + cable_end: Which side of the cable to report on (A or B) + attr: The CableTermination attribute to return for each instance (returns the termination object by default) + """ + def __init__(self, cable_end, attr='termination', *args, **kwargs): + self.cable_end = cable_end + self.attr = attr + super().__init__(accessor=Accessor('terminations'), *args, **kwargs) - def __init__(self, cable_end, *args, **kwargs): - template_code = """ - {% for term in value.all %} - {% if term.cable_end == '""" + cable_end + """' %} - {{ term.termination }} - {% endif %} - {% endfor %} - """ - super().__init__(template_code=template_code, *args, **kwargs) + def _get_terminations(self, manager): + terminations = set() + for cabletermination in manager.all(): + if cabletermination.cable_end == self.cable_end: + if termination := getattr(cabletermination, self.attr, None): + terminations.add(termination) + + return terminations + + def render(self, value): + links = [ + f'{term}' for term in self._get_terminations(value) + ] + return mark_safe('
    '.join(links) or '—') def value(self, value): - return ', '.join([str(t.termination) for t in value.all()]) + return ','.join([str(t) for t in self._get_terminations(value)]) # @@ -32,41 +47,63 @@ class CableTerminationsColumn(tables.TemplateColumn): # class CableTable(NetBoxTable): - # termination_a_parent = tables.TemplateColumn( - # template_code=CABLE_TERMINATION_PARENT, - # accessor=Accessor('termination_a'), - # orderable=False, - # verbose_name='Side A' - # ) - # rack_a = tables.Column( - # accessor=Accessor('termination_a__device__rack'), - # orderable=False, - # linkify=True, - # verbose_name='Rack A' - # ) - # termination_b_parent = tables.TemplateColumn( - # template_code=CABLE_TERMINATION_PARENT, - # accessor=Accessor('termination_b'), - # orderable=False, - # verbose_name='Side B' - # ) - # rack_b = tables.Column( - # accessor=Accessor('termination_b__device__rack'), - # orderable=False, - # linkify=True, - # verbose_name='Rack B' - # ) a_terminations = CableTerminationsColumn( cable_end='A', - accessor=Accessor('terminations'), orderable=False, - verbose_name='A Side' + verbose_name='Termination A' ) b_terminations = CableTerminationsColumn( cable_end='B', - accessor=Accessor('terminations'), orderable=False, - verbose_name='B Side' + verbose_name='Termination B' + ) + device_a = CableTerminationsColumn( + cable_end='A', + attr='_device', + orderable=False, + verbose_name='Device A' + ) + device_b = CableTerminationsColumn( + cable_end='B', + attr='_device', + orderable=False, + verbose_name='Device B' + ) + location_a = CableTerminationsColumn( + cable_end='A', + attr='_location', + orderable=False, + verbose_name='Location A' + ) + location_b = CableTerminationsColumn( + cable_end='B', + attr='_location', + orderable=False, + verbose_name='Location B' + ) + rack_a = CableTerminationsColumn( + cable_end='A', + attr='_rack', + orderable=False, + verbose_name='Rack A' + ) + rack_b = CableTerminationsColumn( + cable_end='B', + attr='_rack', + orderable=False, + verbose_name='Rack B' + ) + site_a = CableTerminationsColumn( + cable_end='A', + attr='_site', + orderable=False, + verbose_name='Site A' + ) + site_b = CableTerminationsColumn( + cable_end='B', + attr='_site', + orderable=False, + verbose_name='Site B' ) status = columns.ChoiceFieldColumn() tenant = TenantColumn() @@ -82,8 +119,9 @@ class CableTable(NetBoxTable): class Meta(NetBoxTable.Meta): model = Cable fields = ( - 'pk', 'id', 'label', 'a_terminations', 'b_terminations', 'status', 'type', 'tenant', 'color', 'length', - 'tags', 'created', 'last_updated', + 'pk', 'id', 'label', 'a_terminations', 'b_terminations', 'device_a', 'device_b', 'rack_a', 'rack_b', + 'location_a', 'location_b', 'site_a', 'site_b', 'status', 'type', 'tenant', 'color', 'length', 'tags', + 'created', 'last_updated', ) default_columns = ( 'pk', 'id', 'label', 'a_terminations', 'b_terminations', 'status', 'type', diff --git a/netbox/dcim/views.py b/netbox/dcim/views.py index 5619329ac..1f2f04d7a 100644 --- a/netbox/dcim/views.py +++ b/netbox/dcim/views.py @@ -2756,7 +2756,10 @@ class DeviceBulkAddInventoryItemView(generic.BulkComponentCreateView): # class CableListView(generic.ObjectListView): - queryset = Cable.objects.prefetch_related('terminations__termination') + queryset = Cable.objects.prefetch_related( + 'terminations__termination', 'terminations___device', 'terminations___rack', 'terminations___location', + 'terminations___site', + ) filterset = filtersets.CableFilterSet filterset_form = forms.CableFilterForm table = tables.CableTable From f386ec82ae3086cc9e470148bc25fa23555b5199 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 8 Jul 2022 13:55:13 -0400 Subject: [PATCH 150/245] Fix CablePath serialization for pass-through port paths --- docs/release-notes/version-3.3.md | 2 ++ netbox/dcim/api/serializers.py | 34 ++++--------------------------- 2 files changed, 6 insertions(+), 30 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index e5f999048..ac499f806 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -27,6 +27,8 @@ | `connected_endpoint_type` | string | `connected_endpoints_type` | string | | `connected_endpoint_reachable` | boolean | `connected_endpoints_reachable` | boolean | +* The cable path serialization returned by the `/paths/` endpoint for pass-through ports has been simplified, and the following fields removed: `origin_type`, `origin`, `destination_type`, `destination`. (Additionally, `is_complete` has been added.) + ### New Features #### Half-Height Rack Units ([#51](https://github.com/netbox-community/netbox/issues/51)) diff --git a/netbox/dcim/api/serializers.py b/netbox/dcim/api/serializers.py index 53205e162..08edd2820 100644 --- a/netbox/dcim/api/serializers.py +++ b/netbox/dcim/api/serializers.py @@ -1081,45 +1081,19 @@ class CableTerminationSerializer(NetBoxModelSerializer): class CablePathSerializer(serializers.ModelSerializer): - origin_type = ContentTypeField(read_only=True) - origin = serializers.SerializerMethodField(read_only=True) - destination_type = ContentTypeField(read_only=True) - destination = serializers.SerializerMethodField(read_only=True) path = serializers.SerializerMethodField(read_only=True) class Meta: model = CablePath - fields = [ - 'id', 'origin_type', 'origin', 'destination_type', 'destination', 'path', 'is_active', 'is_split', - ] - - @swagger_serializer_method(serializer_or_field=serializers.DictField) - def get_origin(self, obj): - """ - Return the appropriate serializer for the origin. - """ - serializer = get_serializer_for_model(obj.origin, prefix='Nested') - context = {'request': self.context['request']} - return serializer(obj.origin, context=context).data - - @swagger_serializer_method(serializer_or_field=serializers.DictField) - def get_destination(self, obj): - """ - Return the appropriate serializer for the destination, if any. - """ - if obj.destination_id is not None: - serializer = get_serializer_for_model(obj.destination, prefix='Nested') - context = {'request': self.context['request']} - return serializer(obj.destination, context=context).data - return None + fields = ['id', 'path', 'is_active', 'is_complete', 'is_split'] @swagger_serializer_method(serializer_or_field=serializers.ListField) def get_path(self, obj): ret = [] - for node in obj.path_objects(): - serializer = get_serializer_for_model(node, prefix='Nested') + for nodes in obj.path_objects: + serializer = get_serializer_for_model(nodes[0], prefix='Nested') context = {'request': self.context['request']} - ret.append(serializer(node, context=context).data) + ret.append(serializer(nodes, context=context, many=True).data) return ret From 531d961d30bdcd91ff1b9ffc7d3f147f481e0101 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 11 Jul 2022 14:47:15 -0400 Subject: [PATCH 151/245] Add API tokens to user menu --- netbox/templates/inc/profile_button.html | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/netbox/templates/inc/profile_button.html b/netbox/templates/inc/profile_button.html index 1e562651f..e48ec2148 100644 --- a/netbox/templates/inc/profile_button.html +++ b/netbox/templates/inc/profile_button.html @@ -28,6 +28,11 @@ Preferences +
  • + + API Tokens + +
  • From 123e758c6d86d6a1605ebdf076e36b4c3acaf8f3 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 11 Jul 2022 15:43:59 -0400 Subject: [PATCH 152/245] Closes #9708: Render user API tokens in a table --- netbox/templates/inc/profile_button.html | 6 +- netbox/templates/users/api_tokens.html | 87 +++++------------------- netbox/templates/users/base.html | 8 +-- netbox/templates/users/password.html | 2 +- netbox/templates/users/preferences.html | 2 +- netbox/users/tables.py | 42 ++++++++++++ netbox/users/urls.py | 2 +- netbox/users/views.py | 24 ++++--- 8 files changed, 83 insertions(+), 90 deletions(-) create mode 100644 netbox/users/tables.py diff --git a/netbox/templates/inc/profile_button.html b/netbox/templates/inc/profile_button.html index e48ec2148..b63b25464 100644 --- a/netbox/templates/inc/profile_button.html +++ b/netbox/templates/inc/profile_button.html @@ -19,17 +19,17 @@ {% endif %}
  • - + Profile
  • - + Preferences
  • - + API Tokens
    • diff --git a/netbox/templates/users/api_tokens.html b/netbox/templates/users/api_tokens.html index 24b32cc9b..e1641468c 100644 --- a/netbox/templates/users/api_tokens.html +++ b/netbox/templates/users/api_tokens.html @@ -1,78 +1,25 @@ {% extends 'users/base.html' %} {% load helpers %} +{% load render_table from django_tables2 %} {% block title %}API Tokens{% endblock %} {% block content %} -
    -
    - {% for token in tokens %} -
    -
    -
    - Copy - Edit - Delete -
    - - {{ token.key }} - {% if token.is_expired %} - Expired - {% endif %} -
    -
    -
    -
    - Created
    - {{ token.created|annotated_date }} -
    -
    - Expires
    - {% if token.expires %} - {{ token.expires|annotated_date }} - {% else %} - Never - {% endif %} -
    -
    - Last Used
    - {% if token.last_used %} - {{ token.last_used|annotated_date }} - {% else %} - Never - {% endif %} -
    -
    - Create/Edit/Delete Operations
    - {% if token.write_enabled %} - Enabled - {% else %} - Disabled - {% endif %} -
    -
    - Allowed Source IPs
    - {% if token.allowed_ips %} - {{ token.allowed_ips|join:', ' }} - {% else %} - Any - {% endif %} -
    - {% if token.description %} -
    {{ token.description }} - {% endif %} -
    -
    - {% empty %} -
    You do not have any API tokens.
    -

    Tokens are used to authenticate REST and GraphQL API requests.

    - {% endfor %} -
    - - - Add a Token - -
    -
    +
    +
    + + Add a Token + +
    +
    +
    +
    +
    +
    + {% render_table table 'inc/table.html' %} + {% include 'inc/paginator.html' with paginator=table.paginator page=table.page %} +
    +
    +
    {% endblock %} diff --git a/netbox/templates/users/base.html b/netbox/templates/users/base.html index cf4cd585d..58861ee90 100644 --- a/netbox/templates/users/base.html +++ b/netbox/templates/users/base.html @@ -3,18 +3,18 @@ {% block tabs %} {% endblock %} diff --git a/netbox/templates/users/password.html b/netbox/templates/users/password.html index 81082792d..02e80bb26 100644 --- a/netbox/templates/users/password.html +++ b/netbox/templates/users/password.html @@ -13,7 +13,7 @@ {% render_field form.new_password2 %}
    - Cancel + Cancel
    diff --git a/netbox/templates/users/preferences.html b/netbox/templates/users/preferences.html index 6ce60a458..f2c88db3c 100644 --- a/netbox/templates/users/preferences.html +++ b/netbox/templates/users/preferences.html @@ -79,7 +79,7 @@
    - Cancel + Cancel
    diff --git a/netbox/users/tables.py b/netbox/users/tables.py new file mode 100644 index 000000000..27547b955 --- /dev/null +++ b/netbox/users/tables.py @@ -0,0 +1,42 @@ +from .models import Token +from netbox.tables import NetBoxTable, columns + +__all__ = ( + 'TokenTable', +) + + +TOKEN = """{{ value }}""" + +ALLOWED_IPS = """{{ value|join:", " }}""" + +COPY_BUTTON = """ + + + +""" + + +class TokenTable(NetBoxTable): + key = columns.TemplateColumn( + template_code=TOKEN + ) + write_enabled = columns.BooleanColumn( + verbose_name='Write' + ) + created = columns.DateColumn() + expired = columns.DateColumn() + last_used = columns.DateTimeColumn() + allowed_ips = columns.TemplateColumn( + template_code=ALLOWED_IPS + ) + actions = columns.ActionsColumn( + actions=('edit', 'delete'), + extra_buttons=COPY_BUTTON + ) + + class Meta(NetBoxTable.Meta): + model = Token + fields = ( + 'pk', 'key', 'write_enabled', 'created', 'expires', 'last_used', 'allowed_ips', 'description', + ) diff --git a/netbox/users/urls.py b/netbox/users/urls.py index 0cfcfc9de..62b17a663 100644 --- a/netbox/users/urls.py +++ b/netbox/users/urls.py @@ -2,7 +2,7 @@ from django.urls import path from . import views -app_name = 'user' +app_name = 'users' urlpatterns = [ path('profile/', views.ProfileView.as_view(), name='profile'), diff --git a/netbox/users/views.py b/netbox/users/views.py index 6a923e77e..aabdd6774 100644 --- a/netbox/users/views.py +++ b/netbox/users/views.py @@ -21,6 +21,7 @@ from netbox.config import get_config from utilities.forms import ConfirmationForm from .forms import LoginForm, PasswordChangeForm, TokenForm, UserConfigForm from .models import Token +from .tables import TokenTable # @@ -157,7 +158,7 @@ class UserConfigView(LoginRequiredMixin, View): form.save() messages.success(request, "Your preferences have been updated.") - return redirect('user:preferences') + return redirect('users:preferences') return render(request, self.template_name, { 'form': form, @@ -172,7 +173,7 @@ class ChangePasswordView(LoginRequiredMixin, View): # LDAP users cannot change their password here if getattr(request.user, 'ldap_username', None): messages.warning(request, "LDAP-authenticated user credentials cannot be changed within NetBox.") - return redirect('user:profile') + return redirect('users:profile') form = PasswordChangeForm(user=request.user) @@ -187,7 +188,7 @@ class ChangePasswordView(LoginRequiredMixin, View): form.save() update_session_auth_hash(request, form.user) messages.success(request, "Your password has been changed successfully.") - return redirect('user:profile') + return redirect('users:profile') return render(request, self.template_name, { 'form': form, @@ -204,10 +205,13 @@ class TokenListView(LoginRequiredMixin, View): def get(self, request): tokens = Token.objects.filter(user=request.user) + table = TokenTable(tokens) + table.configure(request) return render(request, 'users/api_tokens.html', { 'tokens': tokens, 'active_tab': 'api-tokens', + 'table': table, }) @@ -225,7 +229,7 @@ class TokenEditView(LoginRequiredMixin, View): return render(request, 'generic/object_edit.html', { 'object': token, 'form': form, - 'return_url': reverse('user:token_list'), + 'return_url': reverse('users:token_list'), }) def post(self, request, pk=None): @@ -248,12 +252,12 @@ class TokenEditView(LoginRequiredMixin, View): if '_addanother' in request.POST: return redirect(request.path) else: - return redirect('user:token_list') + return redirect('users:token_list') return render(request, 'generic/object_edit.html', { 'object': token, 'form': form, - 'return_url': reverse('user:token_list'), + 'return_url': reverse('users:token_list'), }) @@ -263,14 +267,14 @@ class TokenDeleteView(LoginRequiredMixin, View): token = get_object_or_404(Token.objects.filter(user=request.user), pk=pk) initial_data = { - 'return_url': reverse('user:token_list'), + 'return_url': reverse('users:token_list'), } form = ConfirmationForm(initial=initial_data) return render(request, 'generic/object_delete.html', { 'object': token, 'form': form, - 'return_url': reverse('user:token_list'), + 'return_url': reverse('users:token_list'), }) def post(self, request, pk): @@ -280,10 +284,10 @@ class TokenDeleteView(LoginRequiredMixin, View): if form.is_valid(): token.delete() messages.success(request, "Token deleted") - return redirect('user:token_list') + return redirect('users:token_list') return render(request, 'generic/object_delete.html', { 'object': token, 'form': form, - 'return_url': reverse('user:token_list'), + 'return_url': reverse('users:token_list'), }) From 8a8ada852959c745103e8351cf5d4ea83a96c114 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 11 Jul 2022 16:14:46 -0400 Subject: [PATCH 153/245] #9177: Use TenancyColumnsMixin (from #9686) --- netbox/wireless/tables/wirelesslan.py | 9 ++++----- netbox/wireless/tables/wirelesslink.py | 9 ++++----- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/netbox/wireless/tables/wirelesslan.py b/netbox/wireless/tables/wirelesslan.py index fc791d730..af0cdae88 100644 --- a/netbox/wireless/tables/wirelesslan.py +++ b/netbox/wireless/tables/wirelesslan.py @@ -2,7 +2,7 @@ import django_tables2 as tables from dcim.models import Interface from netbox.tables import NetBoxTable, columns -from tenancy.tables import TenantColumn +from tenancy.tables import TenancyColumnsMixin from wireless.models import * __all__ = ( @@ -33,14 +33,13 @@ class WirelessLANGroupTable(NetBoxTable): default_columns = ('pk', 'name', 'wirelesslan_count', 'description') -class WirelessLANTable(NetBoxTable): +class WirelessLANTable(TenancyColumnsMixin, NetBoxTable): ssid = tables.Column( linkify=True ) group = tables.Column( linkify=True ) - tenant = TenantColumn() interface_count = tables.Column( verbose_name='Interfaces' ) @@ -51,8 +50,8 @@ class WirelessLANTable(NetBoxTable): class Meta(NetBoxTable.Meta): model = WirelessLAN fields = ( - 'pk', 'ssid', 'group', 'tenant', 'description', 'vlan', 'interface_count', 'auth_type', 'auth_cipher', - 'auth_psk', 'tags', 'created', 'last_updated', + 'pk', 'ssid', 'group', 'tenant', 'tenant_group', 'description', 'vlan', 'interface_count', 'auth_type', + 'auth_cipher', 'auth_psk', 'tags', 'created', 'last_updated', ) default_columns = ('pk', 'ssid', 'group', 'description', 'vlan', 'auth_type', 'interface_count') diff --git a/netbox/wireless/tables/wirelesslink.py b/netbox/wireless/tables/wirelesslink.py index 6a45a21ae..0135ce620 100644 --- a/netbox/wireless/tables/wirelesslink.py +++ b/netbox/wireless/tables/wirelesslink.py @@ -1,7 +1,7 @@ import django_tables2 as tables from netbox.tables import NetBoxTable, columns -from tenancy.tables import TenantColumn +from tenancy.tables import TenancyColumnsMixin from wireless.models import * __all__ = ( @@ -9,7 +9,7 @@ __all__ = ( ) -class WirelessLinkTable(NetBoxTable): +class WirelessLinkTable(TenancyColumnsMixin, NetBoxTable): id = tables.Column( linkify=True, verbose_name='ID' @@ -29,7 +29,6 @@ class WirelessLinkTable(NetBoxTable): interface_b = tables.Column( linkify=True ) - tenant = TenantColumn() tags = columns.TagColumn( url_name='wireless:wirelesslink_list' ) @@ -37,8 +36,8 @@ class WirelessLinkTable(NetBoxTable): class Meta(NetBoxTable.Meta): model = WirelessLink fields = ( - 'pk', 'id', 'status', 'device_a', 'interface_a', 'device_b', 'interface_b', 'ssid', 'tenant', 'description', - 'auth_type', 'auth_cipher', 'auth_psk', 'tags', 'created', 'last_updated', + 'pk', 'id', 'status', 'device_a', 'interface_a', 'device_b', 'interface_b', 'ssid', 'tenant', + 'tenant_group', 'description', 'auth_type', 'auth_cipher', 'auth_psk', 'tags', 'created', 'last_updated', ) default_columns = ( 'pk', 'id', 'status', 'device_a', 'interface_a', 'device_b', 'interface_b', 'ssid', 'auth_type', From 2264937f815acef7500a79796b70482cb33a15d3 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 11 Jul 2022 17:11:58 -0400 Subject: [PATCH 154/245] Consolidate custom field migrations --- ..._name.py => 0074_customfield_extensions.py} | 5 +++++ ...ions.py => 0075_configcontext_locations.py} | 2 +- .../0075_customfield_ui_visibility.py | 18 ------------------ netbox/ipam/migrations/0059_l2vpn.py | 2 +- 4 files changed, 7 insertions(+), 20 deletions(-) rename netbox/extras/migrations/{0074_customfield_group_name.py => 0074_customfield_extensions.py} (75%) rename netbox/extras/migrations/{0076_configcontext_locations.py => 0075_configcontext_locations.py} (88%) delete mode 100644 netbox/extras/migrations/0075_customfield_ui_visibility.py diff --git a/netbox/extras/migrations/0074_customfield_group_name.py b/netbox/extras/migrations/0074_customfield_extensions.py similarity index 75% rename from netbox/extras/migrations/0074_customfield_group_name.py rename to netbox/extras/migrations/0074_customfield_extensions.py index e1be76b1f..6ca8b958f 100644 --- a/netbox/extras/migrations/0074_customfield_group_name.py +++ b/netbox/extras/migrations/0074_customfield_extensions.py @@ -19,4 +19,9 @@ class Migration(migrations.Migration): name='group_name', field=models.CharField(blank=True, max_length=50), ), + migrations.AddField( + model_name='customfield', + name='ui_visibility', + field=models.CharField(default='read-write', max_length=50), + ), ] diff --git a/netbox/extras/migrations/0076_configcontext_locations.py b/netbox/extras/migrations/0075_configcontext_locations.py similarity index 88% rename from netbox/extras/migrations/0076_configcontext_locations.py rename to netbox/extras/migrations/0075_configcontext_locations.py index f9b3a664b..853aec4f7 100644 --- a/netbox/extras/migrations/0076_configcontext_locations.py +++ b/netbox/extras/migrations/0075_configcontext_locations.py @@ -7,7 +7,7 @@ class Migration(migrations.Migration): dependencies = [ ('dcim', '0156_location_status'), - ('extras', '0075_customfield_ui_visibility'), + ('extras', '0074_customfield_extensions'), ] operations = [ diff --git a/netbox/extras/migrations/0075_customfield_ui_visibility.py b/netbox/extras/migrations/0075_customfield_ui_visibility.py deleted file mode 100644 index 29ee65516..000000000 --- a/netbox/extras/migrations/0075_customfield_ui_visibility.py +++ /dev/null @@ -1,18 +0,0 @@ -# Generated by Django 4.0.4 on 2022-05-23 20:23 - -from django.db import migrations, models - - -class Migration(migrations.Migration): - - dependencies = [ - ('extras', '0074_customfield_group_name'), - ] - - operations = [ - migrations.AddField( - model_name='customfield', - name='ui_visibility', - field=models.CharField(default='read-write', max_length=50), - ), - ] diff --git a/netbox/ipam/migrations/0059_l2vpn.py b/netbox/ipam/migrations/0059_l2vpn.py index 5662049c3..ef670ddea 100644 --- a/netbox/ipam/migrations/0059_l2vpn.py +++ b/netbox/ipam/migrations/0059_l2vpn.py @@ -9,7 +9,7 @@ import taggit.managers class Migration(migrations.Migration): dependencies = [ - ('extras', '0076_configcontext_locations'), + ('extras', '0075_configcontext_locations'), ('contenttypes', '0002_remove_content_type_name'), ('tenancy', '0007_contact_link'), ('ipam', '0058_ipaddress_nat_inside_nonunique'), From 1ddb219a0cd0232524fe18638cb7f4265fb00a48 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 11 Jul 2022 17:29:25 -0400 Subject: [PATCH 155/245] Documentation cleanup --- docs/configuration/optional-settings.md | 2 ++ docs/models/extras/customfield.md | 30 ++++++++++++++++++--- docs/models/users/objectpermission.md | 2 +- docs/models/users/token.md | 9 ++++++- docs/plugins/development/models.md | 4 +-- mkdocs.yml | 2 +- netbox/extras/webhooks.py | 2 +- netbox/netbox/views/generic/object_views.py | 3 ++- netbox/users/forms.py | 2 +- 9 files changed, 45 insertions(+), 11 deletions(-) diff --git a/docs/configuration/optional-settings.md b/docs/configuration/optional-settings.md index 3b1c848a7..8e5664a95 100644 --- a/docs/configuration/optional-settings.md +++ b/docs/configuration/optional-settings.md @@ -212,6 +212,7 @@ The following model fields support configurable choices: * `circuits.Circuit.status` * `dcim.Device.status` +* `dcim.Location.status` * `dcim.PowerFeed.status` * `dcim.Rack.status` * `dcim.Site.status` @@ -220,6 +221,7 @@ The following model fields support configurable choices: * `ipam.IPRange.status` * `ipam.Prefix.status` * `ipam.VLAN.status` +* `virtualization.Cluster.status` * `virtualization.VirtualMachine.status` The following colors are supported: diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md index e0c01688d..3f6860758 100644 --- a/docs/models/extras/customfield.md +++ b/docs/models/extras/customfield.md @@ -26,11 +26,35 @@ Each custom field must have a name. This should be a simple database-friendly st Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. -The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. - A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. -### Custom Field Validation +### Filtering + +The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. + +### Grouping + +!!! note + This feature was introduced in NetBox v3.3. + +Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) + +This parameter has no effect on the API representation of custom field data. + +### Visibility + +!!! note + This feature was introduced in NetBox v3.3. + +When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. + +* **Read/write** (default): The custom field is included when viewing and editing objects. +* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. + +Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. + +### Validation NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: diff --git a/docs/models/users/objectpermission.md b/docs/models/users/objectpermission.md index 075a2cae5..82dbc955a 100644 --- a/docs/models/users/objectpermission.md +++ b/docs/models/users/objectpermission.md @@ -54,7 +54,7 @@ To achieve a logical OR with a different set of constraints, define multiple obj Additionally, where multiple permissions have been assigned for an object type, their collective constraints will be merged using a logical "OR" operation. -### Tokens +### User Token !!! info "This feature was introduced in NetBox v3.3" diff --git a/docs/models/users/token.md b/docs/models/users/token.md index 367444477..f6c5bfe80 100644 --- a/docs/models/users/token.md +++ b/docs/models/users/token.md @@ -9,4 +9,11 @@ Each token contains a 160-bit key represented as 40 hexadecimal characters. When By default, a token can be used to perform all actions via the API that a user would be permitted to do via the web UI. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only. -Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox. Tokens can also be restricted by IP range: If defined, authentication for API clients connecting from an IP address outside these ranges will fail. +Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox. + +### Client IP Restriction + +!!! note + This feature was introduced in NetBox v3.3. + +Each API token can optionally be restricted by client IP address. If one or more allowed IP prefixes/addresses is defined for a token, authentication will fail for any client connecting from an IP address outside the defined range(s). This enables restricting the use a token to a specific client. (By default, any client IP address is permitted.) diff --git a/docs/plugins/development/models.md b/docs/plugins/development/models.md index 43e3cad9a..6d7075b80 100644 --- a/docs/plugins/development/models.md +++ b/docs/plugins/development/models.md @@ -37,7 +37,7 @@ This class performs two crucial functions: 1. Apply any fields, methods, and/or attributes necessary to the operation of these features 2. Register the model with NetBox as utilizing these features -Simply subclass BaseModel when defining a model in your plugin: +Simply subclass NetBoxModel when defining a model in your plugin: ```python # models.py @@ -54,7 +54,7 @@ class MyModel(NetBoxModel): !!! info This method was introduced in NetBox v3.3. -The `NetBoxModel` class includes a `clone()` method to be used for gathering attriubtes which can be used to create a "cloned" instance. This is used primarily for form initialization, e.g. when using the "clone" button in the NetBox UI. By default, this method will replicate any fields listed in the model's `clone_fields` list, if defined. +The `NetBoxModel` class includes a `clone()` method to be used for gathering attributes which can be used to create a "cloned" instance. This is used primarily for form initialization, e.g. when using the "clone" button in the NetBox UI. By default, this method will replicate any fields listed in the model's `clone_fields` list, if defined. Plugin models can leverage this method by defining `clone_fields` as a list of field names to be replicated, or override this method to replace or extend its content: diff --git a/mkdocs.yml b/mkdocs.yml index 88a2794e8..5e9f4b842 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -131,7 +131,7 @@ nav: - NetBox Shell: 'administration/netbox-shell.md' - REST API: - Overview: 'rest-api/overview.md' - - Filtering: 'rest-api/filtering.md' + - Filtering & Ordering: 'rest-api/filtering.md' - Authentication: 'rest-api/authentication.md' - GraphQL API: - Overview: 'graphql-api/overview.md' diff --git a/netbox/extras/webhooks.py b/netbox/extras/webhooks.py index 334539026..bef90a245 100644 --- a/netbox/extras/webhooks.py +++ b/netbox/extras/webhooks.py @@ -31,7 +31,7 @@ def get_snapshots(instance, action): 'postchange': None, } if action != ObjectChangeActionChoices.ACTION_DELETE: - # Use model's serialize() method if defined; fall back to serialize_object + # Use model's serialize_object() method if defined; fall back to serialize_object() utility function if hasattr(instance, 'serialize_object'): snapshots['postchange'] = instance.serialize_object() else: diff --git a/netbox/netbox/views/generic/object_views.py b/netbox/netbox/views/generic/object_views.py index dc078a7e2..cb3f58123 100644 --- a/netbox/netbox/views/generic/object_views.py +++ b/netbox/netbox/views/generic/object_views.py @@ -72,7 +72,8 @@ class ObjectView(BaseObjectView): class ObjectChildrenView(ObjectView, ActionsMixin, TableMixin): """ - Display a table of child objects associated with the parent object. + Display a table of child objects associated with the parent object. For example, NetBox uses this to display + the set of child IP addresses within a parent prefix. Attributes: child_model: The model class which represents the child objects diff --git a/netbox/users/forms.py b/netbox/users/forms.py index 8692eb050..b4e86461d 100644 --- a/netbox/users/forms.py +++ b/netbox/users/forms.py @@ -106,7 +106,7 @@ class TokenForm(BootstrapMixin, forms.ModelForm): required=False, label='Allowed IPs', help_text='Allowed IPv4/IPv6 networks from where the token can be used. Leave blank for no restrictions. ' - 'Ex: "10.1.1.0/24, 192.168.10.16/32, 2001:DB8:1::/64"', + 'Example: 10.1.1.0/24,192.168.10.16/32,2001:db8:1::/64', ) class Meta: From 53372a747109479f632fc916244d14fb75253f60 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 11 Jul 2022 21:51:39 -0400 Subject: [PATCH 156/245] #8157: General cleanup & fix tests --- netbox/ipam/filtersets.py | 25 ++-- netbox/ipam/forms/bulk_edit.py | 9 +- netbox/ipam/forms/bulk_import.py | 2 +- netbox/ipam/forms/filtersets.py | 38 ++++-- netbox/ipam/forms/models.py | 6 +- netbox/ipam/migrations/0059_l2vpn.py | 6 +- netbox/ipam/models/ip.py | 2 +- netbox/ipam/models/l2vpn.py | 11 +- netbox/ipam/tables/l2vpn.py | 11 +- netbox/ipam/tests/test_api.py | 2 - netbox/ipam/tests/test_filtersets.py | 126 ++++++++++++------ netbox/ipam/tests/test_views.py | 37 ++--- netbox/templates/ipam/l2vpn.html | 98 +++++++------- .../templates/ipam/l2vpntermination_edit.html | 4 +- 14 files changed, 213 insertions(+), 164 deletions(-) diff --git a/netbox/ipam/filtersets.py b/netbox/ipam/filtersets.py index f682009ee..edd1867ed 100644 --- a/netbox/ipam/filtersets.py +++ b/netbox/ipam/filtersets.py @@ -930,8 +930,11 @@ class ServiceFilterSet(NetBoxModelFilterSet): # L2VPN # - class L2VPNFilterSet(NetBoxModelFilterSet, TenancyFilterSet): + type = django_filters.MultipleChoiceFilter( + choices=L2VPNTypeChoices, + null_value=None + ) import_target_id = django_filters.ModelMultipleChoiceFilter( field_name='import_targets', queryset=RouteTarget.objects.all(), @@ -972,10 +975,10 @@ class L2VPNTerminationFilterSet(NetBoxModelFilterSet): label='L2VPN (ID)', ) l2vpn = django_filters.ModelMultipleChoiceFilter( - field_name='l2vpn__name', + field_name='l2vpn__slug', queryset=L2VPN.objects.all(), - to_field_name='name', - label='L2VPN (name)', + to_field_name='slug', + label='L2VPN (slug)', ) device = MultiValueCharFilter( method='filter_device', @@ -987,17 +990,16 @@ class L2VPNTerminationFilterSet(NetBoxModelFilterSet): field_name='pk', label='Device (ID)', ) - interface = django_filters.ModelMultipleChoiceFilter( - field_name='interface__name', - queryset=Interface.objects.all(), - to_field_name='name', - label='Interface (name)', - ) interface_id = django_filters.ModelMultipleChoiceFilter( field_name='interface', queryset=Interface.objects.all(), label='Interface (ID)', ) + vminterface_id = django_filters.ModelMultipleChoiceFilter( + field_name='vminterface', + queryset=VMInterface.objects.all(), + label='VM Interface (ID)', + ) vlan = django_filters.ModelMultipleChoiceFilter( field_name='vlan__name', queryset=VLAN.objects.all(), @@ -1013,10 +1015,11 @@ class L2VPNTerminationFilterSet(NetBoxModelFilterSet): queryset=VLAN.objects.all(), label='VLAN (ID)', ) + assigned_object_type = ContentTypeFilter() class Meta: model = L2VPNTermination - fields = ['id', ] + fields = ('id', 'assigned_object_type_id') def search(self, queryset, name, value): if not value.strip(): diff --git a/netbox/ipam/forms/bulk_edit.py b/netbox/ipam/forms/bulk_edit.py index 50fc51522..5f579b07f 100644 --- a/netbox/ipam/forms/bulk_edit.py +++ b/netbox/ipam/forms/bulk_edit.py @@ -8,7 +8,7 @@ from ipam.models import ASN from netbox.forms import NetBoxModelBulkEditForm from tenancy.models import Tenant from utilities.forms import ( - add_blank_choice, BulkEditNullBooleanSelect, DatePicker, DynamicModelChoiceField, NumericArrayField, StaticSelect, + add_blank_choice, BulkEditNullBooleanSelect, DynamicModelChoiceField, NumericArrayField, StaticSelect, DynamicModelMultipleChoiceField, ) @@ -445,6 +445,11 @@ class ServiceBulkEditForm(ServiceTemplateBulkEditForm): class L2VPNBulkEditForm(NetBoxModelBulkEditForm): + type = forms.ChoiceField( + choices=add_blank_choice(L2VPNTypeChoices), + required=False, + widget=StaticSelect() + ) tenant = DynamicModelChoiceField( queryset=Tenant.objects.all(), required=False @@ -456,7 +461,7 @@ class L2VPNBulkEditForm(NetBoxModelBulkEditForm): model = L2VPN fieldsets = ( - (None, ('tenant', 'description')), + (None, ('type', 'description', 'tenant')), ) nullable_fields = ('tenant', 'description',) diff --git a/netbox/ipam/forms/bulk_import.py b/netbox/ipam/forms/bulk_import.py index b8dd1c54c..880d2722f 100644 --- a/netbox/ipam/forms/bulk_import.py +++ b/netbox/ipam/forms/bulk_import.py @@ -438,7 +438,7 @@ class L2VPNCSVForm(NetBoxModelCSVForm): ) type = CSVChoiceField( choices=L2VPNTypeChoices, - help_text='IP protocol' + help_text='L2VPN type' ) class Meta: diff --git a/netbox/ipam/forms/filtersets.py b/netbox/ipam/forms/filtersets.py index 795cfe378..384a4da33 100644 --- a/netbox/ipam/forms/filtersets.py +++ b/netbox/ipam/forms/filtersets.py @@ -1,18 +1,19 @@ from django import forms +from django.contrib.contenttypes.models import ContentType +from django.db.models import Q from django.utils.translation import gettext as _ from dcim.models import Location, Rack, Region, Site, SiteGroup, Device -from virtualization.models import VirtualMachine from ipam.choices import * from ipam.constants import * from ipam.models import * -from ipam.models import ASN from netbox.forms import NetBoxModelFilterSetForm from tenancy.forms import TenancyFilterForm from utilities.forms import ( - add_blank_choice, DynamicModelChoiceField, DynamicModelMultipleChoiceField, MultipleChoiceField, StaticSelect, - TagFilterField, BOOLEAN_WITH_BLANK_CHOICES, + add_blank_choice, ContentTypeMultipleChoiceField, DynamicModelChoiceField, DynamicModelMultipleChoiceField, + MultipleChoiceField, StaticSelect, TagFilterField, BOOLEAN_WITH_BLANK_CHOICES, ) +from virtualization.models import VirtualMachine __all__ = ( 'AggregateFilterForm', @@ -482,7 +483,8 @@ class ServiceFilterForm(ServiceTemplateFilterForm): class L2VPNFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm): model = L2VPN fieldsets = ( - (None, ('type', )), + (None, ('q', 'tag')), + ('Attributes', ('type', 'import_target_id', 'export_target_id')), ('Tenant', ('tenant_group_id', 'tenant_id')), ) type = forms.ChoiceField( @@ -490,17 +492,31 @@ class L2VPNFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm): required=False, widget=StaticSelect() ) + import_target_id = DynamicModelMultipleChoiceField( + queryset=RouteTarget.objects.all(), + required=False, + label=_('Import targets') + ) + export_target_id = DynamicModelMultipleChoiceField( + queryset=RouteTarget.objects.all(), + required=False, + label=_('Export targets') + ) + tag = TagFilterField(model) class L2VPNTerminationFilterForm(NetBoxModelFilterSetForm): model = L2VPNTermination fieldsets = ( - (None, ('l2vpn', )), + (None, ('l2vpn_id', 'assigned_object_type_id')), ) - l2vpn = DynamicModelChoiceField( + l2vpn_id = DynamicModelChoiceField( queryset=L2VPN.objects.all(), - required=True, - query_params={}, - label='L2VPN', - fetch_trigger='open' + required=False, + label='L2VPN' + ) + assigned_object_type_id = ContentTypeMultipleChoiceField( + queryset=ContentType.objects.all(), + required=False, + label='Object type' ) diff --git a/netbox/ipam/forms/models.py b/netbox/ipam/forms/models.py index 3986eee32..415c952be 100644 --- a/netbox/ipam/forms/models.py +++ b/netbox/ipam/forms/models.py @@ -916,7 +916,8 @@ class L2VPNTerminationForm(NetBoxModelForm): required=False, query_params={ 'available_on_device': '$device' - } + }, + label='VLAN' ) interface = DynamicModelChoiceField( queryset=Interface.objects.all(), @@ -935,7 +936,8 @@ class L2VPNTerminationForm(NetBoxModelForm): required=False, query_params={ 'virtual_machine_id': '$virtual_machine' - } + }, + label='Interface' ) class Meta: diff --git a/netbox/ipam/migrations/0059_l2vpn.py b/netbox/ipam/migrations/0059_l2vpn.py index ef670ddea..7436989f7 100644 --- a/netbox/ipam/migrations/0059_l2vpn.py +++ b/netbox/ipam/migrations/0059_l2vpn.py @@ -27,7 +27,7 @@ class Migration(migrations.Migration): ('slug', models.SlugField()), ('type', models.CharField(max_length=50)), ('identifier', models.BigIntegerField(blank=True, null=True, unique=True)), - ('description', models.TextField(blank=True, null=True)), + ('description', models.CharField(blank=True, max_length=200)), ('export_targets', models.ManyToManyField(blank=True, related_name='exporting_l2vpns', to='ipam.routetarget')), ('import_targets', models.ManyToManyField(blank=True, related_name='importing_l2vpns', to='ipam.routetarget')), ('tags', taggit.managers.TaggableManager(through='extras.TaggedItem', to='extras.Tag')), @@ -35,7 +35,7 @@ class Migration(migrations.Migration): ], options={ 'verbose_name': 'L2VPN', - 'ordering': ('identifier', 'name'), + 'ordering': ('name', 'identifier'), }, ), migrations.CreateModel( @@ -51,7 +51,7 @@ class Migration(migrations.Migration): ('tags', taggit.managers.TaggableManager(through='extras.TaggedItem', to='extras.Tag')), ], options={ - 'verbose_name': 'L2VPN Termination', + 'verbose_name': 'L2VPN termination', 'ordering': ('l2vpn',), }, ), diff --git a/netbox/ipam/models/ip.py b/netbox/ipam/models/ip.py index 0bc0e2364..ee5de8cf4 100644 --- a/netbox/ipam/models/ip.py +++ b/netbox/ipam/models/ip.py @@ -931,7 +931,7 @@ class IPAddress(NetBoxModel): # Populate the address field with the next available IP (if any) if next_available_ip := self.get_next_available_ip(): - attrs['address'] = next_available_ip + attrs['address'] = f'{next_available_ip}/{self.address.prefixlen}' return attrs diff --git a/netbox/ipam/models/l2vpn.py b/netbox/ipam/models/l2vpn.py index dd8c51984..5d85fe915 100644 --- a/netbox/ipam/models/l2vpn.py +++ b/netbox/ipam/models/l2vpn.py @@ -31,7 +31,10 @@ class L2VPN(NetBoxModel): related_name='exporting_l2vpns', blank=True ) - description = models.TextField(null=True, blank=True) + description = models.CharField( + max_length=200, + blank=True + ) tenant = models.ForeignKey( to='tenancy.Tenant', on_delete=models.PROTECT, @@ -44,7 +47,7 @@ class L2VPN(NetBoxModel): ) class Meta: - ordering = ('identifier', 'name') + ordering = ('name', 'identifier') verbose_name = 'L2VPN' def __str__(self): @@ -76,7 +79,7 @@ class L2VPNTermination(NetBoxModel): class Meta: ordering = ('l2vpn',) - verbose_name = 'L2VPN Termination' + verbose_name = 'L2VPN termination' constraints = ( models.UniqueConstraint( fields=('assigned_object_type', 'assigned_object_id'), @@ -102,7 +105,7 @@ class L2VPNTermination(NetBoxModel): raise ValidationError(f'L2VPN Termination already assigned ({self.assigned_object})') # Only check if L2VPN is set and is of type P2P - if self.l2vpn and self.l2vpn.type in L2VPNTypeChoices.P2P: + if hasattr(self, 'l2vpn') and self.l2vpn.type in L2VPNTypeChoices.P2P: terminations_count = L2VPNTermination.objects.filter(l2vpn=self.l2vpn).exclude(pk=self.pk).count() if terminations_count >= 2: l2vpn_type = self.l2vpn.get_type_display() diff --git a/netbox/ipam/tables/l2vpn.py b/netbox/ipam/tables/l2vpn.py index a0e2f5d67..5be525343 100644 --- a/netbox/ipam/tables/l2vpn.py +++ b/netbox/ipam/tables/l2vpn.py @@ -1,8 +1,8 @@ import django_tables2 as tables -from ipam.models import * -from ipam.models.l2vpn import L2VPN, L2VPNTermination +from ipam.models import L2VPN, L2VPNTermination from netbox.tables import NetBoxTable, columns +from tenancy.tables import TenancyColumnsMixin __all__ = ( 'L2VPNTable', @@ -16,7 +16,7 @@ L2VPN_TARGETS = """ """ -class L2VPNTable(NetBoxTable): +class L2VPNTable(TenancyColumnsMixin, NetBoxTable): pk = columns.ToggleColumn() name = tables.Column( linkify=True @@ -32,7 +32,10 @@ class L2VPNTable(NetBoxTable): class Meta(NetBoxTable.Meta): model = L2VPN - fields = ('pk', 'name', 'slug', 'type', 'description', 'import_targets', 'export_targets', 'tenant', 'actions') + fields = ( + 'pk', 'name', 'slug', 'type', 'description', 'import_targets', 'export_targets', 'tenant', 'tenant_group', + 'actions', + ) default_columns = ('pk', 'name', 'type', 'description', 'actions') diff --git a/netbox/ipam/tests/test_api.py b/netbox/ipam/tests/test_api.py index a5ebef2c7..3fef04194 100644 --- a/netbox/ipam/tests/test_api.py +++ b/netbox/ipam/tests/test_api.py @@ -970,7 +970,6 @@ class L2VPNTerminationTest(APIViewTestCases.APIViewTestCase): VLAN(name='VLAN 6', vid=656), VLAN(name='VLAN 7', vid=657) ) - VLAN.objects.bulk_create(vlans) l2vpns = ( @@ -985,7 +984,6 @@ class L2VPNTerminationTest(APIViewTestCases.APIViewTestCase): L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[1]), L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vlans[2]) ) - L2VPNTermination.objects.bulk_create(l2vpnterminations) cls.create_data = [ diff --git a/netbox/ipam/tests/test_filtersets.py b/netbox/ipam/tests/test_filtersets.py index 2b5fb0759..9106a4965 100644 --- a/netbox/ipam/tests/test_filtersets.py +++ b/netbox/ipam/tests/test_filtersets.py @@ -1,6 +1,8 @@ +from django.contrib.contenttypes.models import ContentType from django.test import TestCase from netaddr import IPNetwork +from dcim.choices import InterfaceTypeChoices from dcim.models import Device, DeviceRole, DeviceType, Interface, Location, Manufacturer, Rack, Region, Site, SiteGroup from ipam.choices import * from ipam.filtersets import * @@ -1472,12 +1474,54 @@ class L2VPNTestCase(TestCase, ChangeLoggedFilterSetTests): @classmethod def setUpTestData(cls): + route_targets = ( + RouteTarget(name='1:1'), + RouteTarget(name='1:2'), + RouteTarget(name='1:3'), + RouteTarget(name='2:1'), + RouteTarget(name='2:2'), + RouteTarget(name='2:3'), + ) + RouteTarget.objects.bulk_create(route_targets) + l2vpns = ( - L2VPN(name='L2VPN 1', type='vxlan', identifier=650001), - L2VPN(name='L2VPN 2', type='vpws', identifier=650002), - L2VPN(name='L2VPN 3', type='vpls'), # No RD + L2VPN(name='L2VPN 1', type=L2VPNTypeChoices.TYPE_VXLAN, identifier=65001), + L2VPN(name='L2VPN 2', type=L2VPNTypeChoices.TYPE_VPWS, identifier=65002), + L2VPN(name='L2VPN 3', type=L2VPNTypeChoices.TYPE_VPLS), ) L2VPN.objects.bulk_create(l2vpns) + l2vpns[0].import_targets.add(route_targets[0]) + l2vpns[1].import_targets.add(route_targets[1]) + l2vpns[2].import_targets.add(route_targets[2]) + l2vpns[0].export_targets.add(route_targets[3]) + l2vpns[1].export_targets.add(route_targets[4]) + l2vpns[2].export_targets.add(route_targets[5]) + + def test_name(self): + params = {'name': ['L2VPN 1', 'L2VPN 2']} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + + def test_identifier(self): + params = {'identifier': ['65001', '65002']} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + + def test_type(self): + params = {'type': [L2VPNTypeChoices.TYPE_VXLAN, L2VPNTypeChoices.TYPE_VPWS]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + + def test_import_targets(self): + route_targets = RouteTarget.objects.filter(name__in=['1:1', '1:2']) + params = {'import_target_id': [route_targets[0].pk, route_targets[1].pk]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + params = {'import_target': [route_targets[0].name, route_targets[1].name]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + + def test_export_targets(self): + route_targets = RouteTarget.objects.filter(name__in=['2:1', '2:2']) + params = {'export_target_id': [route_targets[0].pk, route_targets[1].pk]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + params = {'export_target': [route_targets[0].name, route_targets[1].name]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) class L2VPNTerminationTestCase(TestCase, ChangeLoggedFilterSetTests): @@ -1486,44 +1530,33 @@ class L2VPNTerminationTestCase(TestCase, ChangeLoggedFilterSetTests): @classmethod def setUpTestData(cls): - - site = Site.objects.create(name='Site 1') - manufacturer = Manufacturer.objects.create(name='Manufacturer 1') - device_type = DeviceType.objects.create(model='Device Type 1', manufacturer=manufacturer) - device_role = DeviceRole.objects.create(name='Switch') - device = Device.objects.create( - name='Device 1', - site=site, - device_type=device_type, - device_role=device_role, - status='active' - ) - + device = create_test_device('Device 1') interfaces = ( - Interface(name='Interface 1', device=device, type='1000baset'), - Interface(name='Interface 2', device=device, type='1000baset'), - Interface(name='Interface 3', device=device, type='1000baset'), - Interface(name='Interface 4', device=device, type='1000baset'), - Interface(name='Interface 5', device=device, type='1000baset'), - Interface(name='Interface 6', device=device, type='1000baset') + Interface(name='Interface 1', device=device, type=InterfaceTypeChoices.TYPE_1GE_FIXED), + Interface(name='Interface 2', device=device, type=InterfaceTypeChoices.TYPE_1GE_FIXED), + Interface(name='Interface 3', device=device, type=InterfaceTypeChoices.TYPE_1GE_FIXED), ) - Interface.objects.bulk_create(interfaces) - vlans = ( - VLAN(name='VLAN 1', vid=651), - VLAN(name='VLAN 2', vid=652), - VLAN(name='VLAN 3', vid=653), - VLAN(name='VLAN 4', vid=654), - VLAN(name='VLAN 5', vid=655) + vm = create_test_virtualmachine('Virtual Machine 1') + vminterfaces = ( + VMInterface(name='Interface 1', virtual_machine=vm), + VMInterface(name='Interface 2', virtual_machine=vm), + VMInterface(name='Interface 3', virtual_machine=vm), ) + VMInterface.objects.bulk_create(vminterfaces) + vlans = ( + VLAN(name='VLAN 1', vid=101), + VLAN(name='VLAN 2', vid=102), + VLAN(name='VLAN 3', vid=103), + ) VLAN.objects.bulk_create(vlans) l2vpns = ( - L2VPN(name='L2VPN 1', type='vxlan', identifier=650001), - L2VPN(name='L2VPN 2', type='vpws', identifier=650002), - L2VPN(name='L2VPN 3', type='vpls'), # No RD, + L2VPN(name='L2VPN 1', slug='l2vpn-1', type='vxlan', identifier=65001), + L2VPN(name='L2VPN 2', slug='l2vpn-2', type='vpws', identifier=65002), + L2VPN(name='L2VPN 3', slug='l2vpn-3', type='vpls'), # No RD, ) L2VPN.objects.bulk_create(l2vpns) @@ -1534,27 +1567,34 @@ class L2VPNTerminationTestCase(TestCase, ChangeLoggedFilterSetTests): L2VPNTermination(l2vpn=l2vpns[0], assigned_object=interfaces[0]), L2VPNTermination(l2vpn=l2vpns[1], assigned_object=interfaces[1]), L2VPNTermination(l2vpn=l2vpns[2], assigned_object=interfaces[2]), + L2VPNTermination(l2vpn=l2vpns[0], assigned_object=vminterfaces[0]), + L2VPNTermination(l2vpn=l2vpns[1], assigned_object=vminterfaces[1]), + L2VPNTermination(l2vpn=l2vpns[2], assigned_object=vminterfaces[2]), ) - L2VPNTermination.objects.bulk_create(l2vpnterminations) - def test_l2vpns(self): + def test_l2vpn(self): l2vpns = L2VPN.objects.all()[:2] params = {'l2vpn_id': [l2vpns[0].pk, l2vpns[1].pk]} - self.assertEqual(self.filterset(params, self.queryset).qs.count(), 4) - params = {'l2vpn': ['L2VPN 1', 'L2VPN 2']} - self.assertEqual(self.filterset(params, self.queryset).qs.count(), 4) + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 6) + params = {'l2vpn': [l2vpns[0].slug, l2vpns[1].slug]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 6) - def test_interfaces(self): + def test_content_type(self): + params = {'assigned_object_type_id': ContentType.objects.get(model='vlan').pk} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 3) + + def test_interface(self): interfaces = Interface.objects.all()[:2] params = {'interface_id': [interfaces[0].pk, interfaces[1].pk]} - qs = self.filterset(params, self.queryset).qs - results = qs.all() - self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) - params = {'interface': ['Interface 1', 'Interface 2']} self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) - def test_vlans(self): + def test_vminterface(self): + vminterfaces = VMInterface.objects.all()[:2] + params = {'vminterface_id': [vminterfaces[0].pk, vminterfaces[1].pk]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + + def test_vlan(self): vlans = VLAN.objects.all()[:2] params = {'vlan_id': [vlans[0].pk, vlans[1].pk]} self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) diff --git a/netbox/ipam/tests/test_views.py b/netbox/ipam/tests/test_views.py index 890c0eae3..27520229a 100644 --- a/netbox/ipam/tests/test_views.py +++ b/netbox/ipam/tests/test_views.py @@ -1,18 +1,14 @@ import datetime -from django.contrib.contenttypes.models import ContentType from django.test import override_settings from django.urls import reverse from netaddr import IPNetwork from dcim.models import Device, DeviceRole, DeviceType, Manufacturer, Site, Interface -from extras.choices import ObjectChangeActionChoices -from extras.models import ObjectChange from ipam.choices import * from ipam.models import * from tenancy.models import Tenant -from users.models import ObjectPermission -from utilities.testing import ViewTestCases, create_tags, post_data +from utilities.testing import ViewTestCases, create_test_device, create_tags class ASNTestCase(ViewTestCases.PrimaryObjectViewTestCase): @@ -772,9 +768,9 @@ class L2VPNTestCase(ViewTestCases.PrimaryObjectViewTestCase): RouteTarget.objects.bulk_create(rts) l2vpns = ( - L2VPN(name='L2VPN 1', slug='l2vpn-1', type='vxlan', identifier='650001'), - L2VPN(name='L2VPN 2', slug='l2vpn-2', type='vxlan', identifier='650002'), - L2VPN(name='L2VPN 3', slug='l2vpn-3', type='vxlan', identifier='650003') + L2VPN(name='L2VPN 1', slug='l2vpn-1', type=L2VPNTypeChoices.TYPE_VXLAN, identifier='650001'), + L2VPN(name='L2VPN 2', slug='l2vpn-2', type=L2VPNTypeChoices.TYPE_VXLAN, identifier='650002'), + L2VPN(name='L2VPN 3', slug='l2vpn-3', type=L2VPNTypeChoices.TYPE_VXLAN, identifier='650003') ) L2VPN.objects.bulk_create(l2vpns) @@ -782,7 +778,7 @@ class L2VPNTestCase(ViewTestCases.PrimaryObjectViewTestCase): cls.form_data = { 'name': 'L2VPN 8', 'slug': 'l2vpn-8', - 'type': 'vxlan', + 'type': L2VPNTypeChoices.TYPE_VXLAN, 'identifier': 123, 'description': 'Description', 'import_targets': [rts[0].pk], @@ -805,21 +801,9 @@ class L2VPNTerminationTestCase( @classmethod def setUpTestData(cls): - site = Site.objects.create(name='Site 1') - manufacturer = Manufacturer.objects.create(name='Manufacturer 1') - device_type = DeviceType.objects.create(model='Device Type 1', manufacturer=manufacturer) - device_role = DeviceRole.objects.create(name='Switch') - device = Device.objects.create( - name='Device 1', - site=site, - device_type=device_type, - device_role=device_role, - status='active' - ) - + device = create_test_device('Device 1') interface = Interface.objects.create(name='Interface 1', device=device, type='1000baset') - l2vpn = L2VPN.objects.create(name='L2VPN 1', type='vxlan', identifier=650001) - l2vpn_vlans = L2VPN.objects.create(name='L2VPN 2', type='vxlan', identifier=650002) + l2vpn = L2VPN.objects.create(name='L2VPN 1', type=L2VPNTypeChoices.TYPE_VXLAN, identifier=650001) vlans = ( VLAN(name='Vlan 1', vid=1001), @@ -846,9 +830,9 @@ class L2VPNTerminationTestCase( cls.csv_data = ( "l2vpn,vlan", - "L2VPN 2,Vlan 4", - "L2VPN 2,Vlan 5", - "L2VPN 2,Vlan 6", + "L2VPN 1,Vlan 4", + "L2VPN 1,Vlan 5", + "L2VPN 1,Vlan 6", ) cls.bulk_edit_data = {} @@ -857,6 +841,7 @@ class L2VPNTerminationTestCase( # Custom assertions # + # TODO: Remove this def assertInstanceEqual(self, instance, data, exclude=None, api=False): """ Override parent diff --git a/netbox/templates/ipam/l2vpn.html b/netbox/templates/ipam/l2vpn.html index 130940b02..44a1da818 100644 --- a/netbox/templates/ipam/l2vpn.html +++ b/netbox/templates/ipam/l2vpn.html @@ -6,46 +6,40 @@ {% block content %}
    -
    -
    - L2VPN Attributes -
    -
    - Name - - - - - - - - - - - - - - - - - - - - - - -
    {{ object.name|placeholder }}
    Slug{{ object.slug|placeholder }}
    Identifier{{ object.identifier|placeholder }}
    Type{{ object.get_type_display }}
    Description{{ object.description|placeholder }}
    Tenant{{ object.tenant|placeholder }}
    -
    -
    - {% include 'inc/panels/contacts.html' %} - {% plugin_left_page object %} +
    +
    L2VPN Attributes
    +
    + + + + + + + + + + + + + + + + + + + + + +
    Name{{ object.name|placeholder }}
    Identifier{{ object.identifier|placeholder }}
    Type{{ object.get_type_display }}
    Description{{ object.description|placeholder }}
    Tenant{{ object.tenant|linkify|placeholder }}
    +
    +
    + {% include 'inc/panels/tags.html' with tags=object.tags.all url='ipam:l2vpn_list' %} + {% plugin_left_page object %}
    - {% include 'inc/panels/tags.html' with tags=object.tags.all url='circuits:circuit_list' %} - {% include 'inc/panels/custom_fields.html' %} - {% plugin_right_page object %} + {% include 'inc/panels/contacts.html' %} + {% include 'inc/panels/custom_fields.html' %} + {% plugin_right_page object %}
    @@ -58,24 +52,24 @@
    -
    -
    Terminations
    -
    - {% render_table terminations_table 'inc/table.html' %} -
    - {% if perms.ipam.add_l2vpntermination %} -
    - - Add a Termination - -
    - {% endif %} +
    +
    Terminations
    +
    + {% render_table terminations_table 'inc/table.html' %} +
    + {% if perms.ipam.add_l2vpntermination %} +
    + + Add a Termination +
    + {% endif %}
    +
    -
    - {% plugin_full_width_page object %} +
    + {% plugin_full_width_page object %}
    {% endblock %} diff --git a/netbox/templates/ipam/l2vpntermination_edit.html b/netbox/templates/ipam/l2vpntermination_edit.html index 4ba079eb5..7b4a9f50a 100644 --- a/netbox/templates/ipam/l2vpntermination_edit.html +++ b/netbox/templates/ipam/l2vpntermination_edit.html @@ -18,12 +18,12 @@ From 43b27cc052ee1fb569af3d8f62fffea3a365f3aa Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 12 Jul 2022 12:30:07 -0400 Subject: [PATCH 157/245] Misc cleanup --- docs/models/dcim/interface.md | 3 +++ docs/models/ipam/l2vpn.md | 4 ++-- docs/models/ipam/l2vpntermination.md | 8 ++++---- netbox/circuits/filtersets.py | 2 +- netbox/dcim/choices.py | 4 ++-- netbox/dcim/forms/bulk_edit.py | 6 ++++-- netbox/dcim/models/device_components.py | 4 ++++ netbox/dcim/models/devices.py | 13 ++++++++++++- netbox/dcim/svg/racks.py | 3 ++- netbox/dcim/tables/sites.py | 1 + netbox/templates/dcim/frontport.html | 6 +++++- netbox/templates/dcim/rearport.html | 6 +++++- .../virtualization/virtualmachine/base.html | 8 +++++++- netbox/virtualization/forms/models.py | 9 ++++++--- 14 files changed, 58 insertions(+), 19 deletions(-) diff --git a/docs/models/dcim/interface.md b/docs/models/dcim/interface.md index e3237c2ee..87a1411b9 100644 --- a/docs/models/dcim/interface.md +++ b/docs/models/dcim/interface.md @@ -13,6 +13,9 @@ Physical interfaces may be arranged into a link aggregation group (LAG) and asso ### Power over Ethernet (PoE) +!!! note + This feature was added in NetBox v3.3. + Physical interfaces can be assigned a PoE mode to indicate PoE capability: power supplying equipment (PSE) or powered device (PD). Additionally, a PoE mode may be specified. This can be one of the listed IEEE 802.3 standards, or a passive setting (24 or 48 volts across two or four pairs). ### Wireless Interfaces diff --git a/docs/models/ipam/l2vpn.md b/docs/models/ipam/l2vpn.md index 9f9b4703c..214b8aab0 100644 --- a/docs/models/ipam/l2vpn.md +++ b/docs/models/ipam/l2vpn.md @@ -17,5 +17,5 @@ Each L2VPN instance must have one of the following type associated with it: * MPLS-EVPN * PBB-EVPN -!!!note - Choosing VPWS, EPL, EP-LAN, EP-TREE will result in only being able to add 2 terminations to a given L2VPN. +!!! note + Choosing VPWS, EPL, EP-LAN, EP-TREE will result in only being able to add two terminations to a given L2VPN. diff --git a/docs/models/ipam/l2vpntermination.md b/docs/models/ipam/l2vpntermination.md index cc1843639..e7c6a6810 100644 --- a/docs/models/ipam/l2vpntermination.md +++ b/docs/models/ipam/l2vpntermination.md @@ -1,15 +1,15 @@ # L2VPN Termination -A L2VPN Termination is the termination point of a L2VPN. Certain types of L2VPN's may only have 2 termination points (point-to-point) while others may have many terminations (multipoint). +A L2VPN Termination is the termination point of a L2VPN. Certain types of L2VPNs may only have 2 termination points (point-to-point) while others may have many terminations (multipoint). Each termination consists of a L2VPN it is a member of as well as the connected endpoint which can be an interface or a VLAN. -The following types of L2VPN's are considered point-to-point: +The following types of L2VPNs are considered point-to-point: * VPWS * EPL * EP-LAN * EP-TREE -!!!note - Choosing any of the above types of L2VPN's will result in only being able to add 2 terminations to a given L2VPN. +!!! note + Choosing any of the above types will result in only being able to add 2 terminations to a given L2VPN. diff --git a/netbox/circuits/filtersets.py b/netbox/circuits/filtersets.py index 8005c0afe..cee38fb18 100644 --- a/netbox/circuits/filtersets.py +++ b/netbox/circuits/filtersets.py @@ -4,7 +4,7 @@ from django.db.models import Q from dcim.filtersets import CabledObjectFilterSet from dcim.models import Region, Site, SiteGroup from ipam.models import ASN -from netbox.filtersets import ChangeLoggedModelFilterSet, NetBoxModelFilterSet, OrganizationalModelFilterSet +from netbox.filtersets import NetBoxModelFilterSet, OrganizationalModelFilterSet from tenancy.filtersets import ContactModelFilterSet, TenancyFilterSet from utilities.filters import TreeNodeMultipleChoiceFilter from .choices import * diff --git a/netbox/dcim/choices.py b/netbox/dcim/choices.py index 1a66312da..1fe21ed4b 100644 --- a/netbox/dcim/choices.py +++ b/netbox/dcim/choices.py @@ -1031,8 +1031,8 @@ class InterfacePoEModeChoices(ChoiceSet): MODE_PSE = 'pse' CHOICES = ( - (MODE_PD, 'Powered device (PD)'), - (MODE_PSE, 'Power sourcing equipment (PSE)'), + (MODE_PD, 'PD'), + (MODE_PSE, 'PSE'), ) diff --git a/netbox/dcim/forms/bulk_edit.py b/netbox/dcim/forms/bulk_edit.py index b4ab226ae..6d51302d3 100644 --- a/netbox/dcim/forms/bulk_edit.py +++ b/netbox/dcim/forms/bulk_edit.py @@ -1073,13 +1073,15 @@ class InterfaceBulkEditForm( choices=add_blank_choice(InterfacePoEModeChoices), required=False, initial='', - widget=StaticSelect() + widget=StaticSelect(), + label='PoE mode' ) poe_type = forms.ChoiceField( choices=add_blank_choice(InterfacePoETypeChoices), required=False, initial='', - widget=StaticSelect() + widget=StaticSelect(), + label='PoE type' ) mark_connected = forms.NullBooleanField( required=False, diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 9645efdbf..8f62b0626 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -227,6 +227,10 @@ class PathEndpoint(models.Model): # Return the path as a list of three-tuples (A termination(s), cable(s), B termination(s)) return list(zip(*[iter(path)] * 3)) + @property + def path(self): + return self._path + @cached_property def connected_endpoints(self): """ diff --git a/netbox/dcim/models/devices.py b/netbox/dcim/models/devices.py index 43b84974b..6075cb5a0 100644 --- a/netbox/dcim/models/devices.py +++ b/netbox/dcim/models/devices.py @@ -1,3 +1,4 @@ +import decimal from collections import OrderedDict import yaml @@ -279,6 +280,12 @@ class DeviceType(NetBoxModel): def clean(self): super().clean() + # U height must be divisible by 0.5 + if self.u_height % decimal.Decimal(0.5): + raise ValidationError({ + 'u_height': "U height must be in increments of 0.5 rack units." + }) + # If editing an existing DeviceType to have a larger u_height, first validate that *all* instances of it have # room to expand within their racks. This validation will impose a very high performance penalty when there are # many instances to check, but increasing the u_height of a DeviceType should be a very rare occurrence. @@ -811,7 +818,11 @@ class Device(NetBoxModel, ConfigContextModel): 'position': "Cannot select a rack position without assigning a rack.", }) - # Validate position/face combination + # Validate rack position and face + if self.position and self.position % decimal.Decimal(0.5): + raise ValidationError({ + 'position': "Position must be in increments of 0.5 rack units." + }) if self.position and not self.face: raise ValidationError({ 'face': "Must specify rack face when defining rack position.", diff --git a/netbox/dcim/svg/racks.py b/netbox/dcim/svg/racks.py index 920bd662f..f228c416b 100644 --- a/netbox/dcim/svg/racks.py +++ b/netbox/dcim/svg/racks.py @@ -260,13 +260,14 @@ class RackElevationSVG: ) for ru in range(0, self.rack.u_height): + unit = ru + 1 if self.rack.desc_units else self.rack.u_height - ru y_offset = RACK_ELEVATION_BORDER_WIDTH + ru * self.unit_height text_coords = ( x_offset + self.unit_width / 2, y_offset + self.unit_height / 2 ) - link = Hyperlink(href=url_string.format(ru), target='_blank') + link = Hyperlink(href=url_string.format(unit), target='_blank') link.add(Rect((x_offset, y_offset), (self.unit_width, self.unit_height), class_='slot')) link.add(Text('add device', insert=text_coords, class_='add-device')) diff --git a/netbox/dcim/tables/sites.py b/netbox/dcim/tables/sites.py index e452badea..5dc2aa611 100644 --- a/netbox/dcim/tables/sites.py +++ b/netbox/dcim/tables/sites.py @@ -125,6 +125,7 @@ class LocationTable(TenancyColumnsMixin, NetBoxTable): site = tables.Column( linkify=True ) + status = columns.ChoiceFieldColumn() rack_count = columns.LinkedCountColumn( viewname='dcim:rack_list', url_params={'location_id': 'pk'}, diff --git a/netbox/templates/dcim/frontport.html b/netbox/templates/dcim/frontport.html index 4cea7989b..e5f1df5ae 100644 --- a/netbox/templates/dcim/frontport.html +++ b/netbox/templates/dcim/frontport.html @@ -41,7 +41,11 @@ Color -   + {% if object.color %} +   + {% else %} + {{ ''|placeholder }} + {% endif %} diff --git a/netbox/templates/dcim/rearport.html b/netbox/templates/dcim/rearport.html index 3caae49c3..ae7b55316 100644 --- a/netbox/templates/dcim/rearport.html +++ b/netbox/templates/dcim/rearport.html @@ -41,7 +41,11 @@ Color -   + {% if object.color %} +   + {% else %} + {{ ''|placeholder }} + {% endif %} diff --git a/netbox/templates/virtualization/virtualmachine/base.html b/netbox/templates/virtualization/virtualmachine/base.html index 0c2f43de8..946467e31 100644 --- a/netbox/templates/virtualization/virtualmachine/base.html +++ b/netbox/templates/virtualization/virtualmachine/base.html @@ -5,7 +5,13 @@ {% block breadcrumbs %} {{ block.super }} -
  • {{ object.cluster }}
    • +
  • + {% if object.cluster %} + {{ object.cluster }} + {% else %} + {{ object.site }} + {% endif %} +
    • {% endblock %} {% block extra_controls %} diff --git a/netbox/virtualization/forms/models.py b/netbox/virtualization/forms/models.py index 018b50c99..a60d15281 100644 --- a/netbox/virtualization/forms/models.py +++ b/netbox/virtualization/forms/models.py @@ -166,7 +166,8 @@ class ClusterRemoveDevicesForm(ConfirmationForm): class VirtualMachineForm(TenancyForm, NetBoxModelForm): site = DynamicModelChoiceField( - queryset=Site.objects.all() + queryset=Site.objects.all(), + required=False ) cluster_group = DynamicModelChoiceField( queryset=ClusterGroup.objects.all(), @@ -178,6 +179,7 @@ class VirtualMachineForm(TenancyForm, NetBoxModelForm): ) cluster = DynamicModelChoiceField( queryset=Cluster.objects.all(), + required=False, query_params={ 'site_id': '$site', 'group_id': '$cluster_group', @@ -188,7 +190,8 @@ class VirtualMachineForm(TenancyForm, NetBoxModelForm): required=False, query_params={ 'cluster_id': '$cluster' - } + }, + help_text="Optionally pin this VM to a specific host device within the cluster" ) role = DynamicModelChoiceField( queryset=DeviceRole.objects.all(), @@ -208,7 +211,7 @@ class VirtualMachineForm(TenancyForm, NetBoxModelForm): fieldsets = ( ('Virtual Machine', ('name', 'role', 'status', 'tags')), - ('Cluster', ('site', 'cluster_group', 'cluster', 'device')), + ('Site/Cluster', ('site', 'cluster_group', 'cluster', 'device')), ('Tenancy', ('tenant_group', 'tenant')), ('Management', ('platform', 'primary_ip4', 'primary_ip6')), ('Resources', ('vcpus', 'memory', 'disk')), From 43a4a9c86d69d273e8564fca6b72d2b93b27f26c Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 12 Jul 2022 16:29:43 -0400 Subject: [PATCH 158/245] Complete release notes --- docs/release-notes/version-3.3.md | 46 +++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index ac499f806..3d514ea69 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -31,17 +31,52 @@ ### New Features -#### Half-Height Rack Units ([#51](https://github.com/netbox-community/netbox/issues/51)) +#### Multi-object Cable Terminations ([#9102](https://github.com/netbox-community/netbox/issues/9102)) -#### PoE Interface Attributes ([#1099](https://github.com/netbox-community/netbox/issues/1099)) +When creating a cable in NetBox, each end can now be attached to multiple objects. This allows accurate modeling of duplex fiber connections to individual termination ports and breakout cables, as examples. (Note that all terminations attached to one end of a cable must be the same object type, but do not need to connect to the same parent object.) Additionally, cable terminations can now be modified without needing to delete and recreate the cable. #### L2VPN Modeling ([#8157](https://github.com/netbox-community/netbox/issues/8157)) +NetBox can now model a variety of L2 VPN technologies, including VXLAN, VPLS, and others. Each L2VPN can be terminated to multiple device or virtual machine interfaces and/or VLANs to track connectivity across an overlay. Similarly to VRFs, each L2VPN can also have import and export route targets associated with it. + +#### PoE Interface Attributes ([#1099](https://github.com/netbox-community/netbox/issues/1099)) + +Two new fields have been added to the device interface model to track power over Ethernet (PoE) capabilities: + +* **PoE mode**: Power supplying equipment (PSE) or powered device (PD) +* **PoE type**: Applicable IEEE standard or other power type + +#### Half-Height Rack Units ([#51](https://github.com/netbox-community/netbox/issues/51)) + +Device type height can now be specified in 0.5U increments, allowing for the creation of half-height devices. Additionally, a device can be installed at the half-unit mark within a rack (e.g. U2.5). For example, two half-height devices positioned in sequence will consume a single rack unit; two consecutive 1.5U devices will consume 3U of space. + #### Restrict API Tokens by Client IP ([#8233](https://github.com/netbox-community/netbox/issues/8233)) +API tokens can now be restricted to use by certain client IP addresses or networks. For example, an API token with its `allowed_ips` list set to `[192.0.2.0/24]` will only permit authentication from API clients within that network; requests from other sources will fail authentication. This can be very useful for restricting the use of a token to specific clients. + #### Reference User in Permission Constraints ([#9074](https://github.com/netbox-community/netbox/issues/9074)) -#### Multi-object Cable Terminations ([#9102](https://github.com/netbox-community/netbox/issues/9102)) +NetBox's permission constraints have been expanded to support referencing the current user associated with a request using the special `$user` token. As an example, this enables an administrator to efficiently grant each user to edit his or her own journal entries, but not those created by other users. + +```json +{ + "created_by": "$user" +} +``` + +#### Custom Field Grouping ([#8495](https://github.com/netbox-community/netbox/issues/8495)) + +A `group_name` field has been added to the custom field model to enable organizing related custom fields by group. Similarly to custom links, custom links which have been assigned to a common group will be rendered within that group when viewing an object in the UI. (Custom field grouping has no effect on API operation.) + +#### Toggle Custom Field Visibility ([#9166](https://github.com/netbox-community/netbox/issues/9166)) + +The behavior of each custom field within the NetBox UI can now be controlled individually by toggling its UI visibility. Three settings are available: + +* **Read/write**: The custom field is included when viewing and editing objects (default). +* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. + +Custom field UI visibility has no impact on API operation. ### Enhancements @@ -54,11 +89,9 @@ * [#8171](https://github.com/netbox-community/netbox/issues/8171) - Populate next available address when cloning an IP * [#8222](https://github.com/netbox-community/netbox/issues/8222) - Enable the assignment of a VM to a specific host device within a cluster * [#8471](https://github.com/netbox-community/netbox/issues/8471) - Add `status` field to Cluster -* [#8495](https://github.com/netbox-community/netbox/issues/8495) - Enable custom field grouping * [#8511](https://github.com/netbox-community/netbox/issues/8511) - Enable custom fields and tags for circuit terminations * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results * [#9070](https://github.com/netbox-community/netbox/issues/9070) - Hide navigation menu items based on user permissions -* [#9166](https://github.com/netbox-community/netbox/issues/9166) - Add UI visibility toggle for custom fields * [#9177](https://github.com/netbox-community/netbox/issues/9177) - Add tenant assignment for wireless LANs & links * [#9536](https://github.com/netbox-community/netbox/issues/9536) - Track API token usage times * [#9582](https://github.com/netbox-community/netbox/issues/9582) - Enable assigning config contexts based on device location @@ -78,6 +111,7 @@ ### REST API Changes +* List results can now be ordered by field, by appending `?ordering={fieldname}` to the query. Multiple fields can be specified by separating the field names with a comma, e.g. `?ordering=site,name`. To invert the ordering, prepend a hyphen to the field name, e.g. `?ordering=-name`. * Added the following endpoints: * `/api/dcim/cable-terminations/` * `/api/ipam/l2vpns/` @@ -173,7 +207,7 @@ * virtualization.VirtualMachine * The `site` field is now directly writable (rather than being inferred from the assigned cluster) * The `cluster` field is now optional. A virtual machine must have a site and/or cluster assigned. - * Added the `device` field + * Added the optional `device` field * Added the `l2vpn_termination` read-only field wireless.WirelessLAN * Added `tenant` field From fb2bfe23375c5ffa718424ae8ae0c751eabafae0 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 13 Jul 2022 15:12:53 -0400 Subject: [PATCH 159/245] Introduce GenericObjectSerializer --- netbox/netbox/api/serializers/__init__.py | 1 + netbox/netbox/api/serializers/generic.py | 31 +++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 netbox/netbox/api/serializers/generic.py diff --git a/netbox/netbox/api/serializers/__init__.py b/netbox/netbox/api/serializers/__init__.py index adc556549..0ec3ab5f3 100644 --- a/netbox/netbox/api/serializers/__init__.py +++ b/netbox/netbox/api/serializers/__init__.py @@ -2,6 +2,7 @@ from rest_framework import serializers from .base import * from .features import * +from .generic import * from .nested import * diff --git a/netbox/netbox/api/serializers/generic.py b/netbox/netbox/api/serializers/generic.py new file mode 100644 index 000000000..81ec338ff --- /dev/null +++ b/netbox/netbox/api/serializers/generic.py @@ -0,0 +1,31 @@ +from django.contrib.contenttypes.models import ContentType +from rest_framework import serializers + +from netbox.api import ContentTypeField +from utilities.utils import content_type_identifier + +__all__ = ( + 'GenericObjectSerializer', +) + + +class GenericObjectSerializer(serializers.Serializer): + """ + Minimal representation of some generic object identified by ContentType and PK. + """ + object_type = ContentTypeField( + queryset=ContentType.objects.all() + ) + object_id = serializers.IntegerField() + + def to_internal_value(self, data): + data = super().to_internal_value(data) + model = data['object_type'].model_class() + return model.objects.get(pk=data['object_id']) + + def to_representation(self, instance): + ct = ContentType.objects.get_for_model(instance) + return { + 'object_type': content_type_identifier(ct), + 'object_id': instance.pk, + } From 0b86326435fe6ea07ef376a81ff6fb592906fafc Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 13 Jul 2022 15:35:37 -0400 Subject: [PATCH 160/245] #9102: Enable creating terminations in conjunction with cables via REST API --- docs/release-notes/version-3.3.md | 6 +- netbox/dcim/api/serializers.py | 50 ++------------- netbox/dcim/forms/bulk_import.py | 2 +- netbox/dcim/forms/connections.py | 4 +- netbox/dcim/models/cables.py | 103 +++++++++++++++++------------- netbox/dcim/signals.py | 2 +- netbox/dcim/tests/test_api.py | 48 ++++++++++---- netbox/dcim/tests/test_views.py | 16 ++++- netbox/templates/dcim/cable.html | 4 +- 9 files changed, 123 insertions(+), 112 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 3d514ea69..7a093a35b 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -6,12 +6,12 @@ * Device position and rack unit values are now reported as decimals (e.g. `1.0` or `1.5`) to support modeling half-height rack units. * The `nat_outside` relation on the IP address model now returns a list of zero or more related IP addresses, rather than a single instance (or None). -* Several fields on the cable API serializers have been altered to support multiple-object cable terminations: +* Several fields on the cable API serializers have been altered or removed to support multiple-object cable terminations: | Old Name | Old Type | New Name | New Type | |----------------------|----------|-----------------------|----------| -| `termination_a_type` | string | `a_terminations_type` | string | -| `termination_b_type` | string | `b_terminations_type` | string | +| `termination_a_type` | string | _Removed_ | - | +| `termination_b_type` | string | _Removed_ | - | | `termination_a_id` | integer | _Removed_ | - | | `termination_b_id` | integer | _Removed_ | - | | `termination_a` | object | `a_terminations` | list | diff --git a/netbox/dcim/api/serializers.py b/netbox/dcim/api/serializers.py index 08edd2820..66d28c3fb 100644 --- a/netbox/dcim/api/serializers.py +++ b/netbox/dcim/api/serializers.py @@ -15,7 +15,8 @@ from ipam.api.nested_serializers import ( from ipam.models import ASN, VLAN from netbox.api import ChoiceField, ContentTypeField, SerializedPKRelatedField from netbox.api.serializers import ( - NestedGroupModelSerializer, NetBoxModelSerializer, ValidatedModelSerializer, WritableNestedSerializer, + GenericObjectSerializer, NestedGroupModelSerializer, NetBoxModelSerializer, ValidatedModelSerializer, + WritableNestedSerializer, ) from netbox.config import ConfigItem from tenancy.api.nested_serializers import NestedTenantSerializer @@ -994,10 +995,8 @@ class InventoryItemRoleSerializer(NetBoxModelSerializer): class CableSerializer(NetBoxModelSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:cable-detail') - a_terminations_type = serializers.SerializerMethodField(read_only=True) - b_terminations_type = serializers.SerializerMethodField(read_only=True) - a_terminations = serializers.SerializerMethodField(read_only=True) - b_terminations = serializers.SerializerMethodField(read_only=True) + a_terminations = GenericObjectSerializer(many=True, required=False) + b_terminations = GenericObjectSerializer(many=True, required=False) status = ChoiceField(choices=LinkStatusChoices, required=False) tenant = NestedTenantSerializer(required=False, allow_null=True) length_unit = ChoiceField(choices=CableLengthUnitChoices, allow_blank=True, required=False) @@ -1005,47 +1004,10 @@ class CableSerializer(NetBoxModelSerializer): class Meta: model = Cable fields = [ - 'id', 'url', 'display', 'type', 'a_terminations_type', 'a_terminations', 'b_terminations_type', - 'b_terminations', 'status', 'tenant', 'label', 'color', 'length', 'length_unit', 'tags', 'custom_fields', - 'created', 'last_updated', + 'id', 'url', 'display', 'type', 'a_terminations', 'b_terminations', 'status', 'tenant', 'label', 'color', + 'length', 'length_unit', 'tags', 'custom_fields', 'created', 'last_updated', ] - def _get_terminations_type(self, obj, side): - assert side in CableEndChoices.values() - terms = getattr(obj, f'get_{side.lower()}_terminations')() - if terms: - ct = ContentType.objects.get_for_model(terms[0]) - return f"{ct.app_label}.{ct.model}" - - def _get_terminations(self, obj, side): - assert side in CableEndChoices.values() - terms = getattr(obj, f'get_{side.lower()}_terminations')() - if not terms: - return [] - - termination_type = ContentType.objects.get_for_model(terms[0]) - serializer = get_serializer_for_model(termination_type.model_class(), prefix='Nested') - context = {'request': self.context['request']} - data = serializer(terms, context=context, many=True).data - - return data - - @swagger_serializer_method(serializer_or_field=serializers.CharField) - def get_a_terminations_type(self, obj): - return self._get_terminations_type(obj, CableEndChoices.SIDE_A) - - @swagger_serializer_method(serializer_or_field=serializers.CharField) - def get_b_terminations_type(self, obj): - return self._get_terminations_type(obj, CableEndChoices.SIDE_B) - - @swagger_serializer_method(serializer_or_field=serializers.DictField) - def get_a_terminations(self, obj): - return self._get_terminations(obj, CableEndChoices.SIDE_A) - - @swagger_serializer_method(serializer_or_field=serializers.DictField) - def get_b_terminations(self, obj): - return self._get_terminations(obj, CableEndChoices.SIDE_B) - class TracedCableSerializer(serializers.ModelSerializer): """ diff --git a/netbox/dcim/forms/bulk_import.py b/netbox/dcim/forms/bulk_import.py index d6ec0f6f4..f0fd9bf86 100644 --- a/netbox/dcim/forms/bulk_import.py +++ b/netbox/dcim/forms/bulk_import.py @@ -955,7 +955,7 @@ class CableCSVForm(NetBoxModelCSVForm): except ObjectDoesNotExist: raise forms.ValidationError(f"{side.upper()} side termination not found: {device} {name}") - setattr(self.instance, f'termination_{side}', termination_object) + setattr(self.instance, f'{side}_terminations', [termination_object]) return termination_object def clean_side_a_name(self): diff --git a/netbox/dcim/forms/connections.py b/netbox/dcim/forms/connections.py index f7bfa6431..1b393ec6e 100644 --- a/netbox/dcim/forms/connections.py +++ b/netbox/dcim/forms/connections.py @@ -157,8 +157,8 @@ def get_cable_form(a_type, b_type): if self.instance and self.instance.pk: # Initialize A/B terminations when modifying an existing Cable instance - self.initial['a_terminations'] = self.instance.get_a_terminations() - self.initial['b_terminations'] = self.instance.get_b_terminations() + self.initial['a_terminations'] = self.instance.a_terminations + self.initial['b_terminations'] = self.instance.b_terminations def save(self, *args, **kwargs): diff --git a/netbox/dcim/models/cables.py b/netbox/dcim/models/cables.py index 551521c26..b35864aa0 100644 --- a/netbox/dcim/models/cables.py +++ b/netbox/dcim/models/cables.py @@ -93,11 +93,12 @@ class Cable(NetBoxModel): # Cache the original status so we can check later if it's been changed self._orig_status = self.status - # Assign any *new* CableTerminations for the instance. These will replace any existing - # terminations on save(). - if a_terminations is not None: + self._terminations_modified = False + + # Assign or retrieve A/B terminations + if a_terminations: self.a_terminations = a_terminations - if b_terminations is not None: + if b_terminations: self.b_terminations = b_terminations def __str__(self): @@ -107,6 +108,34 @@ class Cable(NetBoxModel): def get_absolute_url(self): return reverse('dcim:cable', args=[self.pk]) + @property + def a_terminations(self): + if hasattr(self, '_a_terminations'): + return self._a_terminations + # Query self.terminations.all() to leverage cached results + return [ + ct.termination for ct in self.terminations.all() if ct.cable_end == CableEndChoices.SIDE_A + ] + + @a_terminations.setter + def a_terminations(self, value): + self._terminations_modified = True + self._a_terminations = value + + @property + def b_terminations(self): + if hasattr(self, '_b_terminations'): + return self._b_terminations + # Query self.terminations.all() to leverage cached results + return [ + ct.termination for ct in self.terminations.all() if ct.cable_end == CableEndChoices.SIDE_B + ] + + @b_terminations.setter + def b_terminations(self, value): + self._terminations_modified = True + self._b_terminations = value + def clean(self): super().clean() @@ -116,30 +145,28 @@ class Cable(NetBoxModel): elif self.length is None: self.length_unit = '' - a_terminations = [ - CableTermination(cable=self, cable_end='A', termination=t) - for t in getattr(self, 'a_terminations', []) - ] - b_terminations = [ - CableTermination(cable=self, cable_end='B', termination=t) - for t in getattr(self, 'b_terminations', []) - ] + if self.pk is None and (not self.a_terminations or not self.b_terminations): + raise ValidationError("Must define A and B terminations when creating a new cable.") - # Check that all termination objects for either end are of the same type - for terms in (a_terminations, b_terminations): - if len(terms) > 1 and not all(t.termination_type == terms[0].termination_type for t in terms[1:]): - raise ValidationError("Cannot connect different termination types to same end of cable.") + if self._terminations_modified: - # Check that termination types are compatible - if a_terminations and b_terminations: - a_type = a_terminations[0].termination_type.model - b_type = b_terminations[0].termination_type.model - if b_type not in COMPATIBLE_TERMINATION_TYPES.get(a_type): - raise ValidationError(f"Incompatible termination types: {a_type} and {b_type}") + # Check that all termination objects for either end are of the same type + for terms in (self.a_terminations, self.b_terminations): + if len(terms) > 1 and not all(isinstance(t, type(terms[0])) for t in terms[1:]): + raise ValidationError("Cannot connect different termination types to same end of cable.") - # Run clean() on any new CableTerminations - for cabletermination in [*a_terminations, *b_terminations]: - cabletermination.clean() + # Check that termination types are compatible + if self.a_terminations and self.b_terminations: + a_type = self.a_terminations[0]._meta.model_name + b_type = self.b_terminations[0]._meta.model_name + if b_type not in COMPATIBLE_TERMINATION_TYPES.get(a_type): + raise ValidationError(f"Incompatible termination types: {a_type} and {b_type}") + + # Run clean() on any new CableTerminations + for termination in self.a_terminations: + CableTermination(cable=self, cable_end='A', termination=termination).clean() + for termination in self.b_terminations: + CableTermination(cable=self, cable_end='B', termination=termination).clean() def save(self, *args, **kwargs): _created = self.pk is None @@ -160,23 +187,21 @@ class Cable(NetBoxModel): b_terminations = {ct.termination: ct for ct in self.terminations.filter(cable_end='B')} # Delete stale CableTerminations - if hasattr(self, 'a_terminations'): + if self._terminations_modified: for termination, ct in a_terminations.items(): - if termination not in self.a_terminations: + if termination.pk and termination not in self.a_terminations: ct.delete() - if hasattr(self, 'b_terminations'): for termination, ct in b_terminations.items(): - if termination not in self.b_terminations: + if termination.pk and termination not in self.b_terminations: ct.delete() # Save new CableTerminations (if any) - if hasattr(self, 'a_terminations'): + if self._terminations_modified: for termination in self.a_terminations: - if termination not in a_terminations: + if not termination.pk or termination not in a_terminations: CableTermination(cable=self, cable_end='A', termination=termination).save() - if hasattr(self, 'b_terminations'): for termination in self.b_terminations: - if termination not in b_terminations: + if not termination.pk or termination not in b_terminations: CableTermination(cable=self, cable_end='B', termination=termination).save() trace_paths.send(Cable, instance=self, created=_created) @@ -184,18 +209,6 @@ class Cable(NetBoxModel): def get_status_color(self): return LinkStatusChoices.colors.get(self.status) - def get_a_terminations(self): - # Query self.terminations.all() to leverage cached results - return [ - ct.termination for ct in self.terminations.all() if ct.cable_end == CableEndChoices.SIDE_A - ] - - def get_b_terminations(self): - # Query self.terminations.all() to leverage cached results - return [ - ct.termination for ct in self.terminations.all() if ct.cable_end == CableEndChoices.SIDE_B - ] - class CableTermination(models.Model): """ diff --git a/netbox/dcim/signals.py b/netbox/dcim/signals.py index 7cfdc823d..2293f8840 100644 --- a/netbox/dcim/signals.py +++ b/netbox/dcim/signals.py @@ -79,7 +79,7 @@ def update_connected_endpoints(instance, created, raw=False, **kwargs): return # Update cable paths if new terminations have been set - if hasattr(instance, 'a_terminations') or hasattr(instance, 'b_terminations'): + if instance._terminations_modified: a_terminations = [] b_terminations = [] for t in instance.terminations.all(): diff --git a/netbox/dcim/tests/test_api.py b/netbox/dcim/tests/test_api.py index 1c6f45596..a78a98ae5 100644 --- a/netbox/dcim/tests/test_api.py +++ b/netbox/dcim/tests/test_api.py @@ -7,6 +7,7 @@ from dcim.choices import * from dcim.constants import * from dcim.models import * from ipam.models import ASN, RIR, VLAN, VRF +from netbox.api.serializers import GenericObjectSerializer from utilities.testing import APITestCase, APIViewTestCases, create_test_device from virtualization.models import Cluster, ClusterType from wireless.choices import WirelessChannelChoices @@ -1864,6 +1865,17 @@ class CableTest(APIViewTestCases.APIViewTestCase): # TODO: Allow updating cable terminations test_update_object = None + def model_to_dict(self, *args, **kwargs): + data = super().model_to_dict(*args, **kwargs) + + # Serialize termination objects + if 'a_terminations' in data: + data['a_terminations'] = GenericObjectSerializer(data['a_terminations'], many=True).data + if 'b_terminations' in data: + data['b_terminations'] = GenericObjectSerializer(data['b_terminations'], many=True).data + + return data + @classmethod def setUpTestData(cls): site = Site.objects.create(name='Site 1', slug='site-1') @@ -1893,24 +1905,36 @@ class CableTest(APIViewTestCases.APIViewTestCase): cls.create_data = [ { - 'a_terminations_type': 'dcim.interface', - 'a_terminations': [interfaces[4].pk], - 'b_terminations_type': 'dcim.interface', - 'b_terminations': [interfaces[14].pk], + 'a_terminations': [{ + 'object_type': 'dcim.interface', + 'object_id': interfaces[4].pk, + }], + 'b_terminations': [{ + 'object_type': 'dcim.interface', + 'object_id': interfaces[14].pk, + }], 'label': 'Cable 4', }, { - 'a_terminations_type': 'dcim.interface', - 'a_terminations': [interfaces[5].pk], - 'b_terminations_type': 'dcim.interface', - 'b_terminations': [interfaces[15].pk], + 'a_terminations': [{ + 'object_type': 'dcim.interface', + 'object_id': interfaces[5].pk, + }], + 'b_terminations': [{ + 'object_type': 'dcim.interface', + 'object_id': interfaces[15].pk, + }], 'label': 'Cable 5', }, { - 'a_terminations_type': 'dcim.interface', - 'a_terminations': [interfaces[6].pk], - 'b_terminations_type': 'dcim.interface', - 'b_terminations': [interfaces[16].pk], + 'a_terminations': [{ + 'object_type': 'dcim.interface', + 'object_id': interfaces[6].pk, + }], + 'b_terminations': [{ + 'object_type': 'dcim.interface', + 'object_id': interfaces[16].pk, + }], 'label': 'Cable 6', }, ] diff --git a/netbox/dcim/tests/test_views.py b/netbox/dcim/tests/test_views.py index c6a531a31..a25267166 100644 --- a/netbox/dcim/tests/test_views.py +++ b/netbox/dcim/tests/test_views.py @@ -12,6 +12,7 @@ from dcim.choices import * from dcim.constants import * from dcim.models import * from ipam.models import ASN, RIR, VLAN, VRF +from netbox.api.serializers import GenericObjectSerializer from tenancy.models import Tenant from utilities.testing import ViewTestCases, create_tags, create_test_device, post_data from wireless.models import WirelessLAN @@ -2640,8 +2641,8 @@ class CableTestCase( cls.form_data = { # TODO: Revisit this limitation # Changing terminations not supported when editing an existing Cable - 'a_terminations': interfaces[0].pk, - 'b_terminations': interfaces[3].pk, + 'a_terminations': [interfaces[0].pk], + 'b_terminations': [interfaces[3].pk], 'type': CableTypeChoices.TYPE_CAT6, 'status': LinkStatusChoices.STATUS_PLANNED, 'label': 'Label', @@ -2667,6 +2668,17 @@ class CableTestCase( 'length_unit': CableLengthUnitChoices.UNIT_METER, } + def model_to_dict(self, *args, **kwargs): + data = super().model_to_dict(*args, **kwargs) + + # Serialize termination objects + if 'a_terminations' in data: + data['a_terminations'] = [obj.pk for obj in data['a_terminations']] + if 'b_terminations' in data: + data['b_terminations'] = [obj.pk for obj in data['b_terminations']] + + return data + class VirtualChassisTestCase(ViewTestCases.PrimaryObjectViewTestCase): model = VirtualChassis diff --git a/netbox/templates/dcim/cable.html b/netbox/templates/dcim/cable.html index f557792c1..e032d7034 100644 --- a/netbox/templates/dcim/cable.html +++ b/netbox/templates/dcim/cable.html @@ -63,13 +63,13 @@
    Termination A
    - {% include 'dcim/inc/cable_termination.html' with terminations=object.get_a_terminations %} + {% include 'dcim/inc/cable_termination.html' with terminations=object.a_terminations %}
    Termination B
    - {% include 'dcim/inc/cable_termination.html' with terminations=object.get_b_terminations %} + {% include 'dcim/inc/cable_termination.html' with terminations=object.b_terminations %}
    {% plugin_right_page object %} From 3eb6b6c07fc1e666fa1148981200cec615b0a445 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 13 Jul 2022 16:18:55 -0400 Subject: [PATCH 161/245] Clean up core API imports --- netbox/circuits/api/nested_serializers.py | 2 +- netbox/circuits/api/serializers.py | 4 ++-- netbox/circuits/api/urls.py | 2 +- netbox/dcim/api/serializers.py | 2 +- netbox/dcim/api/urls.py | 2 +- netbox/extras/api/nested_serializers.py | 4 ++-- netbox/extras/api/serializers.py | 2 +- netbox/extras/api/urls.py | 2 +- netbox/ipam/api/nested_serializers.py | 2 +- netbox/ipam/api/serializers.py | 2 +- netbox/ipam/api/urls.py | 3 +-- netbox/netbox/api/__init__.py | 15 --------------- netbox/netbox/api/metadata.py | 2 +- netbox/tenancy/api/nested_serializers.py | 2 +- netbox/tenancy/api/serializers.py | 2 +- netbox/tenancy/api/urls.py | 2 +- netbox/users/api/nested_serializers.py | 3 ++- netbox/users/api/serializers.py | 3 ++- netbox/users/api/urls.py | 2 +- netbox/utilities/custom_inspectors.py | 3 ++- netbox/virtualization/api/nested_serializers.py | 2 +- netbox/virtualization/api/serializers.py | 2 +- netbox/virtualization/api/urls.py | 2 +- netbox/wireless/api/nested_serializers.py | 2 +- netbox/wireless/api/serializers.py | 2 +- netbox/wireless/api/urls.py | 2 +- 26 files changed, 30 insertions(+), 43 deletions(-) diff --git a/netbox/circuits/api/nested_serializers.py b/netbox/circuits/api/nested_serializers.py index 6f7cb4f21..8fc1bfaf7 100644 --- a/netbox/circuits/api/nested_serializers.py +++ b/netbox/circuits/api/nested_serializers.py @@ -1,7 +1,7 @@ from rest_framework import serializers from circuits.models import * -from netbox.api import WritableNestedSerializer +from netbox.api.serializers import WritableNestedSerializer __all__ = [ 'NestedCircuitSerializer', diff --git a/netbox/circuits/api/serializers.py b/netbox/circuits/api/serializers.py index 6b09cd531..c1d856f39 100644 --- a/netbox/circuits/api/serializers.py +++ b/netbox/circuits/api/serializers.py @@ -2,11 +2,11 @@ from rest_framework import serializers from circuits.choices import CircuitStatusChoices from circuits.models import * -from dcim.api.nested_serializers import NestedCableSerializer, NestedSiteSerializer +from dcim.api.nested_serializers import NestedSiteSerializer from dcim.api.serializers import CabledObjectSerializer from ipam.models import ASN from ipam.api.nested_serializers import NestedASNSerializer -from netbox.api import ChoiceField, SerializedPKRelatedField +from netbox.api.fields import ChoiceField, SerializedPKRelatedField from netbox.api.serializers import NetBoxModelSerializer, WritableNestedSerializer from tenancy.api.nested_serializers import NestedTenantSerializer from .nested_serializers import * diff --git a/netbox/circuits/api/urls.py b/netbox/circuits/api/urls.py index 616adfaa4..9d75009d5 100644 --- a/netbox/circuits/api/urls.py +++ b/netbox/circuits/api/urls.py @@ -1,4 +1,4 @@ -from netbox.api import NetBoxRouter +from netbox.api.routers import NetBoxRouter from . import views diff --git a/netbox/dcim/api/serializers.py b/netbox/dcim/api/serializers.py index 66d28c3fb..cc5c87a8a 100644 --- a/netbox/dcim/api/serializers.py +++ b/netbox/dcim/api/serializers.py @@ -13,7 +13,7 @@ from ipam.api.nested_serializers import ( NestedVRFSerializer, ) from ipam.models import ASN, VLAN -from netbox.api import ChoiceField, ContentTypeField, SerializedPKRelatedField +from netbox.api.fields import ChoiceField, ContentTypeField, SerializedPKRelatedField from netbox.api.serializers import ( GenericObjectSerializer, NestedGroupModelSerializer, NetBoxModelSerializer, ValidatedModelSerializer, WritableNestedSerializer, diff --git a/netbox/dcim/api/urls.py b/netbox/dcim/api/urls.py index e73678f71..47bbfd525 100644 --- a/netbox/dcim/api/urls.py +++ b/netbox/dcim/api/urls.py @@ -1,4 +1,4 @@ -from netbox.api import NetBoxRouter +from netbox.api.routers import NetBoxRouter from . import views diff --git a/netbox/extras/api/nested_serializers.py b/netbox/extras/api/nested_serializers.py index 4acde31ab..44dfe7cbc 100644 --- a/netbox/extras/api/nested_serializers.py +++ b/netbox/extras/api/nested_serializers.py @@ -1,8 +1,8 @@ from rest_framework import serializers from extras import choices, models -from netbox.api import ChoiceField, WritableNestedSerializer -from netbox.api.serializers import NestedTagSerializer +from netbox.api.fields import ChoiceField +from netbox.api.serializers import NestedTagSerializer, WritableNestedSerializer from users.api.nested_serializers import NestedUserSerializer __all__ = [ diff --git a/netbox/extras/api/serializers.py b/netbox/extras/api/serializers.py index 988c3bf7b..0688f6d76 100644 --- a/netbox/extras/api/serializers.py +++ b/netbox/extras/api/serializers.py @@ -12,8 +12,8 @@ from dcim.models import DeviceRole, DeviceType, Location, Platform, Region, Site from extras.choices import * from extras.models import * from extras.utils import FeatureQuery -from netbox.api import ChoiceField, ContentTypeField, SerializedPKRelatedField from netbox.api.exceptions import SerializerNotFound +from netbox.api.fields import ChoiceField, ContentTypeField, SerializedPKRelatedField from netbox.api.serializers import BaseModelSerializer, NetBoxModelSerializer, ValidatedModelSerializer from tenancy.api.nested_serializers import NestedTenantSerializer, NestedTenantGroupSerializer from tenancy.models import Tenant, TenantGroup diff --git a/netbox/extras/api/urls.py b/netbox/extras/api/urls.py index dd6a5aeff..bcad6b77c 100644 --- a/netbox/extras/api/urls.py +++ b/netbox/extras/api/urls.py @@ -1,4 +1,4 @@ -from netbox.api import NetBoxRouter +from netbox.api.routers import NetBoxRouter from . import views diff --git a/netbox/ipam/api/nested_serializers.py b/netbox/ipam/api/nested_serializers.py index e74d60fb2..7809e84f8 100644 --- a/netbox/ipam/api/nested_serializers.py +++ b/netbox/ipam/api/nested_serializers.py @@ -2,7 +2,7 @@ from rest_framework import serializers from ipam import models from ipam.models.l2vpn import L2VPNTermination, L2VPN -from netbox.api import WritableNestedSerializer +from netbox.api.serializers import WritableNestedSerializer __all__ = [ 'NestedAggregateSerializer', diff --git a/netbox/ipam/api/serializers.py b/netbox/ipam/api/serializers.py index 9cde08374..32fa4e6af 100644 --- a/netbox/ipam/api/serializers.py +++ b/netbox/ipam/api/serializers.py @@ -8,7 +8,7 @@ from dcim.api.nested_serializers import NestedDeviceSerializer, NestedSiteSerial from ipam.choices import * from ipam.constants import IPADDRESS_ASSIGNMENT_MODELS, VLANGROUP_SCOPE_TYPES from ipam.models import * -from netbox.api import ChoiceField, ContentTypeField, SerializedPKRelatedField +from netbox.api.fields import ChoiceField, ContentTypeField, SerializedPKRelatedField from netbox.api.serializers import NetBoxModelSerializer from tenancy.api.nested_serializers import NestedTenantSerializer from utilities.api import get_serializer_for_model diff --git a/netbox/ipam/api/urls.py b/netbox/ipam/api/urls.py index 20e31f4d4..1e077c087 100644 --- a/netbox/ipam/api/urls.py +++ b/netbox/ipam/api/urls.py @@ -1,7 +1,6 @@ from django.urls import path -from netbox.api import NetBoxRouter -from ipam.models import IPRange, Prefix +from netbox.api.routers import NetBoxRouter from . import views diff --git a/netbox/netbox/api/__init__.py b/netbox/netbox/api/__init__.py index 231ab55e6..e69de29bb 100644 --- a/netbox/netbox/api/__init__.py +++ b/netbox/netbox/api/__init__.py @@ -1,15 +0,0 @@ -from .fields import * -from .routers import NetBoxRouter -from .serializers import BulkOperationSerializer, ValidatedModelSerializer, WritableNestedSerializer - - -__all__ = ( - 'BulkOperationSerializer', - 'ChoiceField', - 'ContentTypeField', - 'IPNetworkSerializer', - 'NetBoxRouter', - 'SerializedPKRelatedField', - 'ValidatedModelSerializer', - 'WritableNestedSerializer', -) diff --git a/netbox/netbox/api/metadata.py b/netbox/netbox/api/metadata.py index bc4ecf871..dff1474d9 100644 --- a/netbox/netbox/api/metadata.py +++ b/netbox/netbox/api/metadata.py @@ -5,7 +5,7 @@ from rest_framework import exceptions from rest_framework.metadata import SimpleMetadata from rest_framework.request import clone_request -from netbox.api import ContentTypeField +from netbox.api.fields import ContentTypeField class BulkOperationMetadata(SimpleMetadata): diff --git a/netbox/tenancy/api/nested_serializers.py b/netbox/tenancy/api/nested_serializers.py index 00ac6ff84..2f95eca8c 100644 --- a/netbox/tenancy/api/nested_serializers.py +++ b/netbox/tenancy/api/nested_serializers.py @@ -1,6 +1,6 @@ from rest_framework import serializers -from netbox.api import WritableNestedSerializer +from netbox.api.serializers import WritableNestedSerializer from tenancy.models import * __all__ = [ diff --git a/netbox/tenancy/api/serializers.py b/netbox/tenancy/api/serializers.py index a2286efed..b5cce741a 100644 --- a/netbox/tenancy/api/serializers.py +++ b/netbox/tenancy/api/serializers.py @@ -2,7 +2,7 @@ from django.contrib.auth.models import ContentType from drf_yasg.utils import swagger_serializer_method from rest_framework import serializers -from netbox.api import ChoiceField, ContentTypeField +from netbox.api.fields import ChoiceField, ContentTypeField from netbox.api.serializers import NestedGroupModelSerializer, NetBoxModelSerializer from tenancy.choices import ContactPriorityChoices from tenancy.models import * diff --git a/netbox/tenancy/api/urls.py b/netbox/tenancy/api/urls.py index 7dbe59ea4..18ea98241 100644 --- a/netbox/tenancy/api/urls.py +++ b/netbox/tenancy/api/urls.py @@ -1,4 +1,4 @@ -from netbox.api import NetBoxRouter +from netbox.api.routers import NetBoxRouter from . import views diff --git a/netbox/users/api/nested_serializers.py b/netbox/users/api/nested_serializers.py index 51e0c5b26..e9e730cc4 100644 --- a/netbox/users/api/nested_serializers.py +++ b/netbox/users/api/nested_serializers.py @@ -2,7 +2,8 @@ from django.contrib.auth.models import Group, User from django.contrib.contenttypes.models import ContentType from rest_framework import serializers -from netbox.api import ContentTypeField, WritableNestedSerializer +from netbox.api.fields import ContentTypeField +from netbox.api.serializers import WritableNestedSerializer from users.models import ObjectPermission, Token __all__ = [ diff --git a/netbox/users/api/serializers.py b/netbox/users/api/serializers.py index d05f6c7da..1ec3528f7 100644 --- a/netbox/users/api/serializers.py +++ b/netbox/users/api/serializers.py @@ -2,7 +2,8 @@ from django.contrib.auth.models import Group, User from django.contrib.contenttypes.models import ContentType from rest_framework import serializers -from netbox.api import ContentTypeField, IPNetworkSerializer, SerializedPKRelatedField, ValidatedModelSerializer +from netbox.api.fields import ContentTypeField, IPNetworkSerializer, SerializedPKRelatedField +from netbox.api.serializers import ValidatedModelSerializer from users.models import ObjectPermission, Token from .nested_serializers import * diff --git a/netbox/users/api/urls.py b/netbox/users/api/urls.py index f46cc1680..599d0bb61 100644 --- a/netbox/users/api/urls.py +++ b/netbox/users/api/urls.py @@ -1,6 +1,6 @@ from django.urls import include, path -from netbox.api import NetBoxRouter +from netbox.api.routers import NetBoxRouter from . import views diff --git a/netbox/utilities/custom_inspectors.py b/netbox/utilities/custom_inspectors.py index b110a9123..1a5ede23f 100644 --- a/netbox/utilities/custom_inspectors.py +++ b/netbox/utilities/custom_inspectors.py @@ -6,7 +6,8 @@ from rest_framework.fields import ChoiceField from rest_framework.relations import ManyRelatedField from extras.api.customfields import CustomFieldsDataField -from netbox.api import ChoiceField, SerializedPKRelatedField, WritableNestedSerializer +from netbox.api.fields import ChoiceField, SerializedPKRelatedField +from netbox.api.serializers import WritableNestedSerializer class NetBoxSwaggerAutoSchema(SwaggerAutoSchema): diff --git a/netbox/virtualization/api/nested_serializers.py b/netbox/virtualization/api/nested_serializers.py index 16e10b5fd..07a9f5d13 100644 --- a/netbox/virtualization/api/nested_serializers.py +++ b/netbox/virtualization/api/nested_serializers.py @@ -1,6 +1,6 @@ from rest_framework import serializers -from netbox.api import WritableNestedSerializer +from netbox.api.serializers import WritableNestedSerializer from virtualization.models import Cluster, ClusterGroup, ClusterType, VirtualMachine, VMInterface __all__ = [ diff --git a/netbox/virtualization/api/serializers.py b/netbox/virtualization/api/serializers.py index c5816dca8..903d89a07 100644 --- a/netbox/virtualization/api/serializers.py +++ b/netbox/virtualization/api/serializers.py @@ -9,7 +9,7 @@ from ipam.api.nested_serializers import ( NestedIPAddressSerializer, NestedL2VPNTerminationSerializer, NestedVLANSerializer, NestedVRFSerializer, ) from ipam.models import VLAN -from netbox.api import ChoiceField, SerializedPKRelatedField +from netbox.api.fields import ChoiceField, SerializedPKRelatedField from netbox.api.serializers import NetBoxModelSerializer from tenancy.api.nested_serializers import NestedTenantSerializer from virtualization.choices import * diff --git a/netbox/virtualization/api/urls.py b/netbox/virtualization/api/urls.py index 07b20bfd7..2ceeb8ce6 100644 --- a/netbox/virtualization/api/urls.py +++ b/netbox/virtualization/api/urls.py @@ -1,4 +1,4 @@ -from netbox.api import NetBoxRouter +from netbox.api.routers import NetBoxRouter from . import views diff --git a/netbox/wireless/api/nested_serializers.py b/netbox/wireless/api/nested_serializers.py index e9a840bfc..0e8404266 100644 --- a/netbox/wireless/api/nested_serializers.py +++ b/netbox/wireless/api/nested_serializers.py @@ -1,6 +1,6 @@ from rest_framework import serializers -from netbox.api import WritableNestedSerializer +from netbox.api.serializers import WritableNestedSerializer from wireless.models import * __all__ = ( diff --git a/netbox/wireless/api/serializers.py b/netbox/wireless/api/serializers.py index 49d512e51..d65511765 100644 --- a/netbox/wireless/api/serializers.py +++ b/netbox/wireless/api/serializers.py @@ -3,7 +3,7 @@ from rest_framework import serializers from dcim.choices import LinkStatusChoices from dcim.api.serializers import NestedInterfaceSerializer from ipam.api.serializers import NestedVLANSerializer -from netbox.api import ChoiceField +from netbox.api.fields import ChoiceField from netbox.api.serializers import NestedGroupModelSerializer, NetBoxModelSerializer from tenancy.api.nested_serializers import NestedTenantSerializer from wireless.choices import * diff --git a/netbox/wireless/api/urls.py b/netbox/wireless/api/urls.py index 47799bd3a..5375172eb 100644 --- a/netbox/wireless/api/urls.py +++ b/netbox/wireless/api/urls.py @@ -1,4 +1,4 @@ -from netbox.api import NetBoxRouter +from netbox.api.routers import NetBoxRouter from . import views From be00d1f3c6cb207cc9b3788c04f0356e1875a1cd Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 14 Jul 2022 08:36:16 -0400 Subject: [PATCH 162/245] Fix erroneous import --- netbox/netbox/api/serializers/generic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/netbox/api/serializers/generic.py b/netbox/netbox/api/serializers/generic.py index 81ec338ff..8b4069c98 100644 --- a/netbox/netbox/api/serializers/generic.py +++ b/netbox/netbox/api/serializers/generic.py @@ -1,7 +1,7 @@ from django.contrib.contenttypes.models import ContentType from rest_framework import serializers -from netbox.api import ContentTypeField +from netbox.api.fields import ContentTypeField from utilities.utils import content_type_identifier __all__ = ( From 0615252e1555edc1f06dfa4ec057573573a4c826 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 14 Jul 2022 10:33:20 -0400 Subject: [PATCH 163/245] Add progress output to cable migration --- .../dcim/migrations/0158_populate_cable_terminations.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/netbox/dcim/migrations/0158_populate_cable_terminations.py b/netbox/dcim/migrations/0158_populate_cable_terminations.py index 82f8cd359..5836d24be 100644 --- a/netbox/dcim/migrations/0158_populate_cable_terminations.py +++ b/netbox/dcim/migrations/0158_populate_cable_terminations.py @@ -1,3 +1,5 @@ +import sys + from django.db import migrations @@ -42,6 +44,7 @@ def populate_cable_terminations(apps, schema_editor): # Queue CableTerminations to be created cable_terminations = [] + cable_count = cables.count() for i, cable in enumerate(cables, start=1): for cable_end in ('a', 'b'): # We must manually instantiate the termination object, because GFK fields are not @@ -58,6 +61,12 @@ def populate_cable_terminations(apps, schema_editor): **cache_related_objects(termination) )) + # Output progress occasionally + if 'test' not in sys.argv and not i % 100: + progress = float(i) * 100 / cable_count + sys.stdout.write(f"\r Updated {i}/{cable_count} cables ({progress:.2f}%)") + sys.stdout.flush() + # Bulk create the termination objects CableTermination.objects.bulk_create(cable_terminations, batch_size=100) From 29c81a788ff2d3121a9f80e55f8b021b5fca59c3 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 14 Jul 2022 10:37:27 -0400 Subject: [PATCH 164/245] Clean up connection tables --- netbox/dcim/tables/devices.py | 6 +++--- netbox/dcim/tables/template_code.py | 24 +++++------------------- netbox/templates/dcim/cable_trace.html | 14 +++++++------- 3 files changed, 15 insertions(+), 29 deletions(-) diff --git a/netbox/dcim/tables/devices.py b/netbox/dcim/tables/devices.py index a6c0c0ecc..c1515a15f 100644 --- a/netbox/dcim/tables/devices.py +++ b/netbox/dcim/tables/devices.py @@ -274,17 +274,17 @@ class CableTerminationTable(NetBoxTable): verbose_name='Cable Color' ) link_peer = columns.TemplateColumn( - accessor='_link_peer', + accessor='link_peers', template_code=LINKTERMINATION, orderable=False, - verbose_name='Link Peer' + verbose_name='Link Peers' ) mark_connected = columns.BooleanColumn() class PathEndpointTable(CableTerminationTable): connection = columns.TemplateColumn( - accessor='_path__last_node', + accessor='_path__destinations', template_code=LINKTERMINATION, verbose_name='Connection', orderable=False diff --git a/netbox/dcim/tables/template_code.py b/netbox/dcim/tables/template_code.py index a07186973..90befe0a4 100644 --- a/netbox/dcim/tables/template_code.py +++ b/netbox/dcim/tables/template_code.py @@ -1,11 +1,9 @@ LINKTERMINATION = """ -{% if value %} - {% if value.parent_object %} - {{ value.parent_object }} - - {% endif %} - {{ value }} -{% endif %} +{% for termination in value %} + {{ termination }}{% if not forloop.last %},{% endif %} +{% empty %} + {{ ''|placeholder }} +{% endfor %} """ CABLE_LENGTH = """ @@ -13,18 +11,6 @@ CABLE_LENGTH = """ {% if record.length %}{{ record.length|simplify_decimal }} {{ record.length_unit }}{% endif %} """ -# CABLE_TERMINATION_PARENT = """ -# {% with value.0 as termination %} -# {% if termination.device %} -# {{ termination.device }} -# {% elif termination.circuit %} -# {{ termination.circuit }} -# {% elif termination.power_panel %} -# {{ termination.power_panel }} -# {% endif %} -# {% endwith %} -# """ - DEVICE_LINK = """ {{ record.name|default:'Unnamed device' }} diff --git a/netbox/templates/dcim/cable_trace.html b/netbox/templates/dcim/cable_trace.html index ac0481925..abe13b236 100644 --- a/netbox/templates/dcim/cable_trace.html +++ b/netbox/templates/dcim/cable_trace.html @@ -10,10 +10,12 @@
    {% if path %}
    - + +
    {% with traced_path=path.origin.trace %} @@ -80,18 +82,16 @@ {% for cablepath in related_paths %} - - {{ cablepath.origin.parent_object }} / {{ cablepath.origin }} - + {{ cablepath.origins|join:", " }} - {% if cablepath.destination %} - {{ cablepath.destination }} ({{ cablepath.destination.parent_object }}) + {% if cablepath.destinations %} + {{ cablepath.destinations|join:", " }} {% else %} Incomplete {% endif %} - + {{ cablepath.segment_count }} From 15395a56e736e740757d4a2dec558ea13c862e82 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 14 Jul 2022 11:02:00 -0400 Subject: [PATCH 165/245] Move L2VPN into new menu group --- netbox/netbox/navigation_menu.py | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/netbox/netbox/navigation_menu.py b/netbox/netbox/navigation_menu.py index 513cf4d9e..a495f17c9 100644 --- a/netbox/netbox/navigation_menu.py +++ b/netbox/netbox/navigation_menu.py @@ -174,7 +174,7 @@ DEVICES_MENU = Menu( CONNECTIONS_MENU = Menu( label='Connections', - icon_class='mdi mdi-ethernet', + icon_class='mdi mdi-connection', groups=( MenuGroup( label='Connections', @@ -260,13 +260,6 @@ IPAM_MENU = Menu( get_model_item('ipam', 'vlangroup', 'VLAN Groups'), ), ), - MenuGroup( - label='L2VPNs', - items=( - get_model_item('ipam', 'l2vpn', 'L2VPNs'), - get_model_item('ipam', 'l2vpntermination', 'Terminations'), - ), - ), MenuGroup( label='Other', items=( @@ -278,6 +271,20 @@ IPAM_MENU = Menu( ), ) +OVERLAY_MENU = Menu( + label='Overlay', + icon_class='mdi mdi-graph-outline', + groups=( + MenuGroup( + label='L2VPNs', + items=( + get_model_item('ipam', 'l2vpn', 'L2VPNs'), + get_model_item('ipam', 'l2vpntermination', 'Terminations'), + ), + ), + ), +) + VIRTUALIZATION_MENU = Menu( label='Virtualization', icon_class='mdi mdi-monitor', @@ -387,6 +394,7 @@ MENUS = [ CONNECTIONS_MENU, WIRELESS_MENU, IPAM_MENU, + OVERLAY_MENU, VIRTUALIZATION_MENU, CIRCUITS_MENU, POWER_MENU, From 868e94fb730e24e174abba13a77cdef32c619e6e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 14 Jul 2022 12:04:53 -0400 Subject: [PATCH 166/245] Release v3.3-beta1 --- .github/ISSUE_TEMPLATE/bug_report.yaml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yaml | 2 +- base_requirements.txt | 3 +-- docs/release-notes/version-3.3.md | 2 +- mkdocs.yml | 1 + .../extras/migrations/0076_tag_slug_unicode.py | 18 ++++++++++++++++++ netbox/netbox/settings.py | 2 +- requirements.txt | 6 +++--- 8 files changed, 27 insertions(+), 9 deletions(-) create mode 100644 netbox/extras/migrations/0076_tag_slug_unicode.py diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 78231890b..88fbb1df9 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -14,7 +14,7 @@ body: attributes: label: NetBox version description: What version of NetBox are you currently running? - placeholder: v3.2.6 + placeholder: v3.3-beta1 validations: required: true - type: dropdown diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml index 71d45092c..1035c02fb 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yaml +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -14,7 +14,7 @@ body: attributes: label: NetBox version description: What version of NetBox are you currently running? - placeholder: v3.2.6 + placeholder: v3.3-beta1 validations: required: true - type: dropdown diff --git a/base_requirements.txt b/base_requirements.txt index efeede487..59d4b8255 100644 --- a/base_requirements.txt +++ b/base_requirements.txt @@ -52,8 +52,7 @@ django-tables2 # User-defined tags for objects # https://github.com/alex/django-taggit -# Will evaluate v3.0 during NetBox v3.3 beta -django-taggit>=2.1.0,<3.0 +django-taggit # A Django field for representing time zones # https://github.com/mfogel/django-timezone-field/ diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 7a093a35b..5fc11960e 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -1,6 +1,6 @@ # NetBox v3.3 -## v3.3.0 (FUTURE) +## v3.3-beta1 (2022-07-14) ### Breaking Changes diff --git a/mkdocs.yml b/mkdocs.yml index 5e9f4b842..34c65ed01 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -152,6 +152,7 @@ nav: - Release Checklist: 'development/release-checklist.md' - Release Notes: - Summary: 'release-notes/index.md' + - Version 3.3: 'release-notes/version-3.3.md' - Version 3.2: 'release-notes/version-3.2.md' - Version 3.1: 'release-notes/version-3.1.md' - Version 3.0: 'release-notes/version-3.0.md' diff --git a/netbox/extras/migrations/0076_tag_slug_unicode.py b/netbox/extras/migrations/0076_tag_slug_unicode.py new file mode 100644 index 000000000..3f4922963 --- /dev/null +++ b/netbox/extras/migrations/0076_tag_slug_unicode.py @@ -0,0 +1,18 @@ +# Generated by Django 4.0.6 on 2022-07-14 15:51 + +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('extras', '0075_configcontext_locations'), + ] + + operations = [ + migrations.AlterField( + model_name='tag', + name='slug', + field=models.SlugField(allow_unicode=True, max_length=100, unique=True), + ), + ] diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index b776650dc..e8d414b44 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -29,7 +29,7 @@ django.utils.encoding.force_text = force_str # Environment setup # -VERSION = '3.3.0-dev' +VERSION = '3.3-beta1' # Hostname HOSTNAME = platform.node() diff --git a/requirements.txt b/requirements.txt index 570c59adf..4c8e5e5ce 100644 --- a/requirements.txt +++ b/requirements.txt @@ -11,7 +11,7 @@ django-redis==5.2.0 django-rich==1.4.0 django-rq==2.5.1 django-tables2==2.4.1 -django-taggit==2.1.0 +django-taggit==3.0.0 django-timezone-field==5.0 djangorestframework==3.13.1 drf-yasg[validation]==1.20.0 @@ -26,10 +26,10 @@ netaddr==0.8.0 Pillow==9.2.0 psycopg2-binary==2.9.3 PyYAML==6.0 -sentry-sdk==1.7.0 +sentry-sdk==1.7.1 social-auth-app-django==5.0.0 social-auth-core==4.3.0 -svgwrite==1.4.2 +svgwrite==1.4.3 tablib==3.2.1 tzdata==2022.1 From e8dd952aa5dd908acfa3af47f918ab2f3e4b7c45 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 15 Jul 2022 10:07:35 -0400 Subject: [PATCH 167/245] Fix migration progress output --- netbox/dcim/migrations/0158_populate_cable_terminations.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/netbox/dcim/migrations/0158_populate_cable_terminations.py b/netbox/dcim/migrations/0158_populate_cable_terminations.py index 5836d24be..72d7f154a 100644 --- a/netbox/dcim/migrations/0158_populate_cable_terminations.py +++ b/netbox/dcim/migrations/0158_populate_cable_terminations.py @@ -64,6 +64,8 @@ def populate_cable_terminations(apps, schema_editor): # Output progress occasionally if 'test' not in sys.argv and not i % 100: progress = float(i) * 100 / cable_count + if i == 100: + print('') sys.stdout.write(f"\r Updated {i}/{cable_count} cables ({progress:.2f}%)") sys.stdout.flush() From 024e7d86510adcbe8a948640c052fb1c4059223a Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 15 Jul 2022 10:19:56 -0400 Subject: [PATCH 168/245] Fixes #9728: Fix validation when assigning a virtual machine to a device --- docs/release-notes/version-3.3.md | 6 +++++- netbox/virtualization/forms/models.py | 3 ++- netbox/virtualization/models.py | 4 ++++ 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 5fc11960e..b0bcaaa63 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -1,6 +1,6 @@ # NetBox v3.3 -## v3.3-beta1 (2022-07-14) +## v3.3.0 (FUTURE) ### Breaking Changes @@ -96,6 +96,10 @@ Custom field UI visibility has no impact on API operation. * [#9536](https://github.com/netbox-community/netbox/issues/9536) - Track API token usage times * [#9582](https://github.com/netbox-community/netbox/issues/9582) - Enable assigning config contexts based on device location +### Bug Fixes + +* [#9728](https://github.com/netbox-community/netbox/issues/9728) - Fix validation when assigning a virtual machine to a device + ### Plugins API * [#9075](https://github.com/netbox-community/netbox/issues/9075) - Introduce `AbortRequest` exception for cleanly interrupting object mutations diff --git a/netbox/virtualization/forms/models.py b/netbox/virtualization/forms/models.py index a60d15281..723c19332 100644 --- a/netbox/virtualization/forms/models.py +++ b/netbox/virtualization/forms/models.py @@ -189,7 +189,8 @@ class VirtualMachineForm(TenancyForm, NetBoxModelForm): queryset=Device.objects.all(), required=False, query_params={ - 'cluster_id': '$cluster' + 'cluster_id': '$cluster', + 'site_id': '$site', }, help_text="Optionally pin this VM to a specific host device within the cluster" ) diff --git a/netbox/virtualization/models.py b/netbox/virtualization/models.py index 98321976f..f07b176e7 100644 --- a/netbox/virtualization/models.py +++ b/netbox/virtualization/models.py @@ -349,6 +349,10 @@ class VirtualMachine(NetBoxModel, ConfigContextModel): }) # Validate assigned cluster device + if self.device and not self.cluster: + raise ValidationError({ + 'device': f'Must specify a cluster when assigning a host device.' + }) if self.device and self.device not in self.cluster.devices.all(): raise ValidationError({ 'device': f'The selected device ({self.device} is not assigned to this cluster ({self.cluster}).' From 587a34442a822e99357ee92daa9b5f43f3ce9ef6 Mon Sep 17 00:00:00 2001 From: Brian Candler Date: Fri, 15 Jul 2022 17:10:15 +0100 Subject: [PATCH 169/245] Documentation: distinguish release and git upgrade processes Fixes #9743 --- docs/installation/upgrading.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/installation/upgrading.md b/docs/installation/upgrading.md index 014dffaf8..deeec883a 100644 --- a/docs/installation/upgrading.md +++ b/docs/installation/upgrading.md @@ -18,6 +18,21 @@ NetBox v3.0 and later require the following: 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. +!!! warning + 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: + +``` +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. + ### Option A: Download a Release Download the [latest stable release](https://github.com/netbox-community/netbox/releases) from GitHub as a tarball or ZIP archive. Extract it to your desired path. In this example, we'll use `/opt/netbox`. From 68b87dd668dc1f497bd2cb27dc79b4e251d8626a Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 15 Jul 2022 13:27:20 -0400 Subject: [PATCH 170/245] Fixes #9729: Fix ordering of content type creation to ensure compatability with demo data --- docs/release-notes/version-3.3.md | 1 + netbox/dcim/migrations/0160_populate_cable_ends.py | 12 ++++++++---- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index b0bcaaa63..5d4a6ccfb 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -99,6 +99,7 @@ Custom field UI visibility has no impact on API operation. ### Bug Fixes * [#9728](https://github.com/netbox-community/netbox/issues/9728) - Fix validation when assigning a virtual machine to a device +* [#9729](https://github.com/netbox-community/netbox/issues/9729) - Fix ordering of content type creation to ensure compatability with demo data ### Plugins API diff --git a/netbox/dcim/migrations/0160_populate_cable_ends.py b/netbox/dcim/migrations/0160_populate_cable_ends.py index 0dac81df3..53e042abc 100644 --- a/netbox/dcim/migrations/0160_populate_cable_ends.py +++ b/netbox/dcim/migrations/0160_populate_cable_ends.py @@ -3,7 +3,6 @@ from django.db import migrations def populate_cable_terminations(apps, schema_editor): Cable = apps.get_model('dcim', 'Cable') - ContentType = apps.get_model('contenttypes', 'ContentType') cable_termination_models = ( apps.get_model('dcim', 'ConsolePort'), @@ -18,12 +17,17 @@ def populate_cable_terminations(apps, schema_editor): ) for model in cable_termination_models: - ct = ContentType.objects.get_for_model(model) model.objects.filter( - id__in=Cable.objects.filter(termination_a_type=ct).values_list('termination_a_id', flat=True) + id__in=Cable.objects.filter( + termination_a_type__app_label=model._meta.app_label, + termination_a_type__model=model._meta.model_name + ).values_list('termination_a_id', flat=True) ).update(cable_end='A') model.objects.filter( - id__in=Cable.objects.filter(termination_b_type=ct).values_list('termination_b_id', flat=True) + id__in=Cable.objects.filter( + termination_b_type__app_label=model._meta.app_label, + termination_b_type__model=model._meta.model_name + ).values_list('termination_b_id', flat=True) ).update(cable_end='B') From f385a5fd5e87c3fd07cd804ad18239a7b54a72e2 Mon Sep 17 00:00:00 2001 From: Marek Zbroch Date: Sat, 16 Jul 2022 09:42:01 +0200 Subject: [PATCH 171/245] Typo fix in CableEditView --- netbox/dcim/views.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/dcim/views.py b/netbox/dcim/views.py index b247c3a6d..12e070e70 100644 --- a/netbox/dcim/views.py +++ b/netbox/dcim/views.py @@ -2850,7 +2850,7 @@ class CableEditView(generic.ObjectEditView): termination_a = obj.terminations.filter(cable_end='A').first() a_type = termination_a.termination._meta.model if termination_a else None termination_b = obj.terminations.filter(cable_end='B').first() - b_type = termination_b.termination._meta.model if termination_a else None + b_type = termination_b.termination._meta.model if termination_b else None self.form = forms.get_cable_form(a_type, b_type) return obj From 58b191b439462316229fdf3ecc5d3ac0461e3513 Mon Sep 17 00:00:00 2001 From: Marek Zbroch Date: Sun, 17 Jul 2022 09:28:58 +0200 Subject: [PATCH 172/245] Fix CableForm Validation for #9102 --- netbox/dcim/forms/connections.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/netbox/dcim/forms/connections.py b/netbox/dcim/forms/connections.py index 1b393ec6e..62247e3e3 100644 --- a/netbox/dcim/forms/connections.py +++ b/netbox/dcim/forms/connections.py @@ -160,12 +160,11 @@ def get_cable_form(a_type, b_type): self.initial['a_terminations'] = self.instance.a_terminations self.initial['b_terminations'] = self.instance.b_terminations - def save(self, *args, **kwargs): + def clean(self): + super().clean() # Set the A/B terminations on the Cable instance self.instance.a_terminations = self.cleaned_data['a_terminations'] self.instance.b_terminations = self.cleaned_data['b_terminations'] - return super().save(*args, **kwargs) - return _CableForm From 8a2276e79136d8bac7b212ce1ad7f014ffb0de41 Mon Sep 17 00:00:00 2001 From: kkthxbye-code Date: Mon, 18 Jul 2022 16:17:16 +0200 Subject: [PATCH 173/245] Use segment_count for segment count on trace view --- netbox/templates/dcim/cable_trace.html | 72 +++++++++++++------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/netbox/templates/dcim/cable_trace.html b/netbox/templates/dcim/cable_trace.html index abe13b236..2611686f6 100644 --- a/netbox/templates/dcim/cable_trace.html +++ b/netbox/templates/dcim/cable_trace.html @@ -18,43 +18,41 @@
    - {% with traced_path=path.origin.trace %} - {% if path.is_split %} -

    Path split!

    -

    Select a node below to continue:

    -
      - {% for next_node in path.get_split_nodes %} - {% if next_node.cable %} -
    • - {{ next_node }} - (Cable {{ next_node.cable|linkify }}) -
      • - {% else %} -
    • {{ next_node }}
      • - {% endif %} - {% endfor %} -
    - {% else %} -

    Trace Completed

    - - - - - - - - - -
    Total segments{{ traced_path|length }}
    Total length - {% if total_length %} - {{ total_length|floatformat:"-2" }}{% if not is_definitive %}+{% endif %} Meters / - {{ total_length|meters_to_feet|floatformat:"-2" }} Feet - {% else %} - N/A - {% endif %} -
    - {% endif %} - {% endwith %} + {% if path.is_split %} +

    Path split!

    +

    Select a node below to continue:

    +
      + {% for next_node in path.get_split_nodes %} + {% if next_node.cable %} +
    • + {{ next_node }} + (Cable {{ next_node.cable|linkify }}) +
      • + {% else %} +
    • {{ next_node }}
      • + {% endif %} + {% endfor %} +
    + {% else %} +

    Trace Completed

    + + + + + + + + + +
    Total segments{{ path.segment_count }}
    Total length + {% if total_length %} + {{ total_length|floatformat:"-2" }}{% if not is_definitive %}+{% endif %} Meters / + {{ total_length|meters_to_feet|floatformat:"-2" }} Feet + {% else %} + N/A + {% endif %} +
    + {% endif %}
    {% else %}

    From b8da66bb55e562b7344812bf71a5165031b50cb8 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 18 Jul 2022 11:51:59 -0400 Subject: [PATCH 174/245] Fixes #9733: Handle split paths during trace when fanning out to front ports with differing cables --- docs/release-notes/version-3.3.md | 2 ++ netbox/dcim/models/cables.py | 11 ++++++++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 5d4a6ccfb..14952c2a5 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -100,6 +100,8 @@ Custom field UI visibility has no impact on API operation. * [#9728](https://github.com/netbox-community/netbox/issues/9728) - Fix validation when assigning a virtual machine to a device * [#9729](https://github.com/netbox-community/netbox/issues/9729) - Fix ordering of content type creation to ensure compatability with demo data +* [#9730](https://github.com/netbox-community/netbox/issues/9730) - Fix validation error when creating a new cable via UI form +* [#9733](https://github.com/netbox-community/netbox/issues/9733) - Handle split paths during trace when fanning out to front ports with differing cables ### Plugins API diff --git a/netbox/dcim/models/cables.py b/netbox/dcim/models/cables.py index b35864aa0..e0a489f5b 100644 --- a/netbox/dcim/models/cables.py +++ b/netbox/dcim/models/cables.py @@ -463,6 +463,10 @@ class CablePath(models.Model): """ from circuits.models import CircuitTermination + # Ensure all originating terminations are attached to the same link + if len(terminations) > 1: + assert all(t.link == terminations[0].link for t in terminations[1:]) + path = [] position_stack = [] is_complete = False @@ -474,6 +478,12 @@ class CablePath(models.Model): # Terminations must all be of the same type assert all(isinstance(t, type(terminations[0])) for t in terminations[1:]) + # Check for a split path (e.g. rear port fanning out to multiple front ports with + # different cables attached) + if len(set(t.link for t in terminations)) > 1: + is_split = True + break + # Step 1: Record the near-end termination object(s) path.append([ object_to_path_node(t) for t in terminations @@ -481,7 +491,6 @@ class CablePath(models.Model): # Step 2: Determine the attached link (Cable or WirelessLink), if any link = terminations[0].link - assert all(t.link == link for t in terminations[1:]) if link is None and len(path) == 1: # If this is the start of the path and no link exists, return None return None From 6d53788ea2ad0c946cac8f1ed15be690bf616205 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 18 Jul 2022 13:05:12 -0400 Subject: [PATCH 175/245] Changelog for #9765 --- docs/release-notes/version-3.3.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 14952c2a5..4b3f1dcb2 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -102,6 +102,7 @@ Custom field UI visibility has no impact on API operation. * [#9729](https://github.com/netbox-community/netbox/issues/9729) - Fix ordering of content type creation to ensure compatability with demo data * [#9730](https://github.com/netbox-community/netbox/issues/9730) - Fix validation error when creating a new cable via UI form * [#9733](https://github.com/netbox-community/netbox/issues/9733) - Handle split paths during trace when fanning out to front ports with differing cables +* [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view ### Plugins API From 0e18292e41f6feb77094ee0a9cd8c965071a5dd9 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 18 Jul 2022 13:09:45 -0400 Subject: [PATCH 176/245] Add summary release notes for v3.3 --- docs/release-notes/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md index f8bb365be..8a6a86174 100644 --- a/docs/release-notes/index.md +++ b/docs/release-notes/index.md @@ -10,6 +10,17 @@ Minor releases are published in April, August, and December of each calendar yea This page contains a history of all major and minor releases since NetBox v2.0. For more detail on a specific patch release, please see the release notes page for that specific minor release. +#### [Version 3.3](./version-3.3.md) (August 2022) + +* Multi-object Cable Terminations ([#9102](https://github.com/netbox-community/netbox/issues/9102)) +* L2VPN Modeling ([#8157](https://github.com/netbox-community/netbox/issues/8157)) +* PoE Interface Attributes ([#1099](https://github.com/netbox-community/netbox/issues/1099)) +* Half-Height Rack Units ([#51](https://github.com/netbox-community/netbox/issues/51)) +* Restrict API Tokens by Client IP ([#8233](https://github.com/netbox-community/netbox/issues/8233)) +* Reference User in Permission Constraints ([#9074](https://github.com/netbox-community/netbox/issues/9074)) +* Custom Field Grouping ([#8495](https://github.com/netbox-community/netbox/issues/8495)) +* Toggle Custom Field Visibility ([#9166](https://github.com/netbox-community/netbox/issues/9166)) + #### [Version 3.2](./version-3.2.md) (April 2022) * Plugins Framework Extensions ([#8333](https://github.com/netbox-community/netbox/issues/8333)) From e92b7f8bb95ebf2018a0d57dad2fe88a69cecc85 Mon Sep 17 00:00:00 2001 From: Marek Zbroch Date: Wed, 20 Jul 2022 13:02:10 +0200 Subject: [PATCH 177/245] Typo fix in REARPORT_BUTTONS template code --- netbox/dcim/tables/template_code.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/dcim/tables/template_code.py b/netbox/dcim/tables/template_code.py index 90befe0a4..082df56df 100644 --- a/netbox/dcim/tables/template_code.py +++ b/netbox/dcim/tables/template_code.py @@ -343,7 +343,7 @@ REARPORT_BUTTONS = """
  • Console Port
  • Front Port
  • Rear Port
    • -
  • Circuit Termination
    • +
  • Circuit Termination
    • {% else %} From e2580ea469e0394d7e00a65d91aca51968a97ad1 Mon Sep 17 00:00:00 2001 From: Juho Ylikorpi Date: Thu, 21 Jul 2022 16:54:23 +0300 Subject: [PATCH 178/245] fixes #9818 --- netbox/dcim/forms/connections.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netbox/dcim/forms/connections.py b/netbox/dcim/forms/connections.py index 62247e3e3..7552c0c87 100644 --- a/netbox/dcim/forms/connections.py +++ b/netbox/dcim/forms/connections.py @@ -138,7 +138,7 @@ def get_cable_form(a_type, b_type): label='Side', disabled_indicator='_occupied', query_params={ - 'circuit_id': f'termination_{cable_end}_circuit', + 'circuit_id': f'$termination_{cable_end}_circuit', } ) From 12476036cd3dc5990d2a6c9973ed9ccc758c377d Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 25 Jul 2022 09:55:20 -0400 Subject: [PATCH 179/245] Changelog for #9794, #9818 --- docs/release-notes/version-3.3.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 4b3f1dcb2..ad9ce1a0e 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -103,6 +103,8 @@ Custom field UI visibility has no impact on API operation. * [#9730](https://github.com/netbox-community/netbox/issues/9730) - Fix validation error when creating a new cable via UI form * [#9733](https://github.com/netbox-community/netbox/issues/9733) - Handle split paths during trace when fanning out to front ports with differing cables * [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view +* [#9794](https://github.com/netbox-community/netbox/issues/9794) - Fix link to connect a rear port to a circuit termination +* [#9818](https://github.com/netbox-community/netbox/issues/9818) - Fix circuit side selection when connecting a cable to a circuit termination ### Plugins API From 2583abc39d4eafdca645bc18110140f1e350c7df Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 25 Jul 2022 11:34:16 -0400 Subject: [PATCH 180/245] Fix null cable termination representation --- .../templates/dcim/inc/cable_termination.html | 118 +++++++++--------- 1 file changed, 61 insertions(+), 57 deletions(-) diff --git a/netbox/templates/dcim/inc/cable_termination.html b/netbox/templates/dcim/inc/cable_termination.html index 9d1c43bdd..ced9bda50 100644 --- a/netbox/templates/dcim/inc/cable_termination.html +++ b/netbox/templates/dcim/inc/cable_termination.html @@ -1,58 +1,62 @@ {% load helpers %} - - {% if terminations.0.device %} - {# Device component #} - - - - - - - - - - - - - - - - - {% elif terminations.0.power_panel %} - {# Power feed #} - - - - - - - - - - - - - {% else %} - {# Circuit termination #} - - - - - - - - - {% endif %} -
    Site{{ terminations.0.device.site|linkify }}
    Rack{{ terminations.0.device.rack|linkify|placeholder }}
    Device{{ terminations.0.device|linkify }}
    {{ terminations.0|meta:"verbose_name"|capfirst }} - {% for term in terminations %} - {{ term|linkify }}{% if not forloop.last %},{% endif %} - {% endfor %} -
    Site{{ terminations.0.power_panel.site|linkify }}
    Power Panel{{ terminations.0.power_panel|linkify }}
    {{ terminations.0|meta:"verbose_name"|capfirst }} - {% for term in terminations %} - {{ term|linkify }}{% if not forloop.last %},{% endif %} - {% endfor %} -
    Provider{{ terminations.0.circuit.provider|linkify }}
    Circuit - {% for term in terminations %} - {{ term.circuit|linkify }} ({{ term }}){% if not forloop.last %},{% endif %} - {% endfor %} -
    +{% if terminations.0 %} + + {% if terminations.0.device %} + {# Device component #} + + + + + + + + + + + + + + + + + {% elif terminations.0.power_panel %} + {# Power feed #} + + + + + + + + + + + + + {% elif terminations.0.circuit %} + {# Circuit termination #} + + + + + + + + + {% endif %} +
    Site{{ terminations.0.device.site|linkify }}
    Rack{{ terminations.0.device.rack|linkify|placeholder }}
    Device{{ terminations.0.device|linkify }}
    {{ terminations.0|meta:"verbose_name"|capfirst }} + {% for term in terminations %} + {{ term|linkify }}{% if not forloop.last %},{% endif %} + {% endfor %} +
    Site{{ terminations.0.power_panel.site|linkify }}
    Power Panel{{ terminations.0.power_panel|linkify }}
    {{ terminations.0|meta:"verbose_name"|capfirst }} + {% for term in terminations %} + {{ term|linkify }}{% if not forloop.last %},{% endif %} + {% endfor %} +
    Provider{{ terminations.0.circuit.provider|linkify }}
    Circuit + {% for term in terminations %} + {{ term.circuit|linkify }} ({{ term }}){% if not forloop.last %},{% endif %} + {% endfor %} +
    +{% else %} + No termination +{% endif %} From 6f7289f93217c5d3499264f2cfe6e540ba17d8e9 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Tue, 26 Jul 2022 07:22:21 -0500 Subject: [PATCH 181/245] Fixes #9844 - Add dedicated `device_vlan` form field --- netbox/ipam/forms/models.py | 10 ++++++++-- netbox/templates/ipam/l2vpntermination_edit.html | 2 +- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/netbox/ipam/forms/models.py b/netbox/ipam/forms/models.py index 415c952be..0a22cbc21 100644 --- a/netbox/ipam/forms/models.py +++ b/netbox/ipam/forms/models.py @@ -906,8 +906,9 @@ class L2VPNTerminationForm(NetBoxModelForm): label='L2VPN', fetch_trigger='open' ) - device = DynamicModelChoiceField( + device_vlan = DynamicModelChoiceField( queryset=Device.objects.all(), + label="Available on Device", required=False, query_params={} ) @@ -915,10 +916,15 @@ class L2VPNTerminationForm(NetBoxModelForm): queryset=VLAN.objects.all(), required=False, query_params={ - 'available_on_device': '$device' + 'available_on_device': '$device_vlan' }, label='VLAN' ) + device = DynamicModelChoiceField( + queryset=Device.objects.all(), + required=False, + query_params={} + ) interface = DynamicModelChoiceField( queryset=Interface.objects.all(), required=False, diff --git a/netbox/templates/ipam/l2vpntermination_edit.html b/netbox/templates/ipam/l2vpntermination_edit.html index 7b4a9f50a..c66b8a3d1 100644 --- a/netbox/templates/ipam/l2vpntermination_edit.html +++ b/netbox/templates/ipam/l2vpntermination_edit.html @@ -32,7 +32,7 @@
    - {% render_field form.device %} + {% render_field form.device_vlan %} {% render_field form.vlan %}
    From 6d30c07dd0608c80e4f0a161d7f5ed129b9baa0e Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Tue, 26 Jul 2022 07:29:18 -0500 Subject: [PATCH 182/245] Update changelog for #9844 --- docs/release-notes/version-3.3.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 4b3f1dcb2..85a2e1599 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -103,6 +103,7 @@ Custom field UI visibility has no impact on API operation. * [#9730](https://github.com/netbox-community/netbox/issues/9730) - Fix validation error when creating a new cable via UI form * [#9733](https://github.com/netbox-community/netbox/issues/9733) - Handle split paths during trace when fanning out to front ports with differing cables * [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view +* [#9844](https://github.com/netbox-community/netbox/issues/9844) - Fix interface api request when creating/editing L2VPN termination ### Plugins API From d442f8fd60c88ffabcd6f75e438baa8ecca15f98 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 26 Jul 2022 11:09:51 -0400 Subject: [PATCH 183/245] Fixes #9843: Fix rendering of custom field values (regression from #9647) --- docs/release-notes/version-3.3.md | 1 + .../templates/builtins/customfield_value.html | 20 +++++++++---------- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 8aa91f8f9..51d595123 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -105,6 +105,7 @@ Custom field UI visibility has no impact on API operation. * [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view * [#9794](https://github.com/netbox-community/netbox/issues/9794) - Fix link to connect a rear port to a circuit termination * [#9818](https://github.com/netbox-community/netbox/issues/9818) - Fix circuit side selection when connecting a cable to a circuit termination +* [#9843](https://github.com/netbox-community/netbox/issues/9843) - Fix rendering of custom field values (regression from #9647) * [#9844](https://github.com/netbox-community/netbox/issues/9844) - Fix interface api request when creating/editing L2VPN termination ### Plugins API diff --git a/netbox/utilities/templates/builtins/customfield_value.html b/netbox/utilities/templates/builtins/customfield_value.html index 8fedb03d5..ff93a5168 100644 --- a/netbox/utilities/templates/builtins/customfield_value.html +++ b/netbox/utilities/templates/builtins/customfield_value.html @@ -1,26 +1,26 @@ -{% if field.type == 'integer' and value is not None %} +{% if customfield.type == 'integer' and value is not None %} {{ value }} -{% elif field.type == 'longtext' and value %} +{% elif customfield.type == 'longtext' and value %} {{ value|markdown }} -{% elif field.type == 'boolean' and value == True %} +{% elif customfield.type == 'boolean' and value == True %} {% checkmark value true="True" %} -{% elif field.type == 'boolean' and value == False %} +{% elif customfield.type == 'boolean' and value == False %} {% checkmark value false="False" %} -{% elif field.type == 'url' and value %} +{% elif customfield.type == 'url' and value %} {{ value|truncatechars:70 }} -{% elif field.type == 'json' and value %} +{% elif customfield.type == 'json' and value %} 
    {{ value|json }}
    -{% elif field.type == 'multiselect' and value %} +{% elif customfield.type == 'multiselect' and value %} {{ value|join:", " }} -{% elif field.type == 'object' and value %} +{% elif customfield.type == 'object' and value %} {{ value|linkify }} -{% elif field.type == 'multiobject' and value %} +{% elif customfield.type == 'multiobject' and value %} {% for object in value %} {{ object|linkify }}{% if not forloop.last %}
    {% endif %} {% endfor %} {% elif value %} {{ value }} -{% elif field.required %} +{% elif customfield.required %} Not defined {% else %} {{ ''|placeholder }} From 466931d2fbb5e9db6b3eb90d385119ae44b34886 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 26 Jul 2022 12:41:51 -0400 Subject: [PATCH 184/245] Fixes #9829: Arrange custom fields by group when editing objects --- docs/release-notes/version-3.3.md | 1 + netbox/extras/forms/customfields.py | 4 +++ netbox/netbox/forms/base.py | 27 ++++++------------- .../templates/inc/panels/custom_fields.html | 2 +- .../form_helpers/render_custom_fields.html | 13 ++++++--- 5 files changed, 23 insertions(+), 24 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 51d595123..7e8fd50e3 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -105,6 +105,7 @@ Custom field UI visibility has no impact on API operation. * [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view * [#9794](https://github.com/netbox-community/netbox/issues/9794) - Fix link to connect a rear port to a circuit termination * [#9818](https://github.com/netbox-community/netbox/issues/9818) - Fix circuit side selection when connecting a cable to a circuit termination +* [#9829](https://github.com/netbox-community/netbox/issues/9829) - Arrange custom fields by group when editing objects * [#9843](https://github.com/netbox-community/netbox/issues/9843) - Fix rendering of custom field values (regression from #9647) * [#9844](https://github.com/netbox-community/netbox/issues/9844) - Fix interface api request when creating/editing L2VPN termination diff --git a/netbox/extras/forms/customfields.py b/netbox/extras/forms/customfields.py index 4cf8b5e0a..7574f4f2b 100644 --- a/netbox/extras/forms/customfields.py +++ b/netbox/extras/forms/customfields.py @@ -19,6 +19,7 @@ class CustomFieldsMixin: def __init__(self, *args, **kwargs): self.custom_fields = {} + self.custom_field_groups = {} super().__init__(*args, **kwargs) @@ -58,3 +59,6 @@ class CustomFieldsMixin: # Annotate the field in the list of CustomField form fields self.custom_fields[field_name] = customfield + if customfield.group_name not in self.custom_field_groups: + self.custom_field_groups[customfield.group_name] = [] + self.custom_field_groups[customfield.group_name].append(field_name) diff --git a/netbox/netbox/forms/base.py b/netbox/netbox/forms/base.py index 0e232af1d..2676e4cde 100644 --- a/netbox/netbox/forms/base.py +++ b/netbox/netbox/forms/base.py @@ -94,30 +94,19 @@ class NetBoxModelBulkEditForm(BootstrapMixin, CustomFieldsMixin, forms.Form): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) + self.fields['pk'].queryset = self.model.objects.all() + self._extend_nullable_fields() + def _get_form_field(self, customfield): return customfield.to_form_field(set_initial=False, enforce_required=False) - def _append_customfield_fields(self): - """ - Append form fields for all CustomFields assigned to this object type. - """ - nullable_custom_fields = [] - for customfield in self._get_custom_fields(self._get_content_type()): - field_name = f'cf_{customfield.name}' - self.fields[field_name] = self._get_form_field(customfield) - - # Record non-required custom fields as nullable - if not customfield.required: - nullable_custom_fields.append(field_name) - - # Annotate the field in the list of CustomField form fields - self.custom_fields[field_name] = customfield - - # Annotate nullable custom fields (if any) on the form instance - if nullable_custom_fields: - self.nullable_fields = (*self.nullable_fields, *nullable_custom_fields) + def _extend_nullable_fields(self): + nullable_custom_fields = [ + name for name, customfield in self.custom_fields.items() if not customfield.required + ] + self.nullable_fields = (*self.nullable_fields, *nullable_custom_fields) class NetBoxModelFilterSetForm(BootstrapMixin, CustomFieldsMixin, forms.Form): diff --git a/netbox/templates/inc/panels/custom_fields.html b/netbox/templates/inc/panels/custom_fields.html index 90059447f..616b1c712 100644 --- a/netbox/templates/inc/panels/custom_fields.html +++ b/netbox/templates/inc/panels/custom_fields.html @@ -7,7 +7,7 @@
    {% for group_name, fields in custom_fields.items %} {% if group_name %} -
    {{ group_name }}
    +
    {{ group_name }}
    {% endif %} {% for field, value in fields.items %} diff --git a/netbox/utilities/templates/form_helpers/render_custom_fields.html b/netbox/utilities/templates/form_helpers/render_custom_fields.html index f3e5bffa9..6b0b2840b 100644 --- a/netbox/utilities/templates/form_helpers/render_custom_fields.html +++ b/netbox/utilities/templates/form_helpers/render_custom_fields.html @@ -1,7 +1,12 @@ {% load form_helpers %} -{% for field in form %} - {% if field.name in form.custom_fields %} - {% render_field field %} - {% endif %} +{% for group, fields in form.custom_field_groups.items %} + {% if group %} +
    +
    {{ group }}
    +
    + {% endif %} + {% for name in fields %} + {% render_field form|getfield:name %} + {% endfor %} {% endfor %} From a6be8dccf55726ddd1c9a8319f4a162c43023fa0 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 26 Jul 2022 15:45:47 -0400 Subject: [PATCH 185/245] Fixes #9847: Respect desc_units when ordering rack units --- docs/release-notes/version-3.3.md | 1 + netbox/dcim/models/racks.py | 5 ++--- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 7e8fd50e3..87cb00730 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -108,6 +108,7 @@ Custom field UI visibility has no impact on API operation. * [#9829](https://github.com/netbox-community/netbox/issues/9829) - Arrange custom fields by group when editing objects * [#9843](https://github.com/netbox-community/netbox/issues/9843) - Fix rendering of custom field values (regression from #9647) * [#9844](https://github.com/netbox-community/netbox/issues/9844) - Fix interface api request when creating/editing L2VPN termination +* [#9847](https://github.com/netbox-community/netbox/issues/9847) - Respect `desc_units` when ordering rack units ### Plugins API diff --git a/netbox/dcim/models/racks.py b/netbox/dcim/models/racks.py index 2039def09..4dcfcde28 100644 --- a/netbox/dcim/models/racks.py +++ b/netbox/dcim/models/racks.py @@ -244,10 +244,9 @@ class Rack(NetBoxModel): """ Return a list of unit numbers, top to bottom. """ - max_position = self.u_height + decimal.Decimal(0.5) if self.desc_units: - drange(0.5, max_position, 0.5) - return drange(max_position, 0.5, -0.5) + return drange(decimal.Decimal(1.0), self.u_height + 1, 0.5) + return drange(self.u_height + decimal.Decimal(0.5), 0.5, -0.5) def get_status_color(self): return RackStatusChoices.colors.get(self.status) From c5fb7b72f0eb2b1e3f53b3397090b0470398f725 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 28 Jul 2022 14:36:20 -0400 Subject: [PATCH 186/245] Closes #9391: Remove 500-character limit for custom link text & URL fields --- docs/release-notes/version-3.3.md | 1 + .../0077_customlink_extend_text_and_url.py | 21 +++++++++++++++++++ netbox/extras/models/models.py | 6 ++---- 3 files changed, 24 insertions(+), 4 deletions(-) create mode 100644 netbox/extras/migrations/0077_customlink_extend_text_and_url.py diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 87cb00730..211f264f0 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -93,6 +93,7 @@ Custom field UI visibility has no impact on API operation. * [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results * [#9070](https://github.com/netbox-community/netbox/issues/9070) - Hide navigation menu items based on user permissions * [#9177](https://github.com/netbox-community/netbox/issues/9177) - Add tenant assignment for wireless LANs & links +* [#9391](https://github.com/netbox-community/netbox/issues/9391) - Remove 500-character limit for custom link text & URL fields * [#9536](https://github.com/netbox-community/netbox/issues/9536) - Track API token usage times * [#9582](https://github.com/netbox-community/netbox/issues/9582) - Enable assigning config contexts based on device location diff --git a/netbox/extras/migrations/0077_customlink_extend_text_and_url.py b/netbox/extras/migrations/0077_customlink_extend_text_and_url.py new file mode 100644 index 000000000..c08948aa6 --- /dev/null +++ b/netbox/extras/migrations/0077_customlink_extend_text_and_url.py @@ -0,0 +1,21 @@ +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('extras', '0076_tag_slug_unicode'), + ] + + operations = [ + migrations.AlterField( + model_name='customlink', + name='link_text', + field=models.TextField(), + ), + migrations.AlterField( + model_name='customlink', + name='link_url', + field=models.TextField(), + ), + ] diff --git a/netbox/extras/models/models.py b/netbox/extras/models/models.py index e614a1258..4873a1f9e 100644 --- a/netbox/extras/models/models.py +++ b/netbox/extras/models/models.py @@ -204,12 +204,10 @@ class CustomLink(ExportTemplatesMixin, WebhooksMixin, ChangeLoggedModel): enabled = models.BooleanField( default=True ) - link_text = models.CharField( - max_length=500, + link_text = models.TextField( help_text="Jinja2 template code for link text" ) - link_url = models.CharField( - max_length=500, + link_url = models.TextField( verbose_name='Link URL', help_text="Jinja2 template code for link URL" ) From 2c43c8d077c34402720b86658674c46371da321d Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 28 Jul 2022 15:03:24 -0400 Subject: [PATCH 187/245] Closes #9793: Add PoE attributes to interface templates --- docs/models/dcim/interfacetemplate.md | 2 +- docs/release-notes/version-3.3.md | 4 +++- netbox/dcim/api/serializers.py | 12 +++++++++++- netbox/dcim/filtersets.py | 6 ++++++ netbox/dcim/forms/bulk_edit.py | 16 +++++++++++++++- netbox/dcim/forms/filtersets.py | 6 ++++-- netbox/dcim/forms/models.py | 4 +++- netbox/dcim/forms/object_import.py | 14 ++++++++++++-- netbox/dcim/graphql/types.py | 6 ++++++ .../migrations/0155_interface_poe_mode_type.py | 10 ++++++++++ netbox/dcim/models/device_component_templates.py | 16 +++++++++++++++- netbox/dcim/models/devices.py | 2 ++ netbox/dcim/tables/devicetypes.py | 2 +- netbox/dcim/tests/test_filtersets.py | 12 ++++++++++-- 14 files changed, 99 insertions(+), 13 deletions(-) diff --git a/docs/models/dcim/interfacetemplate.md b/docs/models/dcim/interfacetemplate.md index d9b30dd87..e11abcce4 100644 --- a/docs/models/dcim/interfacetemplate.md +++ b/docs/models/dcim/interfacetemplate.md @@ -1,3 +1,3 @@ ## Interface Templates -A template for a network interface that will be created on all instantiations of the parent device type. Each interface may be assigned a physical or virtual type, and may be designated as "management-only." +A template for a network interface that will be created on all instantiations of the parent device type. Each interface may be assigned a physical or virtual type, and may be designated as "management-only." Power over Ethernet (PoE) mode and type may also be assigned to interface templates. diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 211f264f0..68cff0547 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -97,7 +97,7 @@ Custom field UI visibility has no impact on API operation. * [#9536](https://github.com/netbox-community/netbox/issues/9536) - Track API token usage times * [#9582](https://github.com/netbox-community/netbox/issues/9582) - Enable assigning config contexts based on device location -### Bug Fixes +### Bug Fixes (from Beta1) * [#9728](https://github.com/netbox-community/netbox/issues/9728) - Fix validation when assigning a virtual machine to a device * [#9729](https://github.com/netbox-community/netbox/issues/9729) - Fix ordering of content type creation to ensure compatability with demo data @@ -177,6 +177,8 @@ Custom field UI visibility has no impact on API operation. * `connected_endpoint_reachable` has been renamed to `connected_endpoints_reachable` * Added the optional `poe_mode` and `poe_type` fields * Added the `l2vpn_termination` read-only field +* dcim.InterfaceTemplate + * Added the optional `poe_mode` and `poe_type` fields * dcim.Location * Added required `status` field (default value: `active`) * dcim.PowerOutlet diff --git a/netbox/dcim/api/serializers.py b/netbox/dcim/api/serializers.py index 5f30b7385..249a3f167 100644 --- a/netbox/dcim/api/serializers.py +++ b/netbox/dcim/api/serializers.py @@ -469,12 +469,22 @@ class InterfaceTemplateSerializer(ValidatedModelSerializer): default=None ) type = ChoiceField(choices=InterfaceTypeChoices) + poe_mode = ChoiceField( + choices=InterfacePoEModeChoices, + required=False, + allow_blank=True + ) + poe_type = ChoiceField( + choices=InterfacePoETypeChoices, + required=False, + allow_blank=True + ) class Meta: model = InterfaceTemplate fields = [ 'id', 'url', 'display', 'device_type', 'module_type', 'name', 'label', 'type', 'mgmt_only', 'description', - 'created', 'last_updated', + 'poe_mode', 'poe_type', 'created', 'last_updated', ] diff --git a/netbox/dcim/filtersets.py b/netbox/dcim/filtersets.py index 4bdc525a5..874d08ba5 100644 --- a/netbox/dcim/filtersets.py +++ b/netbox/dcim/filtersets.py @@ -652,6 +652,12 @@ class InterfaceTemplateFilterSet(ChangeLoggedModelFilterSet, ModularDeviceTypeCo choices=InterfaceTypeChoices, null_value=None ) + poe_mode = django_filters.MultipleChoiceFilter( + choices=InterfacePoEModeChoices + ) + poe_type = django_filters.MultipleChoiceFilter( + choices=InterfacePoETypeChoices + ) class Meta: model = InterfaceTemplate diff --git a/netbox/dcim/forms/bulk_edit.py b/netbox/dcim/forms/bulk_edit.py index 6d51302d3..8f765ae9b 100644 --- a/netbox/dcim/forms/bulk_edit.py +++ b/netbox/dcim/forms/bulk_edit.py @@ -818,8 +818,22 @@ class InterfaceTemplateBulkEditForm(BulkEditForm): description = forms.CharField( required=False ) + poe_mode = forms.ChoiceField( + choices=add_blank_choice(InterfacePoEModeChoices), + required=False, + initial='', + widget=StaticSelect(), + label='PoE mode' + ) + poe_type = forms.ChoiceField( + choices=add_blank_choice(InterfacePoETypeChoices), + required=False, + initial='', + widget=StaticSelect(), + label='PoE type' + ) - nullable_fields = ('label', 'description') + nullable_fields = ('label', 'description', 'poe_mode', 'poe_type') class FrontPortTemplateBulkEditForm(BulkEditForm): diff --git a/netbox/dcim/forms/filtersets.py b/netbox/dcim/forms/filtersets.py index 8d2e24c9c..c5474a2b1 100644 --- a/netbox/dcim/forms/filtersets.py +++ b/netbox/dcim/forms/filtersets.py @@ -1027,11 +1027,13 @@ class InterfaceFilterForm(DeviceComponentFilterForm): ) poe_mode = MultipleChoiceField( choices=InterfacePoEModeChoices, - required=False + required=False, + label='PoE mode' ) poe_type = MultipleChoiceField( choices=InterfacePoEModeChoices, - required=False + required=False, + label='PoE type' ) rf_role = MultipleChoiceField( choices=WirelessRoleChoices, diff --git a/netbox/dcim/forms/models.py b/netbox/dcim/forms/models.py index aa573a4df..f3ab6f3a9 100644 --- a/netbox/dcim/forms/models.py +++ b/netbox/dcim/forms/models.py @@ -1052,12 +1052,14 @@ class InterfaceTemplateForm(BootstrapMixin, forms.ModelForm): class Meta: model = InterfaceTemplate fields = [ - 'device_type', 'module_type', 'name', 'label', 'type', 'mgmt_only', 'description', + 'device_type', 'module_type', 'name', 'label', 'type', 'mgmt_only', 'description', 'poe_mode', 'poe_type', ] widgets = { 'device_type': forms.HiddenInput(), 'module_type': forms.HiddenInput(), 'type': StaticSelect(), + 'poe_mode': StaticSelect(), + 'poe_type': StaticSelect(), } diff --git a/netbox/dcim/forms/object_import.py b/netbox/dcim/forms/object_import.py index afbcd6543..a51f48c5b 100644 --- a/netbox/dcim/forms/object_import.py +++ b/netbox/dcim/forms/object_import.py @@ -1,6 +1,6 @@ from django import forms -from dcim.choices import InterfaceTypeChoices, PortTypeChoices +from dcim.choices import InterfacePoEModeChoices, InterfacePoETypeChoices, InterfaceTypeChoices, PortTypeChoices from dcim.models import * from utilities.forms import BootstrapMixin @@ -112,11 +112,21 @@ class InterfaceTemplateImportForm(ComponentTemplateImportForm): type = forms.ChoiceField( choices=InterfaceTypeChoices.CHOICES ) + poe_mode = forms.ChoiceField( + choices=InterfacePoEModeChoices, + required=False, + label='PoE mode' + ) + poe_type = forms.ChoiceField( + choices=InterfacePoETypeChoices, + required=False, + label='PoE type' + ) class Meta: model = InterfaceTemplate fields = [ - 'device_type', 'module_type', 'name', 'label', 'type', 'mgmt_only', 'description', + 'device_type', 'module_type', 'name', 'label', 'type', 'mgmt_only', 'description', 'poe_mode', 'poe_type', ] diff --git a/netbox/dcim/graphql/types.py b/netbox/dcim/graphql/types.py index a43b293a4..52a98278a 100644 --- a/netbox/dcim/graphql/types.py +++ b/netbox/dcim/graphql/types.py @@ -258,6 +258,12 @@ class InterfaceTemplateType(ComponentTemplateObjectType): fields = '__all__' filterset_class = filtersets.InterfaceTemplateFilterSet + def resolve_poe_mode(self, info): + return self.poe_mode or None + + def resolve_poe_type(self, info): + return self.poe_type or None + class InventoryItemType(ComponentObjectType): diff --git a/netbox/dcim/migrations/0155_interface_poe_mode_type.py b/netbox/dcim/migrations/0155_interface_poe_mode_type.py index 0615d5d7e..13f2ddfc0 100644 --- a/netbox/dcim/migrations/0155_interface_poe_mode_type.py +++ b/netbox/dcim/migrations/0155_interface_poe_mode_type.py @@ -20,4 +20,14 @@ class Migration(migrations.Migration): name='poe_type', field=models.CharField(blank=True, max_length=50), ), + migrations.AddField( + model_name='interfacetemplate', + name='poe_mode', + field=models.CharField(blank=True, max_length=50), + ), + migrations.AddField( + model_name='interfacetemplate', + name='poe_type', + field=models.CharField(blank=True, max_length=50), + ), ] diff --git a/netbox/dcim/models/device_component_templates.py b/netbox/dcim/models/device_component_templates.py index 92658d310..4a66bc457 100644 --- a/netbox/dcim/models/device_component_templates.py +++ b/netbox/dcim/models/device_component_templates.py @@ -1,6 +1,6 @@ from django.contrib.contenttypes.fields import GenericForeignKey from django.contrib.contenttypes.models import ContentType -from django.core.exceptions import ObjectDoesNotExist, ValidationError +from django.core.exceptions import ValidationError from django.core.validators import MaxValueValidator, MinValueValidator from django.db import models from mptt.models import MPTTModel, TreeForeignKey @@ -318,6 +318,18 @@ class InterfaceTemplate(ModularComponentTemplateModel): default=False, verbose_name='Management only' ) + poe_mode = models.CharField( + max_length=50, + choices=InterfacePoEModeChoices, + blank=True, + verbose_name='PoE mode' + ) + poe_type = models.CharField( + max_length=50, + choices=InterfacePoETypeChoices, + blank=True, + verbose_name='PoE type' + ) component_model = Interface @@ -334,6 +346,8 @@ class InterfaceTemplate(ModularComponentTemplateModel): label=self.resolve_label(kwargs.get('module')), type=self.type, mgmt_only=self.mgmt_only, + poe_mode=self.poe_mode, + poe_type=self.poe_type, **kwargs ) diff --git a/netbox/dcim/models/devices.py b/netbox/dcim/models/devices.py index 6075cb5a0..f8a28eb58 100644 --- a/netbox/dcim/models/devices.py +++ b/netbox/dcim/models/devices.py @@ -229,6 +229,8 @@ class DeviceType(NetBoxModel): 'mgmt_only': c.mgmt_only, 'label': c.label, 'description': c.description, + 'poe_mode': c.poe_mode, + 'poe_type': c.poe_type, } for c in self.interfacetemplates.all() ] diff --git a/netbox/dcim/tables/devicetypes.py b/netbox/dcim/tables/devicetypes.py index 2da9daee7..3ed4d8c08 100644 --- a/netbox/dcim/tables/devicetypes.py +++ b/netbox/dcim/tables/devicetypes.py @@ -172,7 +172,7 @@ class InterfaceTemplateTable(ComponentTemplateTable): class Meta(ComponentTemplateTable.Meta): model = InterfaceTemplate - fields = ('pk', 'name', 'label', 'mgmt_only', 'type', 'description', 'actions') + fields = ('pk', 'name', 'label', 'mgmt_only', 'type', 'description', 'poe_mode', 'poe_type', 'actions') empty_text = "None" diff --git a/netbox/dcim/tests/test_filtersets.py b/netbox/dcim/tests/test_filtersets.py index 21daa32c1..fbc0addb8 100644 --- a/netbox/dcim/tests/test_filtersets.py +++ b/netbox/dcim/tests/test_filtersets.py @@ -1089,8 +1089,8 @@ class InterfaceTemplateTestCase(TestCase, ChangeLoggedFilterSetTests): DeviceType.objects.bulk_create(device_types) InterfaceTemplate.objects.bulk_create(( - InterfaceTemplate(device_type=device_types[0], name='Interface 1', type=InterfaceTypeChoices.TYPE_1GE_FIXED, mgmt_only=True), - InterfaceTemplate(device_type=device_types[1], name='Interface 2', type=InterfaceTypeChoices.TYPE_1GE_GBIC, mgmt_only=False), + InterfaceTemplate(device_type=device_types[0], name='Interface 1', type=InterfaceTypeChoices.TYPE_1GE_FIXED, mgmt_only=True, poe_mode=InterfacePoEModeChoices.MODE_PD, poe_type=InterfacePoETypeChoices.TYPE_1_8023AF), + InterfaceTemplate(device_type=device_types[1], name='Interface 2', type=InterfaceTypeChoices.TYPE_1GE_GBIC, mgmt_only=False, poe_mode=InterfacePoEModeChoices.MODE_PSE, poe_type=InterfacePoETypeChoices.TYPE_2_8023AT), InterfaceTemplate(device_type=device_types[2], name='Interface 3', type=InterfaceTypeChoices.TYPE_1GE_SFP, mgmt_only=False), )) @@ -1113,6 +1113,14 @@ class InterfaceTemplateTestCase(TestCase, ChangeLoggedFilterSetTests): params = {'mgmt_only': 'false'} self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + def test_poe_mode(self): + params = {'poe_mode': [InterfacePoEModeChoices.MODE_PD, InterfacePoEModeChoices.MODE_PSE]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + + def test_poe_type(self): + params = {'poe_type': [InterfacePoETypeChoices.TYPE_1_8023AF, InterfacePoETypeChoices.TYPE_2_8023AT]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + class FrontPortTemplateTestCase(TestCase, ChangeLoggedFilterSetTests): queryset = FrontPortTemplate.objects.all() From 04fb0bd51c5a3fd0d13fddea155de311b0f4edd9 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 28 Jul 2022 15:41:10 -0400 Subject: [PATCH 188/245] Closes #9858: ChangeLoggedModelFilterSet cleanup --- netbox/netbox/filtersets.py | 23 +++++------------------ netbox/utilities/testing/filtersets.py | 4 ++-- 2 files changed, 7 insertions(+), 20 deletions(-) diff --git a/netbox/netbox/filtersets.py b/netbox/netbox/filtersets.py index f509afa5b..3a0434592 100644 --- a/netbox/netbox/filtersets.py +++ b/netbox/netbox/filtersets.py @@ -197,24 +197,11 @@ class BaseFilterSet(django_filters.FilterSet): class ChangeLoggedModelFilterSet(BaseFilterSet): - created = django_filters.DateTimeFilter() - created__gte = django_filters.DateTimeFilter( - field_name='created', - lookup_expr='gte' - ) - created__lte = django_filters.DateTimeFilter( - field_name='created', - lookup_expr='lte' - ) - last_updated = django_filters.DateTimeFilter() - last_updated__gte = django_filters.DateTimeFilter( - field_name='last_updated', - lookup_expr='gte' - ) - last_updated__lte = django_filters.DateTimeFilter( - field_name='last_updated', - lookup_expr='lte' - ) + """ + Base FilterSet for ChangeLoggedModel classes. + """ + created = filters.MultiValueDateTimeFilter() + last_updated = filters.MultiValueDateTimeFilter() class NetBoxModelFilterSet(ChangeLoggedModelFilterSet): diff --git a/netbox/utilities/testing/filtersets.py b/netbox/utilities/testing/filtersets.py index 9c90f5530..00f3d9745 100644 --- a/netbox/utilities/testing/filtersets.py +++ b/netbox/utilities/testing/filtersets.py @@ -25,11 +25,11 @@ class ChangeLoggedFilterSetTests(BaseFilterSetTests): def test_created(self): pk_list = self.queryset.values_list('pk', flat=True)[:2] self.queryset.filter(pk__in=pk_list).update(created=datetime(2021, 1, 1, 0, 0, 0, tzinfo=timezone.utc)) - params = {'created': '2021-01-01T00:00:00'} + params = {'created': ['2021-01-01T00:00:00']} self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) def test_last_updated(self): pk_list = self.queryset.values_list('pk', flat=True)[:2] self.queryset.filter(pk__in=pk_list).update(last_updated=datetime(2021, 1, 2, 0, 0, 0, tzinfo=timezone.utc)) - params = {'last_updated': '2021-01-02T00:00:00'} + params = {'last_updated': ['2021-01-02T00:00:00']} self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) From c582d7459f2bd5db72ba407b360bf381694b1767 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 10:06:26 -0400 Subject: [PATCH 189/245] Rearrange introductory content --- docs/index.md | 81 ++++++++++++++++++-------------------------- docs/introduction.md | 79 ++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 +- 3 files changed, 113 insertions(+), 49 deletions(-) create mode 100644 docs/introduction.md diff --git a/docs/index.md b/docs/index.md index 81c899387..a6bbcecff 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,63 +1,48 @@ ![NetBox](netbox_logo.svg "NetBox logo"){style="height: 100px; margin-bottom: 3em"} -# What is NetBox? +# The Premiere Network Source of Truth -NetBox is an infrastructure resource modeling (IRM) application designed to empower network automation. Initially conceived by the network engineering team at [DigitalOcean](https://www.digitalocean.com/), NetBox was developed specifically to address the needs of network and infrastructure engineers. NetBox is made available as open source under the Apache 2 license. It encompasses the following aspects of network management: +NetBox is the leading solution for modeling modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. -* **IP address management (IPAM)** - IP networks and addresses, VRFs, and VLANs -* **Equipment racks** - Organized by group and site -* **Devices** - Types of devices and where they are installed -* **Connections** - Network, console, and power connections among devices -* **Virtualization** - Virtual machines and clusters -* **Data circuits** - Long-haul communications circuits and providers +## Built for Networks -## What NetBox Is Not +Unlike general-purpose CMDBs, NetBox has curated a data model which caters specifically to the needs of network engineers and operators. It delivers a wide assortment of object types carefully crafted to best serve the needs of network engineers and operators. These cover all facets of network design, from IP address managements to cabling to overlays and more: -While NetBox strives to cover many areas of network management, the scope of its feature set is necessarily limited. This ensures that development focuses on core functionality and that scope creep is reasonably contained. To that end, it might help to provide some examples of functionality that NetBox **does not** provide: +* Hierarchical regions, site groups, sites, and locations +* Racks, devices, and device components +* Cables and wireless connections +* Power distribution +* Data circuits and providers +* Virtual machines and clusters +* IP prefixes, ranges, and addresses +* VRFs and route targets +* FHRP groups (VRRP, HSRP, etc.) +* AS numbers +* VLANs and scoped VLAN groups +* L2VPN overlays +* Organizational tenants and contacts -* Network monitoring -* DNS server -* RADIUS server -* Configuration management -* Facilities management +## Customizable & Extensible -That said, NetBox _can_ be used to great effect in populating external tools with the data they need to perform these functions. +In addition to its expansive and robust data model, NetBox offers myriad mechanisms through it can be customized and extended. -## Design Philosophy +* Custom fields +* Custom model validation +* Export templates +* Webhooks +* Plugins +* REST & GraphQL APIs -NetBox was designed with the following tenets foremost in mind. +## Always Open -### Replicate the Real World - -Careful consideration has been given to the data model to ensure that it can accurately reflect a real-world network. For instance, IP addresses are assigned not to devices, but to specific interfaces attached to a device, and an interface may have multiple IP addresses assigned to it. - -### Serve as a "Source of Truth" - -NetBox intends to represent the _desired_ state of a network versus its _operational_ state. As such, automated import of live network state is strongly discouraged. All data created in NetBox should first be vetted by a human to ensure its integrity. NetBox can then be used to populate monitoring and provisioning systems with a high degree of confidence. - -### Keep it Simple - -When given a choice between a relatively simple [80% solution](https://en.wikipedia.org/wiki/Pareto_principle) and a much more complex complete solution, the former will typically be favored. This ensures a lean codebase with a low learning curve. - -## Application Stack - -NetBox is built on the [Django](https://djangoproject.com/) Python framework and utilizes a [PostgreSQL](https://www.postgresql.org/) database. It runs as a WSGI service behind your choice of HTTP server. - -| Function | Component | -|--------------------|-------------------| -| HTTP service | nginx or Apache | -| WSGI service | gunicorn or uWSGI | -| Application | Django/Python | -| Database | PostgreSQL 10+ | -| Task queuing | Redis/django-rq | -| Live device access | NAPALM (optional) | - -## Supported Python Versions - -NetBox supports Python 3.8, 3.9, and 3.10 environments. +Because NetBox is an open source application licensed under [Apache 2](https://www.apache.org/licenses/LICENSE-2.0.html), its entire code base is completely accessible to the end user, and there's never a risk of vendor lock-out. Additionally, NetBox development is an entirely public, community-driven process to which everyone can provide input. ## Getting Started -Minor NetBox releases (e.g. v3.1) are published three times a year; in April, August, and December. These typically introduce major new features and may contain breaking API changes. Patch releases are published roughly every one to two weeks to resolve bugs and fulfill minor feature requests. These are backward-compatible with previous releases unless otherwise noted. The NetBox maintainers strongly recommend running the latest stable release whenever possible. +* Public Demo +* Installation Guide +* Docker install +* NetBox Cloud -Please see the [official installation guide](installation/index.md) for detailed instructions on obtaining and installing NetBox. +!!! tip "NetBox Development" + Interested in contributing to NetBox? Check out our [GitHub repository](https://github.com/netbox-community/netbox) to get started! diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 000000000..cffcb37dd --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,79 @@ +# Introduction to NetBox + +## Origin Story + +NetBox was originally developed by its lead maintainer, [Jeremy Stretch](https://github.com/jeremystretch), while he was working as a network engineer at [DigitalOcean](https://www.digitalocean.com/) in 2015 as part of an effort to automate their network provisioning. Recognizing the new tool's potential, DigitalOcean agreed to release it as an open source project in June 2016. + +Since then, thousands of organizations around the world have embraced NetBox as their central network source of truth to empower both network operators and automation. + +## Key Features + +NetBox was built specifically to serve the needs of network engineers and operators. Below is a very brief overview of the core features it provides. + +* IP address management (IPAM) with full IPv4/IPv6 parity +* Automatic provisioning of next available prefix/IP +* VRFs with import & export route targets +* VLANs with variably-scoped groups +* AS number (ASN) management +* Rack elevations with SVG rendering +* Device modeling using pre-defined types +* Network, power, and console cabling with SVG traces +* Power distribution modeling +* Data circuit and provider tracking +* Wireless LAN and point-to-point links +* L2 VPN overlays +* FHRP groups (VRRP, HSRP, etc.) +* Application service bindings +* Virtual machines & clusters +* Flexible hierarchy for sites and locations +* Tenant ownership assignment +* Device & VM configuration contexts for advanced configuration rendering +* Custom fields for data model extension +* Support for custom validation rules +* Custom reports & scripts executable directly within the UI +* Extensive plugin framework for adding custom functionality +* Single sign-on (SSO) authentication +* Robust object-based permissions +* Detailed, automatic change logging +* NAPALM integration + +## What NetBox Is Not + +While NetBox strives to cover many areas of network management, the scope of its feature set is necessarily limited. This ensures that development focuses on core functionality and that scope creep is reasonably contained. To that end, it might help to provide some examples of functionality that NetBox **does not** provide: + +* Network monitoring +* DNS server +* RADIUS server +* Configuration management +* Facilities management + +That said, NetBox _can_ be used to great effect in populating external tools with the data they need to perform these functions. + +## Design Philosophy + +NetBox was designed with the following tenets foremost in mind. + +### Replicate the Real World + +Careful consideration has been given to the data model to ensure that it can accurately reflect a real-world network. For instance, IP addresses are assigned not to devices, but to specific interfaces attached to a device, and an interface may have multiple IP addresses assigned to it. + +### Serve as a "Source of Truth" + +NetBox intends to represent the _desired_ state of a network versus its _operational_ state. As such, automated import of live network state is strongly discouraged. All data created in NetBox should first be vetted by a human to ensure its integrity. NetBox can then be used to populate monitoring and provisioning systems with a high degree of confidence. + +### Keep it Simple + +When given a choice between a relatively simple [80% solution](https://en.wikipedia.org/wiki/Pareto_principle) and a much more complex complete solution, the former will typically be favored. This ensures a lean codebase with a low learning curve. + +## Application Stack + +NetBox is built on the [Django](https://djangoproject.com/) Python framework and utilizes a [PostgreSQL](https://www.postgresql.org/) database. It runs as a WSGI service behind your choice of HTTP server. + +| Function | Component | +|--------------------|-------------------| +| HTTP service | nginx or Apache | +| WSGI service | gunicorn or uWSGI | +| Application | Django/Python | +| Database | PostgreSQL 10+ | +| Task queuing | Redis/django-rq | +| Live device access | NAPALM (optional) | diff --git a/mkdocs.yml b/mkdocs.yml index 34c65ed01..992859d66 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,7 +57,7 @@ markdown_extensions: - pymdownx.tabbed: alternate_style: true nav: - - Introduction: 'index.md' + - Introduction: 'introduction.md' - Installation: - Installing NetBox: 'installation/index.md' - 1. PostgreSQL: 'installation/1-postgresql.md' From 18acac18e0301ad0e3355f9742177062aad403c3 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 10:30:47 -0400 Subject: [PATCH 190/245] Move data model definitions to separate hierarchy --- docs/core-functionality/circuits.md | 10 -- docs/core-functionality/contacts.md | 5 - docs/core-functionality/device-types.md | 41 --------- docs/core-functionality/devices.md | 40 -------- docs/core-functionality/ipam.md | 33 ------- docs/core-functionality/modules.md | 4 - docs/core-functionality/power.md | 8 -- docs/core-functionality/services.md | 4 - docs/core-functionality/sites-and-racks.md | 12 --- docs/core-functionality/tenancy.md | 4 - docs/core-functionality/virtualization.md | 10 -- docs/core-functionality/vlans.md | 4 - docs/core-functionality/wireless.md | 8 -- docs/installation/migrating-to-systemd.md | 55 ----------- mkdocs.yml | 101 +++++++++++++++++---- 15 files changed, 85 insertions(+), 254 deletions(-) delete mode 100644 docs/core-functionality/circuits.md delete mode 100644 docs/core-functionality/contacts.md delete mode 100644 docs/core-functionality/device-types.md delete mode 100644 docs/core-functionality/devices.md delete mode 100644 docs/core-functionality/ipam.md delete mode 100644 docs/core-functionality/modules.md delete mode 100644 docs/core-functionality/power.md delete mode 100644 docs/core-functionality/services.md delete mode 100644 docs/core-functionality/sites-and-racks.md delete mode 100644 docs/core-functionality/tenancy.md delete mode 100644 docs/core-functionality/virtualization.md delete mode 100644 docs/core-functionality/vlans.md delete mode 100644 docs/core-functionality/wireless.md delete mode 100644 docs/installation/migrating-to-systemd.md diff --git a/docs/core-functionality/circuits.md b/docs/core-functionality/circuits.md deleted file mode 100644 index b1b02e300..000000000 --- a/docs/core-functionality/circuits.md +++ /dev/null @@ -1,10 +0,0 @@ -# Circuits - -{!models/circuits/provider.md!} -{!models/circuits/providernetwork.md!} - ---- - -{!models/circuits/circuit.md!} -{!models/circuits/circuittype.md!} -{!models/circuits/circuittermination.md!} diff --git a/docs/core-functionality/contacts.md b/docs/core-functionality/contacts.md deleted file mode 100644 index 76a005fc0..000000000 --- a/docs/core-functionality/contacts.md +++ /dev/null @@ -1,5 +0,0 @@ -# Contacts - -{!models/tenancy/contact.md!} -{!models/tenancy/contactgroup.md!} -{!models/tenancy/contactrole.md!} diff --git a/docs/core-functionality/device-types.md b/docs/core-functionality/device-types.md deleted file mode 100644 index ec5cbacdb..000000000 --- a/docs/core-functionality/device-types.md +++ /dev/null @@ -1,41 +0,0 @@ -# Device Types - -{!models/dcim/devicetype.md!} -{!models/dcim/manufacturer.md!} - ---- - -## Device Component Templates - -Each device type is assigned a number of component templates which define the physical components within a device. These are: - -* Console ports -* Console server ports -* Power ports -* Power outlets -* Network interfaces -* Front ports -* Rear ports -* Device bays (which house child devices) - -Whenever a new device is created, its components are automatically created per the templates assigned to its device type. For example, a Juniper EX4300-48T device type might have the following component templates defined: - -* One template for a console port ("Console") -* Two templates for power ports ("PSU0" and "PSU1") -* 48 templates for 1GE interfaces ("ge-0/0/0" through "ge-0/0/47") -* Four templates for 10GE interfaces ("xe-0/2/0" through "xe-0/2/3") - -Once component templates have been created, every new device that you create as an instance of this type will automatically be assigned each of the components listed above. - -!!! note - Assignment of components from templates occurs only at the time of device creation. If you modify the templates of a device type, it will not affect devices which have already been created. However, you always have the option of adding, modifying, or deleting components on existing devices. - -{!models/dcim/consoleporttemplate.md!} -{!models/dcim/consoleserverporttemplate.md!} -{!models/dcim/powerporttemplate.md!} -{!models/dcim/poweroutlettemplate.md!} -{!models/dcim/interfacetemplate.md!} -{!models/dcim/frontporttemplate.md!} -{!models/dcim/rearporttemplate.md!} -{!models/dcim/modulebaytemplate.md!} -{!models/dcim/devicebaytemplate.md!} diff --git a/docs/core-functionality/devices.md b/docs/core-functionality/devices.md deleted file mode 100644 index 35c978210..000000000 --- a/docs/core-functionality/devices.md +++ /dev/null @@ -1,40 +0,0 @@ -# Devices and Cabling - -{!models/dcim/device.md!} -{!models/dcim/devicerole.md!} -{!models/dcim/platform.md!} - ---- - -## Device Components - -Device components represent discrete objects within a device which are used to terminate cables, house child devices, or track resources. - -{!models/dcim/consoleport.md!} -{!models/dcim/consoleserverport.md!} -{!models/dcim/powerport.md!} -{!models/dcim/poweroutlet.md!} -{!models/dcim/interface.md!} -{!models/dcim/frontport.md!} -{!models/dcim/rearport.md!} -{!models/dcim/modulebay.md!} -{!models/dcim/devicebay.md!} -{!models/dcim/inventoryitem.md!} - ---- - -{!models/dcim/virtualchassis.md!} - ---- - -{!models/dcim/cable.md!} - -In the example below, three individual cables comprise a path between devices A and D: - -![Cable path](../media/models/dcim_cable_trace.png) - -Traced from Interface 1 on Device A, NetBox will show the following path: - -* Cable 1: Interface 1 to Front Port 1 -* Cable 2: Rear Port 1 to Rear Port 2 -* Cable 3: Front Port 2 to Interface 2 diff --git a/docs/core-functionality/ipam.md b/docs/core-functionality/ipam.md deleted file mode 100644 index c86819380..000000000 --- a/docs/core-functionality/ipam.md +++ /dev/null @@ -1,33 +0,0 @@ -# IP Address Management - -{!models/ipam/aggregate.md!} -{!models/ipam/rir.md!} - ---- - -{!models/ipam/prefix.md!} -{!models/ipam/role.md!} - ---- - -{!models/ipam/iprange.md!} -{!models/ipam/ipaddress.md!} - ---- - -{!models/ipam/vrf.md!} -{!models/ipam/routetarget.md!} - ---- - -{!models/ipam/fhrpgroup.md!} -{!models/ipam/fhrpgroupassignment.md!} - ---- - -{!models/ipam/asn.md!} - ---- - -{!models/ipam/l2vpn.md!} -{!models/ipam/l2vpntermination.md!} diff --git a/docs/core-functionality/modules.md b/docs/core-functionality/modules.md deleted file mode 100644 index 4d32fe18c..000000000 --- a/docs/core-functionality/modules.md +++ /dev/null @@ -1,4 +0,0 @@ -# Modules - -{!models/dcim/moduletype.md!} -{!models/dcim/module.md!} diff --git a/docs/core-functionality/power.md b/docs/core-functionality/power.md deleted file mode 100644 index 4d7d5f0ab..000000000 --- a/docs/core-functionality/power.md +++ /dev/null @@ -1,8 +0,0 @@ -# Power Tracking - -{!models/dcim/powerpanel.md!} -{!models/dcim/powerfeed.md!} - -# Example Power Topology - -![Power distribution model](../media/power_distribution.png) diff --git a/docs/core-functionality/services.md b/docs/core-functionality/services.md deleted file mode 100644 index 316c7fe00..000000000 --- a/docs/core-functionality/services.md +++ /dev/null @@ -1,4 +0,0 @@ -# Service Mapping - -{!models/ipam/servicetemplate.md!} -{!models/ipam/service.md!} diff --git a/docs/core-functionality/sites-and-racks.md b/docs/core-functionality/sites-and-racks.md deleted file mode 100644 index c78f2120a..000000000 --- a/docs/core-functionality/sites-and-racks.md +++ /dev/null @@ -1,12 +0,0 @@ -# Sites and Racks - -{!models/dcim/region.md!} -{!models/dcim/sitegroup.md!} -{!models/dcim/site.md!} -{!models/dcim/location.md!} - ---- - -{!models/dcim/rack.md!} -{!models/dcim/rackrole.md!} -{!models/dcim/rackreservation.md!} diff --git a/docs/core-functionality/tenancy.md b/docs/core-functionality/tenancy.md deleted file mode 100644 index fbe1ea8b9..000000000 --- a/docs/core-functionality/tenancy.md +++ /dev/null @@ -1,4 +0,0 @@ -# Tenancy Assignment - -{!models/tenancy/tenant.md!} -{!models/tenancy/tenantgroup.md!} diff --git a/docs/core-functionality/virtualization.md b/docs/core-functionality/virtualization.md deleted file mode 100644 index 220030ab2..000000000 --- a/docs/core-functionality/virtualization.md +++ /dev/null @@ -1,10 +0,0 @@ -# Virtualization - -{!models/virtualization/cluster.md!} -{!models/virtualization/clustertype.md!} -{!models/virtualization/clustergroup.md!} - ---- - -{!models/virtualization/virtualmachine.md!} -{!models/virtualization/vminterface.md!} diff --git a/docs/core-functionality/vlans.md b/docs/core-functionality/vlans.md deleted file mode 100644 index d69128765..000000000 --- a/docs/core-functionality/vlans.md +++ /dev/null @@ -1,4 +0,0 @@ -# VLAN Management - -{!models/ipam/vlan.md!} -{!models/ipam/vlangroup.md!} diff --git a/docs/core-functionality/wireless.md b/docs/core-functionality/wireless.md deleted file mode 100644 index 57133f756..000000000 --- a/docs/core-functionality/wireless.md +++ /dev/null @@ -1,8 +0,0 @@ -# Wireless Networks - -{!models/wireless/wirelesslan.md!} -{!models/wireless/wirelesslangroup.md!} - ---- - -{!models/wireless/wirelesslink.md!} diff --git a/docs/installation/migrating-to-systemd.md b/docs/installation/migrating-to-systemd.md deleted file mode 100644 index a71b748fd..000000000 --- a/docs/installation/migrating-to-systemd.md +++ /dev/null @@ -1,55 +0,0 @@ -# Migrating to systemd - -This document contains instructions for migrating from a legacy NetBox deployment using [supervisor](http://supervisord.org/) to a systemd-based approach. - -## Ubuntu - -### Uninstall supervisord - -```no-highlight -# apt-get remove -y supervisor -``` - -### Configure systemd - -!!! note - These instructions assume the presence of a Python virtual environment at `/opt/netbox/venv`. If you have not created this environment, please refer to the [installation instructions](3-netbox.md#set-up-python-environment) for direction. - -We'll use systemd to control the daemonization of NetBox services. First, copy `contrib/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory: - -```no-highlight -# cp contrib/*.service /etc/systemd/system/ -``` - -!!! note - You may need to modify the user that the systemd service runs as. Please verify the user for httpd on your specific release and edit both files to match your httpd service under user and group. The username could be "nobody", "nginx", "apache", "www-data", or something else. - -Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time: - -```no-highlight -# systemctl daemon-reload -# systemctl start netbox netbox-rq -# systemctl enable netbox netbox-rq -``` - -You can use the command `systemctl status netbox` to verify that the WSGI service is running: - -``` -# systemctl status netbox.service -● netbox.service - NetBox WSGI Service - Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled) - Active: active (running) since Sat 2020-10-24 19:23:40 UTC; 25s ago - Docs: https://docs.netbox.dev/ - Main PID: 11993 (gunicorn) - Tasks: 6 (limit: 2362) - CGroup: /system.slice/netbox.service - ├─11993 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... - ├─12015 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... - ├─12016 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... -... -``` - -At this point, you should be able to connect to the HTTP service at the server name or IP address you provided. If you are unable to connect, check that the nginx service is running and properly configured. If you receive a 502 (bad gateway) error, this indicates that gunicorn is misconfigured or not running. Issue the command `journalctl -xe` to see why the services were unable to start. - -!!! info - Please keep in mind that the configurations provided here are bare minimums required to get NetBox up and running. You may want to make adjustments to better suit your production environment. diff --git a/mkdocs.yml b/mkdocs.yml index 992859d66..6471783e0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,7 +58,7 @@ markdown_extensions: alternate_style: true nav: - Introduction: 'introduction.md' - - Installation: + - Installation & Upgrade: - Installing NetBox: 'installation/index.md' - 1. PostgreSQL: 'installation/1-postgresql.md' - 2. Redis: 'installation/2-redis.md' @@ -67,7 +67,6 @@ nav: - 5. HTTP Server: 'installation/5-http-server.md' - 6. LDAP (Optional): 'installation/6-ldap.md' - Upgrading NetBox: 'installation/upgrading.md' - - Migrating to systemd: 'installation/migrating-to-systemd.md' - Configuration: - Configuring NetBox: 'configuration/index.md' - Required Settings: 'configuration/required-settings.md' @@ -75,20 +74,6 @@ nav: - Dynamic Settings: 'configuration/dynamic-settings.md' - Error Reporting: 'configuration/error-reporting.md' - Remote Authentication: 'configuration/remote-authentication.md' - - Core Functionality: - - IP Address Management: 'core-functionality/ipam.md' - - VLAN Management: 'core-functionality/vlans.md' - - Sites and Racks: 'core-functionality/sites-and-racks.md' - - Devices and Cabling: 'core-functionality/devices.md' - - Device Types: 'core-functionality/device-types.md' - - Modules: 'core-functionality/modules.md' - - Virtualization: 'core-functionality/virtualization.md' - - Service Mapping: 'core-functionality/services.md' - - Circuits: 'core-functionality/circuits.md' - - Wireless: 'core-functionality/wireless.md' - - Power Tracking: 'core-functionality/power.md' - - Tenancy: 'core-functionality/tenancy.md' - - Contacts: 'core-functionality/contacts.md' - Customization: - Custom Fields: 'customization/custom-fields.md' - Custom Validation: 'customization/custom-validation.md' @@ -135,6 +120,90 @@ nav: - Authentication: 'rest-api/authentication.md' - GraphQL API: - Overview: 'graphql-api/overview.md' + - Data Model: + - Circuits: + - Circuit: 'models/circuits/circuit.md' + - Circuit Termination: 'models/circuits/circuittermination.md' + - Circuit Type: 'models/circuits/circuittype.md' + - Provider: 'models/circuits/provider.md' + - Provider Network: 'models/circuits/providernetwork.md' + - DCIM: + - Cable: 'models/dcim/cable.md' + - CablePath: 'models/dcim/cablepath.md' + - CableTermination: 'models/dcim/cabletermination.md' + - ConsolePort: 'models/dcim/consoleport.md' + - ConsolePortTemplate: 'models/dcim/consoleporttemplate.md' + - ConsoleServerPort: 'models/dcim/consoleserverport.md' + - ConsoleServerPortTemplate: 'models/dcim/consoleserverporttemplate.md' + - Device: 'models/dcim/device.md' + - DeviceBay: 'models/dcim/devicebay.md' + - DeviceBayTemplate: 'models/dcim/devicebaytemplate.md' + - DeviceRole: 'models/dcim/devicerole.md' + - DeviceType: 'models/dcim/devicetype.md' + - FrontPort: 'models/dcim/frontport.md' + - FrontPortTemplate: 'models/dcim/frontporttemplate.md' + - Interface: 'models/dcim/interface.md' + - InterfaceTemplate: 'models/dcim/interfacetemplate.md' + - InventoryItem: 'models/dcim/inventoryitem.md' + - InventoryItemRole: 'models/dcim/inventoryitemrole.md' + - InventoryItemTemplate: 'models/dcim/inventoryitemtemplate.md' + - Location: 'models/dcim/location.md' + - Manufacturer: 'models/dcim/manufacturer.md' + - Module: 'models/dcim/module.md' + - ModuleBay: 'models/dcim/modulebay.md' + - ModuleBayTemplate: 'models/dcim/modulebaytemplate.md' + - ModuleType: 'models/dcim/moduletype.md' + - Platform: 'models/dcim/platform.md' + - PowerFeed: 'models/dcim/powerfeed.md' + - PowerOutlet: 'models/dcim/poweroutlet.md' + - PowerOutletTemplate: 'models/dcim/poweroutlettemplate.md' + - PowerPanel: 'models/dcim/powerpanel.md' + - PowerPort: 'models/dcim/powerport.md' + - PowerPortTemplate: 'models/dcim/powerporttemplate.md' + - Rack: 'models/dcim/rack.md' + - RackReservation: 'models/dcim/rackreservation.md' + - RackRole: 'models/dcim/rackrole.md' + - RearPort: 'models/dcim/rearport.md' + - RearPortTemplate: 'models/dcim/rearporttemplate.md' + - Region: 'models/dcim/region.md' + - Site: 'models/dcim/site.md' + - SiteGroup: 'models/dcim/sitegroup.md' + - VirtualChassis: 'models/dcim/virtualchassis.md' + - IPAM: + - ASN: 'models/ipam/asn.md' + - Aggregate: 'models/ipam/aggregate.md' + - FHRPGroup: 'models/ipam/fhrpgroup.md' + - FHRPGroupAssignment: 'models/ipam/fhrpgroupassignment.md' + - IPAddress: 'models/ipam/ipaddress.md' + - IPRange: 'models/ipam/iprange.md' + - L2VPN: 'models/ipam/l2vpn.md' + - L2VPNTermination: 'models/ipam/l2vpntermination.md' + - Prefix: 'models/ipam/prefix.md' + - RIR: 'models/ipam/rir.md' + - Role: 'models/ipam/role.md' + - RouteTarget: 'models/ipam/routetarget.md' + - Service: 'models/ipam/service.md' + - ServiceTemplate: 'models/ipam/servicetemplate.md' + - VLAN: 'models/ipam/vlan.md' + - VLANGroup: 'models/ipam/vlangroup.md' + - VRF: 'models/ipam/vrf.md' + - Tenancy: + - Contact: 'models/tenancy/contact.md' + - ContactAssignment: 'models/tenancy/contactassignment.md' + - ContactGroup: 'models/tenancy/contactgroup.md' + - ContactRole: 'models/tenancy/contactrole.md' + - Tenant: 'models/tenancy/tenant.md' + - TenantGroup: 'models/tenancy/tenantgroup.md' + - Virtualization: + - Cluster: 'models/virtualization/cluster.md' + - ClusterGroup: 'models/virtualization/clustergroup.md' + - ClusterType: 'models/virtualization/clustertype.md' + - VMInterface: 'models/virtualization/vminterface.md' + - VirtualMachine: 'models/virtualization/virtualmachine.md' + - Wireless: + - WirelessLAN: 'models/wireless/wirelesslan.md' + - WirelessLANGroup: 'models/wireless/wirelesslangroup.md' + - WirelessLink: 'models/wireless/wirelesslink.md' - Reference: - Conditions: 'reference/conditions.md' - Markdown: 'reference/markdown.md' From b1ce8bd222a7b39bcacbe1d66ce5ab69f11dfe8e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 13:45:59 -0400 Subject: [PATCH 191/245] Started "getting started" guide --- docs/getting-started/planning.md | 87 +++++++++++++++++++++++++ docs/getting-started/populating-data.md | 42 ++++++++++++ mkdocs.yml | 3 + 3 files changed, 132 insertions(+) create mode 100644 docs/getting-started/planning.md create mode 100644 docs/getting-started/populating-data.md diff --git a/docs/getting-started/planning.md b/docs/getting-started/planning.md new file mode 100644 index 000000000..00640ca44 --- /dev/null +++ b/docs/getting-started/planning.md @@ -0,0 +1,87 @@ +# Planning Your Move + +This guide outlines the steps necessary for planning a successful migration to NetBox. Although it is written under the context of a completely new installation, the general approach outlined here works just as well for adding new data to existing NetBox deployments. + +## Identify Current Sources of Truth + +Before beginning to use NetBox for your own data, it's crucial to first understand where your existing sources of truth reside. A "source of truth" is really just any repository of data that is authoritative for a given domain. For example, you may have a spreadsheet which tracks all IP prefixes in use on your network. So long as everyone involved agrees that this spreadsheet is _authoritative_ for the entire network, it is your source of truth for IP prefixes. + +Anything can be a source of truth, provided it meets two conditions: + +1. It is agreed upon by all relevant parties that this source of data is correct. +2. The domain to which it applies is well-defined. + + + +Dedicate some time to take stock of your own sources of truth for your infrastructure. Upon attempting to catalog these, you're very likely to encounter some challenges, such as: + +* **Multiple conflicting sources** for a given domain. For example, there may be multiple versions of a spreadsheet circulating, each of which asserts a conflicting set of data. +* **Sources with no domain defined.** You may encounter that different teams within your organization use different tools for the same purpose, with no normal definition of when either should be used. +* **Inaccessible data formatting.** Some tools are better suited for programmatic usage than others. For example, spreadsheets are generally very easy to parse and export, however free-form notes on wiki or similar application are much more difficult to consume. +* **There is no source of truth.** Sometimes you'll find that a source of truth simply doesn't exist for a domain. For example, when assigning IP addresses, operators may be just using any (presumed) available IP from a subnet without ever recording its usage. + +See if you can identify each domain of infrastructure data for your organization, and the source of truth for each. Once you have these compiled, you'll need to determine what belongs in NetBox. + +## Determine What to Move + +The general rule when determining what data to put into NetBox is this: If there's a model for it, it belongs in NetBox. For instance, NetBox has purpose-built models for racks, devices, cables, IP prefixes, VLANs, and so on. These are very straightforward to use. However, you'll inevitably reach the limits of NetBox's data model and question what additional data might make sense to record in NetBox. For example, you might wonder whether NetBox should function as the source of truth for infrastructure DNS records or DHCP scopes. + +NetBox provides two core mechanisms for extending its data model. The first is custom fields: Most models in NetBox support the addition of custom fields to hold additional data for which a built-in field does not exist. For example, you might wish to add an "inventory ID" field to the device model. The second mechanism is plugins. Users can create their own plugins to introduce entirely new models, views, and API endpoints in NetBox. This can be incredibly powerful, as it enables rapid development and tight integration with core models. + +That said, it doesn't always make sense to migrate a domain of data to NetBox. For example, many organizations opt to use only the IPAM components or only the DCIM components of NetBox, and integrate with other sources of truth for different domains. This is an entirely valid approach (so long as everyone involved agrees which tool is authoritative for each domain). Ultimately, you'll need to weigh the value of having non-native data models in NetBox against the effort required to define and maintain those models. + +Consider also that NetBox is under constant development. Although the current release might not support a particular type of object, there may be plans to add support for it in a future release. (And if there aren't, consider submitting a feature request citing your use case.) + +## Validate Existing Data + +The last step before migrating data to NetBox is the most crucial: **validation**. The GIGO (garbage in, garbage out) principle is in full effect: Your source of truth is only as good as the data it holds. While NetBox has very powerful data validation tools (including support for custom validation rules), ultimately the onus falls to a human operator to assert what is correct and what is not. For example, NetBox can validate the connection of a cable between two interfaces, but it cannot say whether the cable _should_ be there. + +Here are some tips to help ensure you're only importing valid data into NetBox: + +* Ensure you're starting with complete, well-formatted data. JSON or CSV is highly recommended for the best portability. +* Consider defining custom validation rules in NetBox prior to import. (For example, to enforce device naming schemes.) +* Use custom scripts to automatically populate patterned data. (For example, to automatically create a set of standard VLANs for each site.) + +There are several methods available to import data into NetBox, which we'll cover in the next section. + +## Order of Operations + +When starting with a completely empty database, it might not be immediately clear where to begin. Many models in NetBox rely on the advance creation of other types. For example, you cannot create a device type until after you have created its manufacturer. + +Below is the (rough) recommended order in which NetBox objects should be created or imported. While it is not required to follow this exact order, doing so will help ensure the smoothest workflow. + + + +1. Tenant groups +2. Tenants +3. Regions and/or site groups +4. Sites +5. Locations +6. Rack roles +7. Racks +8. Platforms +9. Manufacturers +10. Device types +11. Module types +12. Device roles +13. Devices +14. Providers +15. Provider networks +16. Circuit types +17. Circuits +18. Wireless LAN groups +19. Wireless LANs & links +20. Route targets +21. VRFs +22. RIRs +23. Aggregates +24. IP/VLAN roles +25. Prefixes +26. IP ranges & addresses +27. VLAN groups +28. VLANs +29. Services +30. Clusters +31. Virtual machines +32. VM interfaces +33. L2 VPNs diff --git a/docs/getting-started/populating-data.md b/docs/getting-started/populating-data.md new file mode 100644 index 000000000..e182a9d52 --- /dev/null +++ b/docs/getting-started/populating-data.md @@ -0,0 +1,42 @@ +# Populating Data + +This section covers the mechanisms which are available to populate data in NetBox. + +## Manual Object Creation + +The simplest and most direct way of populating data in NetBox is to use the object creation forms in the user interface. + +!!! warning "Not Ideal for Large Imports" + While convenient and readily accessible to even novice users, creating objects one at a time by manually completing these forms obviously does not scale well. For large imports, you're generally best served by using one of the other methods discussed in this section. + +To create a new object in NetBox, find the object type in the navigation menu and click the green "Add" button. + +!!! info "Missing Button?" + If you don't see an "add" button for certain object types, it's likely that your account does not have sufficient permission to create these types. Ask your NetBox administrator to grant the required permissions. + + Also note that some object types, such as device components, cannot be created directly from the navigation menu. These must be created within the context of a parent object (such as a parent device). + + + +## Bulk Import (CSV/YAML) + +NetBox supports the bulk import of new objects using CSV-formatted data. This method can be ideal for importing spreadsheet data, which is very easy to convert to CSV data. CSV data can be imported either as raw text using the form field, or by uploading a properly formatted CSV file. + +When viewing the CSV import form for an object type, you'll notice that the headers for the required columns have been pre-populated. Each form has a table beneath it titled "CSV Field Options," which lists _all_ supported columns for your reference. (Generally, these map to the fields you see in the corresponding creation form for individual objects.) + + + +Note that some models (namely device types and module types) do not support CSV import. Instead, they accept YAML-formatted data to facilitate the import of both the parent object as well as child components. + +## Scripting + +Sometimes you'll find that data you need to populate in NetBox can be easily reduced to a pattern. For example, suppose you have one hundred branch sites and each site gets five VLANs, numbered 101 through 105. While it's certainly possible to explicitly define each of these 500 VLANs in a CSV file for import, it may be quicker to draft a simple custom script to automatically create these VLANs according to the pattern. This ensures a high degree of confidence in the validity of the data, since it's impossible for a script to "miss" a VLAN here or there. + +!!! tip "Reconstruct Existing Data with Scripts" + Sometimes, you might want to write a script to populate objects even if you have the necessary data ready for import. This is because using a script eliminates the need to manually verify existing data prior to import. + +## REST API + +You can also use the REST API to facilitate the population of data in NetBox. The REST API offers full programmatic control over the creation of objects, subject to the same validation rules enforced by the UI forms. Additionally, the REST API supports the bulk creation of multiple objects using a single request. + +For more information about this option, see the [REST API documentation](../rest-api/overview.md). diff --git a/mkdocs.yml b/mkdocs.yml index 6471783e0..2203b8934 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,6 +67,9 @@ nav: - 5. HTTP Server: 'installation/5-http-server.md' - 6. LDAP (Optional): 'installation/6-ldap.md' - Upgrading NetBox: 'installation/upgrading.md' + - Getting Started: + - Planning: 'getting-started/planning.md' + - Populating Data: 'getting-started/populating-data.md' - Configuration: - Configuring NetBox: 'configuration/index.md' - Required Settings: 'configuration/required-settings.md' From a6c431f3ba236760ab753f92b8b7aec16c07c568 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 15:10:50 -0400 Subject: [PATCH 192/245] Reorganize configuration docs --- docs/additional-features/napalm.md | 2 +- docs/administration/housekeeping.md | 4 +- docs/configuration/data-validation.md | 86 +++ docs/configuration/date-time.md | 20 + docs/configuration/default-values.md | 77 +++ docs/configuration/development.md | 21 + docs/configuration/dynamic-settings.md | 232 --------- docs/configuration/index.md | 44 +- docs/configuration/miscellaneous.md | 159 ++++++ docs/configuration/napalm.md | 51 ++ docs/configuration/optional-settings.md | 489 ------------------ docs/configuration/plugins.md | 35 ++ docs/configuration/remote-authentication.md | 32 +- ...red-settings.md => required-parameters.md} | 0 docs/configuration/security.md | 144 ++++++ docs/configuration/system.md | 178 +++++++ docs/customization/custom-validation.md | 2 +- docs/customization/export-templates.md | 2 +- docs/customization/reports.md | 2 +- docs/graphql-api/overview.md | 2 +- docs/installation/3-netbox.md | 6 +- docs/installation/6-ldap.md | 2 +- docs/plugins/development/models.md | 2 +- docs/release-notes/version-3.0.md | 2 +- docs/release-notes/version-3.1.md | 2 - docs/release-notes/version-3.2.md | 4 +- docs/rest-api/authentication.md | 2 +- docs/rest-api/overview.md | 4 +- mkdocs.yml | 15 +- 29 files changed, 851 insertions(+), 770 deletions(-) create mode 100644 docs/configuration/data-validation.md create mode 100644 docs/configuration/date-time.md create mode 100644 docs/configuration/default-values.md create mode 100644 docs/configuration/development.md delete mode 100644 docs/configuration/dynamic-settings.md create mode 100644 docs/configuration/miscellaneous.md create mode 100644 docs/configuration/napalm.md delete mode 100644 docs/configuration/optional-settings.md create mode 100644 docs/configuration/plugins.md rename docs/configuration/{required-settings.md => required-parameters.md} (100%) create mode 100644 docs/configuration/security.md create mode 100644 docs/configuration/system.md diff --git a/docs/additional-features/napalm.md b/docs/additional-features/napalm.md index 2387bc8b7..60d8014e2 100644 --- a/docs/additional-features/napalm.md +++ b/docs/additional-features/napalm.md @@ -29,7 +29,7 @@ GET /api/dcim/devices/1/napalm/?method=get_environment ## Authentication -By default, the [`NAPALM_USERNAME`](../configuration/dynamic-settings.md#napalm_username) and [`NAPALM_PASSWORD`](../configuration/dynamic-settings.md#napalm_password) configuration parameters are used for NAPALM authentication. They can be overridden for an individual API call by specifying the `X-NAPALM-Username` and `X-NAPALM-Password` headers. +By default, the [`NAPALM_USERNAME`](../configuration/napalm.md#napalm_username) and [`NAPALM_PASSWORD`](../configuration/napalm.md#napalm_password) configuration parameters are used for NAPALM authentication. They can be overridden for an individual API call by specifying the `X-NAPALM-Username` and `X-NAPALM-Password` headers. ``` $ curl "http://localhost/api/dcim/devices/1/napalm/?method=get_environment" \ diff --git a/docs/administration/housekeeping.md b/docs/administration/housekeeping.md index 1989e41c0..da1a5443b 100644 --- a/docs/administration/housekeeping.md +++ b/docs/administration/housekeeping.md @@ -3,8 +3,8 @@ NetBox includes a `housekeeping` management command that should be run nightly. This command handles: * Clearing expired authentication sessions from the database -* Deleting changelog records older than the configured [retention time](../configuration/dynamic-settings.md#changelog_retention) -* Deleting job result records older than the configured [retention time](../configuration/dynamic-settings.md#jobresult_retention) +* Deleting changelog records older than the configured [retention time](../configuration/miscellaneous.md#changelog_retention) +* Deleting job result records older than the configured [retention time](../configuration/miscellaneous.md#jobresult_retention) This command can be invoked directly, or by using the shell script provided at `/opt/netbox/contrib/netbox-housekeeping.sh`. This script can be linked from your cron scheduler's daily jobs directory (e.g. `/etc/cron.daily`) or referenced directly within the cron configuration file. diff --git a/docs/configuration/data-validation.md b/docs/configuration/data-validation.md new file mode 100644 index 000000000..e4eb4baff --- /dev/null +++ b/docs/configuration/data-validation.md @@ -0,0 +1,86 @@ +# Data & Validation Parameters + +## CUSTOM_VALIDATORS + +!!! tip "Dynamic Configuration Parameter" + +This is a mapping of models to [custom validators](../customization/custom-validation.md) that have been defined locally to enforce custom validation logic. An example is provided below: + +```python +CUSTOM_VALIDATORS = { + "dcim.site": [ + { + "name": { + "min_length": 5, + "max_length": 30 + } + }, + "my_plugin.validators.Validator1" + ], + "dim.device": [ + "my_plugin.validators.Validator1" + ] +} +``` + +--- + +## FIELD_CHOICES + +Some static choice fields on models can be configured with custom values. This is done by defining `FIELD_CHOICES` as a dictionary mapping model fields to their choices. Each choice in the list must have a database value and a human-friendly label, and may optionally specify a color. (A list of available colors is provided below.) + +The choices provided can either replace the stock choices provided by NetBox, or append to them. To _replace_ the available choices, specify the app, model, and field name separated by dots. For example, the site model would be referenced as `dcim.Site.status`. To _extend_ the available choices, append a plus sign to the end of this string (e.g. `dcim.Site.status+`). + +For example, the following configuration would replace the default site status choices with the options Foo, Bar, and Baz: + +```python +FIELD_CHOICES = { + 'dcim.Site.status': ( + ('foo', 'Foo', 'red'), + ('bar', 'Bar', 'green'), + ('baz', 'Baz', 'blue'), + ) +} +``` + +Appending a plus sign to the field identifier would instead _add_ these choices to the ones already offered: + +```python +FIELD_CHOICES = { + 'dcim.Site.status+': ( + ... + ) +} +``` + +The following model fields support configurable choices: + +* `circuits.Circuit.status` +* `dcim.Device.status` +* `dcim.Location.status` +* `dcim.PowerFeed.status` +* `dcim.Rack.status` +* `dcim.Site.status` +* `extras.JournalEntry.kind` +* `ipam.IPAddress.status` +* `ipam.IPRange.status` +* `ipam.Prefix.status` +* `ipam.VLAN.status` +* `virtualization.Cluster.status` +* `virtualization.VirtualMachine.status` + +The following colors are supported: + +* `blue` +* `indigo` +* `purple` +* `pink` +* `red` +* `orange` +* `yellow` +* `green` +* `teal` +* `cyan` +* `gray` +* `black` +* `white` diff --git a/docs/configuration/date-time.md b/docs/configuration/date-time.md new file mode 100644 index 000000000..ab8b5ad13 --- /dev/null +++ b/docs/configuration/date-time.md @@ -0,0 +1,20 @@ +# Date & Time Parameters + +## TIME_ZONE + +Default: UTC + +The time zone NetBox will use when dealing with dates and times. It is recommended to use UTC time unless you have a specific need to use a local time zone. Please see the [list of available time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + +## Date and Time Formatting + +You may define custom formatting for date and times. For detailed instructions on writing format strings, please see [the Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#date). Default formats are listed below. + +```python +DATE_FORMAT = 'N j, Y' # June 26, 2016 +SHORT_DATE_FORMAT = 'Y-m-d' # 2016-06-26 +TIME_FORMAT = 'g:i a' # 1:23 p.m. +SHORT_TIME_FORMAT = 'H:i:s' # 13:23:00 +DATETIME_FORMAT = 'N j, Y g:i a' # June 26, 2016 1:23 p.m. +SHORT_DATETIME_FORMAT = 'Y-m-d H:i' # 2016-06-26 13:23 +``` diff --git a/docs/configuration/default-values.md b/docs/configuration/default-values.md new file mode 100644 index 000000000..6d92858eb --- /dev/null +++ b/docs/configuration/default-values.md @@ -0,0 +1,77 @@ +# Default Value Parameters + +## DEFAULT_USER_PREFERENCES + +!!! tip "Dynamic Configuration Parameter" + +This is a dictionary defining the default preferences to be set for newly-created user accounts. For example, to set the default page size for all users to 100, define the following: + +```python +DEFAULT_USER_PREFERENCES = { + "pagination": { + "per_page": 100 + } +} +``` + +For a complete list of available preferences, log into NetBox and navigate to `/user/preferences/`. A period in a preference name indicates a level of nesting in the JSON data. The example above maps to `pagination.per_page`. + +--- + +## PAGINATE_COUNT + +!!! tip "Dynamic Configuration Parameter" + +Default: 50 + +The default maximum number of objects to display per page within each list of objects. + +--- + +## POWERFEED_DEFAULT_AMPERAGE + +!!! tip "Dynamic Configuration Parameter" + +Default: 15 + +The default value for the `amperage` field when creating new power feeds. + +--- + +## POWERFEED_DEFAULT_MAX_UTILIZATION + +!!! tip "Dynamic Configuration Parameter" + +Default: 80 + +The default value (percentage) for the `max_utilization` field when creating new power feeds. + +--- + +## POWERFEED_DEFAULT_VOLTAGE + +!!! tip "Dynamic Configuration Parameter" + +Default: 120 + +The default value for the `voltage` field when creating new power feeds. + +--- + +## RACK_ELEVATION_DEFAULT_UNIT_HEIGHT + +!!! tip "Dynamic Configuration Parameter" + +Default: 22 + +Default height (in pixels) of a unit within a rack elevation. For best results, this should be approximately one tenth of `RACK_ELEVATION_DEFAULT_UNIT_WIDTH`. + +--- + +## RACK_ELEVATION_DEFAULT_UNIT_WIDTH + +!!! tip "Dynamic Configuration Parameter" + +Default: 220 + +Default width (in pixels) of a unit within a rack elevation. diff --git a/docs/configuration/development.md b/docs/configuration/development.md new file mode 100644 index 000000000..3af56b0e3 --- /dev/null +++ b/docs/configuration/development.md @@ -0,0 +1,21 @@ +# Development Parameters + +## DEBUG + +Default: False + +This setting enables debugging. Debugging should be enabled only during development or troubleshooting. Note that only +clients which access NetBox from a recognized [internal IP address](#internal_ips) will see debugging tools in the user +interface. + +!!! warning + Never enable debugging on a production system, as it can expose sensitive data to unauthenticated users and impose a + substantial performance penalty. + +--- + +## DEVELOPER + +Default: False + +This parameter serves as a safeguard to prevent some potentially dangerous behavior, such as generating new database schema migrations. Set this to `True` **only** if you are actively developing the NetBox code base. diff --git a/docs/configuration/dynamic-settings.md b/docs/configuration/dynamic-settings.md deleted file mode 100644 index d376dc5c4..000000000 --- a/docs/configuration/dynamic-settings.md +++ /dev/null @@ -1,232 +0,0 @@ -# Dynamic Configuration Settings - -These configuration parameters are primarily controlled via NetBox's admin interface (under Admin > Extras > Configuration Revisions). These setting may also be overridden in `configuration.py`; this will prevent them from being modified via the UI. - ---- - -## ALLOWED_URL_SCHEMES - -Default: `('file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto', 'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp')` - -A list of permitted URL schemes referenced when rendering links within NetBox. Note that only the schemes specified in this list will be accepted: If adding your own, be sure to replicate all of the default values as well (excluding those schemes which are not desirable). - ---- - -## BANNER_TOP - -## BANNER_BOTTOM - -Setting these variables will display custom content in a banner at the top and/or bottom of the page, respectively. HTML is allowed. To replicate the content of the top banner in the bottom banner, set: - -```python -BANNER_TOP = 'Your banner text' -BANNER_BOTTOM = BANNER_TOP -``` - ---- - -## BANNER_LOGIN - -This defines custom content to be displayed on the login page above the login form. HTML is allowed. - ---- - -## CHANGELOG_RETENTION - -Default: 90 - -The number of days to retain logged changes (object creations, updates, and deletions). Set this to `0` to retain -changes in the database indefinitely. - -!!! warning - If enabling indefinite changelog retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity. - ---- - -## CUSTOM_VALIDATORS - -This is a mapping of models to [custom validators](../customization/custom-validation.md) that have been defined locally to enforce custom validation logic. An example is provided below: - -```python -CUSTOM_VALIDATORS = { - "dcim.site": [ - { - "name": { - "min_length": 5, - "max_length": 30 - } - }, - "my_plugin.validators.Validator1" - ], - "dim.device": [ - "my_plugin.validators.Validator1" - ] -} -``` - ---- - -## DEFAULT_USER_PREFERENCES - -This is a dictionary defining the default preferences to be set for newly-created user accounts. For example, to set the default page size for all users to 100, define the following: - -```python -DEFAULT_USER_PREFERENCES = { - "pagination": { - "per_page": 100 - } -} -``` - -For a complete list of available preferences, log into NetBox and navigate to `/user/preferences/`. A period in a preference name indicates a level of nesting in the JSON data. The example above maps to `pagination.per_page`. - ---- - -## ENFORCE_GLOBAL_UNIQUE - -Default: False - -By default, NetBox will permit users to create duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This behavior can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to True. - ---- - -## GRAPHQL_ENABLED - -Default: True - -Setting this to False will disable the GraphQL API. - ---- - -## JOBRESULT_RETENTION - -Default: 90 - -The number of days to retain job results (scripts and reports). Set this to `0` to retain -job results in the database indefinitely. - -!!! warning - If enabling indefinite job results retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity. - ---- - -## MAINTENANCE_MODE - -Default: False - -Setting this to True will display a "maintenance mode" banner at the top of every page. Additionally, NetBox will no longer update a user's "last active" time upon login. This is to allow new logins when the database is in a read-only state. Recording of login times will resume when maintenance mode is disabled. - ---- - -## MAPS_URL - -Default: `https://maps.google.com/?q=` (Google Maps) - -This specifies the URL to use when presenting a map of a physical location by street address or GPS coordinates. The URL must accept either a free-form street address or a comma-separated pair of numeric coordinates appended to it. - ---- - -## MAX_PAGE_SIZE - -Default: 1000 - -A web user or API consumer can request an arbitrary number of objects by appending the "limit" parameter to the URL (e.g. `?limit=1000`). This parameter defines the maximum acceptable limit. Setting this to `0` or `None` will allow a client to retrieve _all_ matching objects at once with no limit by specifying `?limit=0`. - ---- - -## NAPALM_USERNAME - -## NAPALM_PASSWORD - -NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional. - -!!! note - If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed. - ---- - -## NAPALM_ARGS - -A dictionary of optional arguments to pass to NAPALM when instantiating a network driver. See the NAPALM documentation for a [complete list of optional arguments](https://napalm.readthedocs.io/en/latest/support/#optional-arguments). An example: - -```python -NAPALM_ARGS = { - 'api_key': '472071a93b60a1bd1fafb401d9f8ef41', - 'port': 2222, -} -``` - -Some platforms (e.g. Cisco IOS) require an argument named `secret` to be passed in addition to the normal password. If desired, you can use the configured `NAPALM_PASSWORD` as the value for this argument: - -```python -NAPALM_USERNAME = 'username' -NAPALM_PASSWORD = 'MySecretPassword' -NAPALM_ARGS = { - 'secret': NAPALM_PASSWORD, - # Include any additional args here -} -``` - ---- - -## NAPALM_TIMEOUT - -Default: 30 seconds - -The amount of time (in seconds) to wait for NAPALM to connect to a device. - ---- - -## PAGINATE_COUNT - -Default: 50 - -The default maximum number of objects to display per page within each list of objects. - ---- - -## POWERFEED_DEFAULT_AMPERAGE - -Default: 15 - -The default value for the `amperage` field when creating new power feeds. - ---- - -## POWERFEED_DEFAULT_MAX_UTILIZATION - -Default: 80 - -The default value (percentage) for the `max_utilization` field when creating new power feeds. - ---- - -## POWERFEED_DEFAULT_VOLTAGE - -Default: 120 - -The default value for the `voltage` field when creating new power feeds. - ---- - -## PREFER_IPV4 - -Default: False - -When determining the primary IP address for a device, IPv6 is preferred over IPv4 by default. Set this to True to prefer IPv4 instead. - ---- - -## RACK_ELEVATION_DEFAULT_UNIT_HEIGHT - -Default: 22 - -Default height (in pixels) of a unit within a rack elevation. For best results, this should be approximately one tenth of `RACK_ELEVATION_DEFAULT_UNIT_WIDTH`. - ---- - -## RACK_ELEVATION_DEFAULT_UNIT_WIDTH - -Default: 220 - -Default width (in pixels) of a unit within a rack elevation. diff --git a/docs/configuration/index.md b/docs/configuration/index.md index a863ef3dc..42d254027 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -1,24 +1,50 @@ # NetBox Configuration -NetBox's local configuration is stored in `$INSTALL_ROOT/netbox/netbox/configuration.py` by default. An example configuration is provided as `configuration_example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file. While NetBox has many configuration settings, only a few of them must be defined at the time of installation: these are defined under "required settings" below. +## Configuration File + +NetBox's configuration file contains all the important parameters which control how NetBox functions: database settings, security controls, user preferences, and so on. While the default configuration suffices out of the box for most use cases, there are a few [required parameters](./required-parameters.md) which **must** be defined during installation. + +The configuration file is loaded from `$INSTALL_ROOT/netbox/netbox/configuration.py` by default. An example configuration is provided at `configuration_example.py`, which you may copy to use as your default config. Note that a configuration file must be defined; NetBox will not run without one. !!! info "Customizing the Configuration Module" A custom configuration module may be specified by setting the `NETBOX_CONFIGURATION` environment variable. This must be a dotted path to the desired Python module. For example, a file named `my_config.py` in the same directory as `settings.py` would be referenced as `netbox.my_config`. - For the sake of brevity, the NetBox documentation refers to the configuration file simply as `configuration.py`. + To keep things simple, the NetBox documentation refers to the configuration file simply as `configuration.py`. Some configuration parameters may alternatively be defined either in `configuration.py` or within the administrative section of the user interface. Settings which are "hard-coded" in the configuration file take precedence over those defined via the UI. -## Configuration Parameters +## Dynamic Configuration Parameters -* [Required settings](required-settings.md) -* [Optional settings](optional-settings.md) -* [Dynamic settings](dynamic-settings.md) -* [Remote authentication settings](remote-authentication.md) +Some configuration parameters are primarily controlled via NetBox's admin interface (under Admin > Extras > Configuration Revisions). These are noted where applicable in the documentation. These settings may also be overridden in `configuration.py` to prevent them from being modified via the UI. A complete list of supported parameters is provided below: -## Changing the Configuration +* [`ALLOWED_URL_SCHEMES`](./security.md#allowed_url_schemes) +* [`BANNER_BOTTOM`](./miscellaneous.md#banner_bottom) +* [`BANNER_LOGIN`](./miscellaneous.md#banner_login) +* [`BANNER_TOP`](./miscellaneous.md#banner_top) +* [`CHANGELOG_RETENTION`](./miscellaneous.md#changelog_retention) +* [`CUSTOM_VALIDATORS`](./data-validation.md#custom_validators) +* [`DEFAULT_USER_PREFERENCES`](./default-values.md#default_user_preferences) +* [`ENFORCE_GLOBAL_UNIQUE`](./miscellaneous.md#enforce_global_unique) +* [`GRAPHQL_ENABLED`](./miscellaneous.md#graphql_enabled) +* [`JOBRESULT_RETENTION`](./miscellaneous.md#jobresult_retention) +* [`MAINTENANCE_MODE`](./miscellaneous.md#maintenance_mode) +* [`MAPS_URL`](./miscellaneous.md#maps_url) +* [`MAX_PAGE_SIZE`](./miscellaneous.md#max_page_size) +* [`NAPALM_ARGS`](./napalm.md#napalm_args) +* [`NAPALM_PASSWORD`](./napalm.md#napalm_password) +* [`NAPALM_TIMEOUT`](./napalm.md#napalm_timeout) +* [`NAPALM_USERNAME`](./napalm.md#napalm_username) +* [`PAGINATE_COUNT`](./default-values.md#paginate_count) +* [`POWERFEED_DEFAULT_AMPERAGE`](./default-values.md#powerfeed_default_amperage) +* [`POWERFEED_DEFAULT_MAX_UTILIZATION`](./default-values.md#powerfeed_default_max_utilization) +* [`POWERFEED_DEFAULT_VOLTAGE`](./default-values.md#powerfeed_default_voltage) +* [`PREFER_IPV4`](./miscellaneous.md#prefer_ipv4) +* [`RACK_ELEVATION_DEFAULT_UNIT_HEIGHT`](./default-values.md#rack_elevation_default_unit_height) +* [`RACK_ELEVATION_DEFAULT_UNIT_WIDTH`](./default-values.md#rack_elevation_default_unit_width) -The configuration file may be modified at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before the changes will take effect: +## Modifying the Configuration + +The configuration file may be modified at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before these changes will take effect: ```no-highlight $ sudo systemctl restart netbox diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md new file mode 100644 index 000000000..2aa21b7e5 --- /dev/null +++ b/docs/configuration/miscellaneous.md @@ -0,0 +1,159 @@ +# Miscellaneous Parameters + +## ADMINS + +NetBox will email details about critical errors to the administrators listed here. This should be a list of (name, email) tuples. For example: + +```python +ADMINS = [ + ['Hank Hill', 'hhill@example.com'], + ['Dale Gribble', 'dgribble@example.com'], +] +``` + +--- + +## BANNER_BOTTOM + +!!! tip "Dynamic Configuration Parameter" + +Sets content for the bottom banner in the user interface. + +--- + +## BANNER_LOGIN + +!!! tip "Dynamic Configuration Parameter" + +This defines custom content to be displayed on the login page above the login form. HTML is allowed. + +--- + +## BANNER_TOP + +!!! tip "Dynamic Configuration Parameter" + +Sets content for the top banner in the user interface. + +!!! tip + If you'd like the top and bottom banners to match, set the following: + + ```python + BANNER_TOP = 'Your banner text' + BANNER_BOTTOM = BANNER_TOP + ``` + +--- + +## CHANGELOG_RETENTION + +!!! tip "Dynamic Configuration Parameter" + +Default: 90 + +The number of days to retain logged changes (object creations, updates, and deletions). Set this to `0` to retain +changes in the database indefinitely. + +!!! warning + If enabling indefinite changelog retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity. + +--- + +## ENFORCE_GLOBAL_UNIQUE + +!!! tip "Dynamic Configuration Parameter" + +Default: False + +By default, NetBox will permit users to create duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This behavior can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to True. + +--- + +## GRAPHQL_ENABLED + +!!! tip "Dynamic Configuration Parameter" + +Default: True + +Setting this to False will disable the GraphQL API. + +--- + +## JOBRESULT_RETENTION + +!!! tip "Dynamic Configuration Parameter" + +Default: 90 + +The number of days to retain job results (scripts and reports). Set this to `0` to retain +job results in the database indefinitely. + +!!! warning + If enabling indefinite job results retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity. + +--- + +## MAINTENANCE_MODE + +!!! tip "Dynamic Configuration Parameter" + +Default: False + +Setting this to True will display a "maintenance mode" banner at the top of every page. Additionally, NetBox will no longer update a user's "last active" time upon login. This is to allow new logins when the database is in a read-only state. Recording of login times will resume when maintenance mode is disabled. + +--- + +## MAPS_URL + +!!! tip "Dynamic Configuration Parameter" + +Default: `https://maps.google.com/?q=` (Google Maps) + +This specifies the URL to use when presenting a map of a physical location by street address or GPS coordinates. The URL must accept either a free-form street address or a comma-separated pair of numeric coordinates appended to it. + +--- + +## MAX_PAGE_SIZE + +!!! tip "Dynamic Configuration Parameter" + +Default: 1000 + +A web user or API consumer can request an arbitrary number of objects by appending the "limit" parameter to the URL (e.g. `?limit=1000`). This parameter defines the maximum acceptable limit. Setting this to `0` or `None` will allow a client to retrieve _all_ matching objects at once with no limit by specifying `?limit=0`. + +--- + +## METRICS_ENABLED + +Default: False + +Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../additional-features/prometheus-metrics.md) documentation for more details. + +--- + +## PREFER_IPV4 + +!!! tip "Dynamic Configuration Parameter" + +Default: False + +When determining the primary IP address for a device, IPv6 is preferred over IPv4 by default. Set this to True to prefer IPv4 instead. + +--- + +## RELEASE_CHECK_URL + +Default: None (disabled) + +This parameter defines the URL of the repository that will be checked for new NetBox releases. When a new release is detected, a message will be displayed to administrative users on the home page. This can be set to the official repository (`'https://api.github.com/repos/netbox-community/netbox/releases'`) or a custom fork. Set this to `None` to disable automatic update checks. + +!!! note + The URL provided **must** be compatible with the [GitHub REST API](https://docs.github.com/en/rest). + +--- + +## RQ_DEFAULT_TIMEOUT + +Default: `300` + +The maximum execution time of a background task (such as running a custom script), in seconds. diff --git a/docs/configuration/napalm.md b/docs/configuration/napalm.md new file mode 100644 index 000000000..925ec17e6 --- /dev/null +++ b/docs/configuration/napalm.md @@ -0,0 +1,51 @@ +# NAPALM Parameters + +## NAPALM_USERNAME + +## NAPALM_PASSWORD + +!!! tip "Dynamic Configuration Parameter" + +NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional. + +!!! note + If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed. + +--- + +## NAPALM_ARGS + +!!! tip "Dynamic Configuration Parameter" + +A dictionary of optional arguments to pass to NAPALM when instantiating a network driver. See the NAPALM documentation for a [complete list of optional arguments](https://napalm.readthedocs.io/en/latest/support/#optional-arguments). An example: + +```python +NAPALM_ARGS = { + 'api_key': '472071a93b60a1bd1fafb401d9f8ef41', + 'port': 2222, +} +``` + +Some platforms (e.g. Cisco IOS) require an argument named `secret` to be passed in addition to the normal password. If desired, you can use the configured `NAPALM_PASSWORD` as the value for this argument: + +```python +NAPALM_USERNAME = 'username' +NAPALM_PASSWORD = 'MySecretPassword' +NAPALM_ARGS = { + 'secret': NAPALM_PASSWORD, + # Include any additional args here +} +``` + +--- + +## NAPALM_TIMEOUT + +!!! tip "Dynamic Configuration Parameter" + +Default: 30 seconds + +The amount of time (in seconds) to wait for NAPALM to connect to a device. + +--- + diff --git a/docs/configuration/optional-settings.md b/docs/configuration/optional-settings.md deleted file mode 100644 index 8e5664a95..000000000 --- a/docs/configuration/optional-settings.md +++ /dev/null @@ -1,489 +0,0 @@ -# Optional Configuration Settings - -## ADMINS - -NetBox will email details about critical errors to the administrators listed here. This should be a list of (name, email) tuples. For example: - -```python -ADMINS = [ - ['Hank Hill', 'hhill@example.com'], - ['Dale Gribble', 'dgribble@example.com'], -] -``` - ---- - -## AUTH_PASSWORD_VALIDATORS - -This parameter acts as a pass-through for configuring Django's built-in password validators for local user accounts. If configured, these will be applied whenever a user's password is updated to ensure that it meets minimum criteria such as length or complexity. An example is provided below. For more detail on the available options, please see [the Django documentation](https://docs.djangoproject.com/en/stable/topics/auth/passwords/#password-validation). - -```python -AUTH_PASSWORD_VALIDATORS = [ - { - 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator', - 'OPTIONS': { - 'min_length': 10, - } - }, -] -``` - ---- - -## BASE_PATH - -Default: None - -The base URL path to use when accessing NetBox. Do not include the scheme or domain name. For example, if installed at https://example.com/netbox/, set: - -```python -BASE_PATH = 'netbox/' -``` - ---- - -## CORS_ORIGIN_ALLOW_ALL - -Default: False - -If True, cross-origin resource sharing (CORS) requests will be accepted from all origins. If False, a whitelist will be used (see below). - ---- - -## CORS_ORIGIN_WHITELIST - -## CORS_ORIGIN_REGEX_WHITELIST - -These settings specify a list of origins that are authorized to make cross-site API requests. Use -`CORS_ORIGIN_WHITELIST` to define a list of exact hostnames, or `CORS_ORIGIN_REGEX_WHITELIST` to define a set of regular -expressions. (These settings have no effect if `CORS_ORIGIN_ALLOW_ALL` is True.) For example: - -```python -CORS_ORIGIN_WHITELIST = [ - 'https://example.com', -] -``` - ---- - -## CSRF_COOKIE_NAME - -Default: `csrftoken` - -The name of the cookie to use for the cross-site request forgery (CSRF) authentication token. See the [Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#csrf-cookie-name) for more detail. - ---- - -## CSRF_TRUSTED_ORIGINS - -Default: `[]` - -Defines a list of trusted origins for unsafe (e.g. `POST`) requests. This is a pass-through to Django's [`CSRF_TRUSTED_ORIGINS`](https://docs.djangoproject.com/en/4.0/ref/settings/#std:setting-CSRF_TRUSTED_ORIGINS) setting. Note that each host listed must specify a scheme (e.g. `http://` or `https://). - -```python -CSRF_TRUSTED_ORIGINS = ( - 'http://netbox.local', - 'https://netbox.local', -) -``` - ---- - -## DEBUG - -Default: False - -This setting enables debugging. Debugging should be enabled only during development or troubleshooting. Note that only -clients which access NetBox from a recognized [internal IP address](#internal_ips) will see debugging tools in the user -interface. - -!!! warning - Never enable debugging on a production system, as it can expose sensitive data to unauthenticated users and impose a - substantial performance penalty. - ---- - -## DEVELOPER - -Default: False - -This parameter serves as a safeguard to prevent some potentially dangerous behavior, such as generating new database schema migrations. Set this to `True` **only** if you are actively developing the NetBox code base. - ---- - -## DOCS_ROOT - -Default: `$INSTALL_ROOT/docs/` - -The filesystem path to NetBox's documentation. This is used when presenting context-sensitive documentation in the web UI. By default, this will be the `docs/` directory within the root NetBox installation path. (Set this to `None` to disable the embedded documentation.) - ---- - -## EMAIL - -In order to send email, NetBox needs an email server configured. The following items can be defined within the `EMAIL` configuration parameter: - -* `SERVER` - Hostname or IP address of the email server (use `localhost` if running locally) -* `PORT` - TCP port to use for the connection (default: `25`) -* `USERNAME` - Username with which to authenticate -* `PASSSWORD` - Password with which to authenticate -* `USE_SSL` - Use SSL when connecting to the server (default: `False`) -* `USE_TLS` - Use TLS when connecting to the server (default: `False`) -* `SSL_CERTFILE` - Path to the PEM-formatted SSL certificate file (optional) -* `SSL_KEYFILE` - Path to the PEM-formatted SSL private key file (optional) -* `TIMEOUT` - Amount of time to wait for a connection, in seconds (default: `10`) -* `FROM_EMAIL` - Sender address for emails sent by NetBox - -!!! note - The `USE_SSL` and `USE_TLS` parameters are mutually exclusive. - -Email is sent from NetBox only for critical events or if configured for [logging](#logging). If you would like to test the email server configuration, Django provides a convenient [send_mail()](https://docs.djangoproject.com/en/stable/topics/email/#send-mail) function accessible within the NetBox shell: - -```no-highlight -# python ./manage.py nbshell ->>> from django.core.mail import send_mail ->>> send_mail( - 'Test Email Subject', - 'Test Email Body', - 'noreply-netbox@example.com', - ['users@example.com'], - fail_silently=False -) -``` - ---- - -## EXEMPT_VIEW_PERMISSIONS - -Default: Empty list - -A list of NetBox models to exempt from the enforcement of view permissions. Models listed here will be viewable by all users, both authenticated and anonymous. - -List models in the form `.`. For example: - -```python -EXEMPT_VIEW_PERMISSIONS = [ - 'dcim.site', - 'dcim.region', - 'ipam.prefix', -] -``` - -To exempt _all_ models from view permission enforcement, set the following. (Note that `EXEMPT_VIEW_PERMISSIONS` must be an iterable.) - -```python -EXEMPT_VIEW_PERMISSIONS = ['*'] -``` - -!!! note - Using a wildcard will not affect certain potentially sensitive models, such as user permissions. If there is a need to exempt these models, they must be specified individually. - ---- - -## FIELD_CHOICES - -Some static choice fields on models can be configured with custom values. This is done by defining `FIELD_CHOICES` as a dictionary mapping model fields to their choices. Each choice in the list must have a database value and a human-friendly label, and may optionally specify a color. (A list of available colors is provided below.) - -The choices provided can either replace the stock choices provided by NetBox, or append to them. To _replace_ the available choices, specify the app, model, and field name separated by dots. For example, the site model would be referenced as `dcim.Site.status`. To _extend_ the available choices, append a plus sign to the end of this string (e.g. `dcim.Site.status+`). - -For example, the following configuration would replace the default site status choices with the options Foo, Bar, and Baz: - -```python -FIELD_CHOICES = { - 'dcim.Site.status': ( - ('foo', 'Foo', 'red'), - ('bar', 'Bar', 'green'), - ('baz', 'Baz', 'blue'), - ) -} -``` - -Appending a plus sign to the field identifier would instead _add_ these choices to the ones already offered: - -```python -FIELD_CHOICES = { - 'dcim.Site.status+': ( - ... - ) -} -``` - -The following model fields support configurable choices: - -* `circuits.Circuit.status` -* `dcim.Device.status` -* `dcim.Location.status` -* `dcim.PowerFeed.status` -* `dcim.Rack.status` -* `dcim.Site.status` -* `extras.JournalEntry.kind` -* `ipam.IPAddress.status` -* `ipam.IPRange.status` -* `ipam.Prefix.status` -* `ipam.VLAN.status` -* `virtualization.Cluster.status` -* `virtualization.VirtualMachine.status` - -The following colors are supported: - -* `blue` -* `indigo` -* `purple` -* `pink` -* `red` -* `orange` -* `yellow` -* `green` -* `teal` -* `cyan` -* `gray` -* `black` -* `white` - ---- - -## HTTP_PROXIES - -Default: None - -A dictionary of HTTP proxies to use for outbound requests originating from NetBox (e.g. when sending webhook requests). Proxies should be specified by schema (HTTP and HTTPS) as per the [Python requests library documentation](https://2.python-requests.org/en/master/user/advanced/). For example: - -```python -HTTP_PROXIES = { - 'http': 'http://10.10.1.10:3128', - 'https': 'http://10.10.1.10:1080', -} -``` - ---- - -## JINJA2_FILTERS - -Default: `{}` - -A dictionary of custom jinja2 filters with the key being the filter name and the value being a callable. For more information see the [Jinja2 documentation](https://jinja.palletsprojects.com/en/3.1.x/api/#custom-filters). For example: - -```python -def uppercase(x): - return str(x).upper() - -JINJA2_FILTERS = { - 'uppercase': uppercase, -} -``` - ---- - -## INTERNAL_IPS - -Default: `('127.0.0.1', '::1')` - -A list of IP addresses recognized as internal to the system, used to control the display of debugging output. For -example, the debugging toolbar will be viewable only when a client is accessing NetBox from one of the listed IP -addresses (and [`DEBUG`](#debug) is true). - ---- - -## LOGGING - -By default, all messages of INFO severity or higher will be logged to the console. Additionally, if [`DEBUG`](#debug) is False and email access has been configured, ERROR and CRITICAL messages will be emailed to the users defined in [`ADMINS`](#admins). - -The Django framework on which NetBox runs allows for the customization of logging format and destination. Please consult the [Django logging documentation](https://docs.djangoproject.com/en/stable/topics/logging/) for more information on configuring this setting. Below is an example which will write all INFO and higher messages to a local file: - -```python -LOGGING = { - 'version': 1, - 'disable_existing_loggers': False, - 'handlers': { - 'file': { - 'level': 'INFO', - 'class': 'logging.FileHandler', - 'filename': '/var/log/netbox.log', - }, - }, - 'loggers': { - 'django': { - 'handlers': ['file'], - 'level': 'INFO', - }, - }, -} -``` - -### Available Loggers - -* `netbox..` - Generic form for model-specific log messages -* `netbox.auth.*` - Authentication events -* `netbox.api.views.*` - Views which handle business logic for the REST API -* `netbox.reports.*` - Report execution (`module.name`) -* `netbox.scripts.*` - Custom script execution (`module.name`) -* `netbox.views.*` - Views which handle business logic for the web UI - ---- - -## LOGIN_PERSISTENCE - -Default: False - -If true, the lifetime of a user's authentication session will be automatically reset upon each valid request. For example, if [`LOGIN_TIMEOUT`](#login_timeout) is configured to 14 days (the default), and a user whose session is due to expire in five days makes a NetBox request (with a valid session cookie), the session's lifetime will be reset to 14 days. - -Note that enabling this setting causes NetBox to update a user's session in the database (or file, as configured per [`SESSION_FILE_PATH`](#session_file_path)) with each request, which may introduce significant overhead in very active environments. It also permits an active user to remain authenticated to NetBox indefinitely. - ---- - -## LOGIN_REQUIRED - -Default: False - -Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users are permitted to access most data in NetBox but not make any changes. - ---- - -## LOGIN_TIMEOUT - -Default: 1209600 seconds (14 days) - -The lifetime (in seconds) of the authentication cookie issued to a NetBox user upon login. - ---- - -## MEDIA_ROOT - -Default: $INSTALL_ROOT/netbox/media/ - -The file path to the location where media files (such as image attachments) are stored. By default, this is the `netbox/media/` directory within the base NetBox installation path. - ---- - -## METRICS_ENABLED - -Default: False - -Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../additional-features/prometheus-metrics.md) documentation for more details. - ---- - -## PLUGINS - -Default: Empty - -A list of installed [NetBox plugins](../../plugins/) to enable. Plugins will not take effect unless they are listed here. - -!!! warning - Plugins extend NetBox by allowing external code to run with the same access and privileges as NetBox itself. Only install plugins from trusted sources. The NetBox maintainers make absolutely no guarantees about the integrity or security of your installation with plugins enabled. - ---- - -## PLUGINS_CONFIG - -Default: Empty - -This parameter holds configuration settings for individual NetBox plugins. It is defined as a dictionary, with each key using the name of an installed plugin. The specific parameters supported are unique to each plugin: Reference the plugin's documentation to determine the supported parameters. An example configuration is shown below: - -```python -PLUGINS_CONFIG = { - 'plugin1': { - 'foo': 123, - 'bar': True - }, - 'plugin2': { - 'foo': 456, - }, -} -``` - -Note that a plugin must be listed in `PLUGINS` for its configuration to take effect. - ---- - -## RELEASE_CHECK_URL - -Default: None (disabled) - -This parameter defines the URL of the repository that will be checked for new NetBox releases. When a new release is detected, a message will be displayed to administrative users on the home page. This can be set to the official repository (`'https://api.github.com/repos/netbox-community/netbox/releases'`) or a custom fork. Set this to `None` to disable automatic update checks. - -!!! note - The URL provided **must** be compatible with the [GitHub REST API](https://docs.github.com/en/rest). - ---- - -## REPORTS_ROOT - -Default: `$INSTALL_ROOT/netbox/reports/` - -The file path to the location where [custom reports](../customization/reports.md) will be kept. By default, this is the `netbox/reports/` directory within the base NetBox installation path. - ---- - -## RQ_DEFAULT_TIMEOUT - -Default: `300` - -The maximum execution time of a background task (such as running a custom script), in seconds. - ---- - -## SCRIPTS_ROOT - -Default: `$INSTALL_ROOT/netbox/scripts/` - -The file path to the location where [custom scripts](../customization/custom-scripts.md) will be kept. By default, this is the `netbox/scripts/` directory within the base NetBox installation path. - ---- - -## SESSION_COOKIE_NAME - -Default: `sessionid` - -The name used for the session cookie. See the [Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#session-cookie-name) for more detail. - ---- - -## SESSION_FILE_PATH - -Default: None - -HTTP session data is used to track authenticated users when they access NetBox. By default, NetBox stores session data in its PostgreSQL database. However, this inhibits authentication to a standby instance of NetBox without write access to the database. Alternatively, a local file path may be specified here and NetBox will store session data as files instead of using the database. Note that the NetBox system user must have read and write permissions to this path. - ---- - -## STORAGE_BACKEND - -Default: None (local storage) - -The backend storage engine for handling uploaded files (e.g. image attachments). NetBox supports integration with the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) package, which provides backends for several popular file storage services. If not configured, local filesystem storage will be used. - -The configuration parameters for the specified storage backend are defined under the `STORAGE_CONFIG` setting. - ---- - -## STORAGE_CONFIG - -Default: Empty - -A dictionary of configuration parameters for the storage backend configured as `STORAGE_BACKEND`. The specific parameters to be used here are specific to each backend; see the [`django-storages` documentation](https://django-storages.readthedocs.io/en/stable/) for more detail. - -If `STORAGE_BACKEND` is not defined, this setting will be ignored. - ---- - -## TIME_ZONE - -Default: UTC - -The time zone NetBox will use when dealing with dates and times. It is recommended to use UTC time unless you have a specific need to use a local time zone. Please see the [list of available time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - ---- - -## Date and Time Formatting - -You may define custom formatting for date and times. For detailed instructions on writing format strings, please see [the Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#date). Default formats are listed below. - -```python -DATE_FORMAT = 'N j, Y' # June 26, 2016 -SHORT_DATE_FORMAT = 'Y-m-d' # 2016-06-26 -TIME_FORMAT = 'g:i a' # 1:23 p.m. -SHORT_TIME_FORMAT = 'H:i:s' # 13:23:00 -DATETIME_FORMAT = 'N j, Y g:i a' # June 26, 2016 1:23 p.m. -SHORT_DATETIME_FORMAT = 'Y-m-d H:i' # 2016-06-26 13:23 -``` diff --git a/docs/configuration/plugins.md b/docs/configuration/plugins.md new file mode 100644 index 000000000..aea60f389 --- /dev/null +++ b/docs/configuration/plugins.md @@ -0,0 +1,35 @@ +# Plugin Parameters + +## PLUGINS + +Default: Empty + +A list of installed [NetBox plugins](../../plugins/) to enable. Plugins will not take effect unless they are listed here. + +!!! warning + Plugins extend NetBox by allowing external code to run with the same access and privileges as NetBox itself. Only install plugins from trusted sources. The NetBox maintainers make absolutely no guarantees about the integrity or security of your installation with plugins enabled. + +--- + +## PLUGINS_CONFIG + +Default: Empty + +This parameter holds configuration settings for individual NetBox plugins. It is defined as a dictionary, with each key using the name of an installed plugin. The specific parameters supported are unique to each plugin: Reference the plugin's documentation to determine the supported parameters. An example configuration is shown below: + +```python +PLUGINS_CONFIG = { + 'plugin1': { + 'foo': 123, + 'bar': True + }, + 'plugin2': { + 'foo': 456, + }, +} +``` + +Note that a plugin must be listed in `PLUGINS` for its configuration to take effect. + +--- + diff --git a/docs/configuration/remote-authentication.md b/docs/configuration/remote-authentication.md index 2c3a7002f..07adf5c6a 100644 --- a/docs/configuration/remote-authentication.md +++ b/docs/configuration/remote-authentication.md @@ -47,6 +47,22 @@ NetBox can be configured to support remote user authentication by inferring user --- +## REMOTE_AUTH_GROUP_HEADER + +Default: `'HTTP_REMOTE_USER_GROUP'` + +When remote user authentication is in use, this is the name of the HTTP header which informs NetBox of the currently authenticated user. For example, to use the request header `X-Remote-User-Groups` it needs to be set to `HTTP_X_REMOTE_USER_GROUPS`. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) + +--- + +## REMOTE_AUTH_GROUP_SEPARATOR + +Default: `|` (Pipe) + +The Seperator upon which `REMOTE_AUTH_GROUP_HEADER` gets split into individual Groups. This needs to be coordinated with your authentication Proxy. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) + +--- + ## REMOTE_AUTH_GROUP_SYNC_ENABLED Default: `False` @@ -63,14 +79,6 @@ When remote user authentication is in use, this is the name of the HTTP header w --- -## REMOTE_AUTH_GROUP_HEADER - -Default: `'HTTP_REMOTE_USER_GROUP'` - -When remote user authentication is in use, this is the name of the HTTP header which informs NetBox of the currently authenticated user. For example, to use the request header `X-Remote-User-Groups` it needs to be set to `HTTP_X_REMOTE_USER_GROUPS`. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) - ---- - ## REMOTE_AUTH_SUPERUSER_GROUPS Default: `[]` (Empty list) @@ -100,11 +108,3 @@ The list of groups that promote an remote User to Staff on Login. If group isn't Default: `[]` (Empty list) The list of users that get promoted to Staff on Login. If user isn't present in list on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) - ---- - -## REMOTE_AUTH_GROUP_SEPARATOR - -Default: `|` (Pipe) - -The Seperator upon which `REMOTE_AUTH_GROUP_HEADER` gets split into individual Groups. This needs to be coordinated with your authentication Proxy. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` ) diff --git a/docs/configuration/required-settings.md b/docs/configuration/required-parameters.md similarity index 100% rename from docs/configuration/required-settings.md rename to docs/configuration/required-parameters.md diff --git a/docs/configuration/security.md b/docs/configuration/security.md new file mode 100644 index 000000000..6aa363b1a --- /dev/null +++ b/docs/configuration/security.md @@ -0,0 +1,144 @@ +# Security & Authentication Parameters + +## ALLOWED_URL_SCHEMES + +!!! tip "Dynamic Configuration Parameter" + +Default: `('file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto', 'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp')` + +A list of permitted URL schemes referenced when rendering links within NetBox. Note that only the schemes specified in this list will be accepted: If adding your own, be sure to replicate all the default values as well (excluding those schemes which are not desirable). + +--- + +## AUTH_PASSWORD_VALIDATORS + +This parameter acts as a pass-through for configuring Django's built-in password validators for local user accounts. If configured, these will be applied whenever a user's password is updated to ensure that it meets minimum criteria such as length or complexity. An example is provided below. For more detail on the available options, please see [the Django documentation](https://docs.djangoproject.com/en/stable/topics/auth/passwords/#password-validation). + +```python +AUTH_PASSWORD_VALIDATORS = [ + { + 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator', + 'OPTIONS': { + 'min_length': 10, + } + }, +] +``` + +--- + +## CORS_ORIGIN_ALLOW_ALL + +Default: False + +If True, cross-origin resource sharing (CORS) requests will be accepted from all origins. If False, a whitelist will be used (see below). + +--- + +## CORS_ORIGIN_WHITELIST + +## CORS_ORIGIN_REGEX_WHITELIST + +These settings specify a list of origins that are authorized to make cross-site API requests. Use +`CORS_ORIGIN_WHITELIST` to define a list of exact hostnames, or `CORS_ORIGIN_REGEX_WHITELIST` to define a set of regular +expressions. (These settings have no effect if `CORS_ORIGIN_ALLOW_ALL` is True.) For example: + +```python +CORS_ORIGIN_WHITELIST = [ + 'https://example.com', +] +``` + +--- + +## CSRF_COOKIE_NAME + +Default: `csrftoken` + +The name of the cookie to use for the cross-site request forgery (CSRF) authentication token. See the [Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#csrf-cookie-name) for more detail. + +--- + +--- + +## CSRF_TRUSTED_ORIGINS + +Default: `[]` + +Defines a list of trusted origins for unsafe (e.g. `POST`) requests. This is a pass-through to Django's [`CSRF_TRUSTED_ORIGINS`](https://docs.djangoproject.com/en/4.0/ref/settings/#std:setting-CSRF_TRUSTED_ORIGINS) setting. Note that each host listed must specify a scheme (e.g. `http://` or `https://). + +```python +CSRF_TRUSTED_ORIGINS = ( + 'http://netbox.local', + 'https://netbox.local', +) +``` + +--- + +## EXEMPT_VIEW_PERMISSIONS + +Default: Empty list + +A list of NetBox models to exempt from the enforcement of view permissions. Models listed here will be viewable by all users, both authenticated and anonymous. + +List models in the form `.`. For example: + +```python +EXEMPT_VIEW_PERMISSIONS = [ + 'dcim.site', + 'dcim.region', + 'ipam.prefix', +] +``` + +To exempt _all_ models from view permission enforcement, set the following. (Note that `EXEMPT_VIEW_PERMISSIONS` must be an iterable.) + +```python +EXEMPT_VIEW_PERMISSIONS = ['*'] +``` + +!!! note + Using a wildcard will not affect certain potentially sensitive models, such as user permissions. If there is a need to exempt these models, they must be specified individually. + +--- + +## LOGIN_PERSISTENCE + +Default: False + +If true, the lifetime of a user's authentication session will be automatically reset upon each valid request. For example, if [`LOGIN_TIMEOUT`](#login_timeout) is configured to 14 days (the default), and a user whose session is due to expire in five days makes a NetBox request (with a valid session cookie), the session's lifetime will be reset to 14 days. + +Note that enabling this setting causes NetBox to update a user's session in the database (or file, as configured per [`SESSION_FILE_PATH`](#session_file_path)) with each request, which may introduce significant overhead in very active environments. It also permits an active user to remain authenticated to NetBox indefinitely. + +--- + +## LOGIN_REQUIRED + +Default: False + +Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users are permitted to access most data in NetBox but not make any changes. + +--- + +## LOGIN_TIMEOUT + +Default: 1209600 seconds (14 days) + +The lifetime (in seconds) of the authentication cookie issued to a NetBox user upon login. + +--- + +## SESSION_COOKIE_NAME + +Default: `sessionid` + +The name used for the session cookie. See the [Django documentation](https://docs.djangoproject.com/en/stable/ref/settings/#session-cookie-name) for more detail. + +--- + +## SESSION_FILE_PATH + +Default: None + +HTTP session data is used to track authenticated users when they access NetBox. By default, NetBox stores session data in its PostgreSQL database. However, this inhibits authentication to a standby instance of NetBox without write access to the database. Alternatively, a local file path may be specified here and NetBox will store session data as files instead of using the database. Note that the NetBox system user must have read and write permissions to this path. diff --git a/docs/configuration/system.md b/docs/configuration/system.md new file mode 100644 index 000000000..21607e566 --- /dev/null +++ b/docs/configuration/system.md @@ -0,0 +1,178 @@ +# System Parameters + +## BASE_PATH + +Default: None + +The base URL path to use when accessing NetBox. Do not include the scheme or domain name. For example, if installed at https://example.com/netbox/, set: + +```python +BASE_PATH = 'netbox/' +``` + +--- + +## DOCS_ROOT + +Default: `$INSTALL_ROOT/docs/` + +The filesystem path to NetBox's documentation. This is used when presenting context-sensitive documentation in the web UI. By default, this will be the `docs/` directory within the root NetBox installation path. (Set this to `None` to disable the embedded documentation.) + +--- + +## EMAIL + +In order to send email, NetBox needs an email server configured. The following items can be defined within the `EMAIL` configuration parameter: + +* `SERVER` - Hostname or IP address of the email server (use `localhost` if running locally) +* `PORT` - TCP port to use for the connection (default: `25`) +* `USERNAME` - Username with which to authenticate +* `PASSSWORD` - Password with which to authenticate +* `USE_SSL` - Use SSL when connecting to the server (default: `False`) +* `USE_TLS` - Use TLS when connecting to the server (default: `False`) +* `SSL_CERTFILE` - Path to the PEM-formatted SSL certificate file (optional) +* `SSL_KEYFILE` - Path to the PEM-formatted SSL private key file (optional) +* `TIMEOUT` - Amount of time to wait for a connection, in seconds (default: `10`) +* `FROM_EMAIL` - Sender address for emails sent by NetBox + +!!! note + The `USE_SSL` and `USE_TLS` parameters are mutually exclusive. + +Email is sent from NetBox only for critical events or if configured for [logging](#logging). If you would like to test the email server configuration, Django provides a convenient [send_mail()](https://docs.djangoproject.com/en/stable/topics/email/#send-mail) function accessible within the NetBox shell: + +```no-highlight +# python ./manage.py nbshell +>>> from django.core.mail import send_mail +>>> send_mail( + 'Test Email Subject', + 'Test Email Body', + 'noreply-netbox@example.com', + ['users@example.com'], + fail_silently=False +) +``` + +--- + +## HTTP_PROXIES + +Default: None + +A dictionary of HTTP proxies to use for outbound requests originating from NetBox (e.g. when sending webhook requests). Proxies should be specified by schema (HTTP and HTTPS) as per the [Python requests library documentation](https://2.python-requests.org/en/master/user/advanced/). For example: + +```python +HTTP_PROXIES = { + 'http': 'http://10.10.1.10:3128', + 'https': 'http://10.10.1.10:1080', +} +``` + +--- + +## INTERNAL_IPS + +Default: `('127.0.0.1', '::1')` + +A list of IP addresses recognized as internal to the system, used to control the display of debugging output. For +example, the debugging toolbar will be viewable only when a client is accessing NetBox from one of the listed IP +addresses (and [`DEBUG`](#debug) is true). + +--- + +## JINJA2_FILTERS + +Default: `{}` + +A dictionary of custom jinja2 filters with the key being the filter name and the value being a callable. For more information see the [Jinja2 documentation](https://jinja.palletsprojects.com/en/3.1.x/api/#custom-filters). For example: + +```python +def uppercase(x): + return str(x).upper() + +JINJA2_FILTERS = { + 'uppercase': uppercase, +} +``` + +--- + +## LOGGING + +By default, all messages of INFO severity or higher will be logged to the console. Additionally, if [`DEBUG`](#debug) is False and email access has been configured, ERROR and CRITICAL messages will be emailed to the users defined in [`ADMINS`](#admins). + +The Django framework on which NetBox runs allows for the customization of logging format and destination. Please consult the [Django logging documentation](https://docs.djangoproject.com/en/stable/topics/logging/) for more information on configuring this setting. Below is an example which will write all INFO and higher messages to a local file: + +```python +LOGGING = { + 'version': 1, + 'disable_existing_loggers': False, + 'handlers': { + 'file': { + 'level': 'INFO', + 'class': 'logging.FileHandler', + 'filename': '/var/log/netbox.log', + }, + }, + 'loggers': { + 'django': { + 'handlers': ['file'], + 'level': 'INFO', + }, + }, +} +``` + +### Available Loggers + +* `netbox..` - Generic form for model-specific log messages +* `netbox.auth.*` - Authentication events +* `netbox.api.views.*` - Views which handle business logic for the REST API +* `netbox.reports.*` - Report execution (`module.name`) +* `netbox.scripts.*` - Custom script execution (`module.name`) +* `netbox.views.*` - Views which handle business logic for the web UI + +--- + +## MEDIA_ROOT + +Default: $INSTALL_ROOT/netbox/media/ + +The file path to the location where media files (such as image attachments) are stored. By default, this is the `netbox/media/` directory within the base NetBox installation path. + +--- + +## REPORTS_ROOT + +Default: `$INSTALL_ROOT/netbox/reports/` + +The file path to the location where [custom reports](../customization/reports.md) will be kept. By default, this is the `netbox/reports/` directory within the base NetBox installation path. + +--- + +## SCRIPTS_ROOT + +Default: `$INSTALL_ROOT/netbox/scripts/` + +The file path to the location where [custom scripts](../customization/custom-scripts.md) will be kept. By default, this is the `netbox/scripts/` directory within the base NetBox installation path. + +--- + +## STORAGE_BACKEND + +Default: None (local storage) + +The backend storage engine for handling uploaded files (e.g. image attachments). NetBox supports integration with the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) package, which provides backends for several popular file storage services. If not configured, local filesystem storage will be used. + +The configuration parameters for the specified storage backend are defined under the `STORAGE_CONFIG` setting. + +--- + +## STORAGE_CONFIG + +Default: Empty + +A dictionary of configuration parameters for the storage backend configured as `STORAGE_BACKEND`. The specific parameters to be used here are specific to each backend; see the [`django-storages` documentation](https://django-storages.readthedocs.io/en/stable/) for more detail. + +If `STORAGE_BACKEND` is not defined, this setting will be ignored. + +--- diff --git a/docs/customization/custom-validation.md b/docs/customization/custom-validation.md index f88cd309b..30198117f 100644 --- a/docs/customization/custom-validation.md +++ b/docs/customization/custom-validation.md @@ -50,7 +50,7 @@ The `fail()` method may optionally specify a field with which to associate the s ## Assigning Custom Validators -Custom validators are associated with specific NetBox models under the [CUSTOM_VALIDATORS](../configuration/dynamic-settings.md#custom_validators) configuration parameter. There are three manners by which custom validation rules can be defined: +Custom validators are associated with specific NetBox models under the [CUSTOM_VALIDATORS](../configuration/data-validation.md#custom_validators) configuration parameter. There are three manners by which custom validation rules can be defined: 1. Plain JSON mapping (no custom logic) 2. Dotted path to a custom validator class diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index affd39aae..3c7ff7d20 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -2,7 +2,7 @@ ## REST API Integration -When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../configuration/optional-settings.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: +When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: ``` GET /api/dcim/sites/?export=MyTemplateName diff --git a/docs/customization/reports.md b/docs/customization/reports.md index ae4ceb9aa..150c32f40 100644 --- a/docs/customization/reports.md +++ b/docs/customization/reports.md @@ -12,7 +12,7 @@ A NetBox report is a mechanism for validating the integrity of data within NetBo ## Writing Reports -Reports must be saved as files in the [`REPORTS_ROOT`](../configuration/optional-settings.md#reports_root) path (which defaults to `netbox/reports/`). Each file created within this path is considered a separate module. Each module holds one or more reports (Python classes), each of which performs a certain function. The logic of each report is broken into discrete test methods, each of which applies a small portion of the logic comprising the overall test. +Reports must be saved as files in the [`REPORTS_ROOT`](../configuration/system.md#reports_root) path (which defaults to `netbox/reports/`). Each file created within this path is considered a separate module. Each module holds one or more reports (Python classes), each of which performs a certain function. The logic of each report is broken into discrete test methods, each of which applies a small portion of the logic comprising the overall test. !!! warning The reports path includes a file named `__init__.py`, which registers the path as a Python module. Do not delete this file. diff --git a/docs/graphql-api/overview.md b/docs/graphql-api/overview.md index 57dfb22bd..4fc6d2dd8 100644 --- a/docs/graphql-api/overview.md +++ b/docs/graphql-api/overview.md @@ -67,4 +67,4 @@ Authorization: Token $TOKEN ## Disabling the GraphQL API -If not needed, the GraphQL API can be disabled by setting the [`GRAPHQL_ENABLED`](../configuration/dynamic-settings.md#graphql_enabled) configuration parameter to False and restarting NetBox. +If not needed, the GraphQL API can be disabled by setting the [`GRAPHQL_ENABLED`](../configuration/miscellaneous.md#graphql_enabled) configuration parameter to False and restarting NetBox. diff --git a/docs/installation/3-netbox.md b/docs/installation/3-netbox.md index 50b350d3a..7c4a60500 100644 --- a/docs/installation/3-netbox.md +++ b/docs/installation/3-netbox.md @@ -142,7 +142,7 @@ ALLOWED_HOSTS = ['*'] ### DATABASE -This parameter holds the database configuration details. You must define the username and password used when you configured PostgreSQL. If the service is running on a remote host, update the `HOST` and `PORT` parameters accordingly. See the [configuration documentation](../configuration/required-settings.md#database) for more detail on individual parameters. +This parameter holds the database configuration details. You must define the username and password used when you configured PostgreSQL. If the service is running on a remote host, update the `HOST` and `PORT` parameters accordingly. See the [configuration documentation](../configuration/required-parameters.md#database) for more detail on individual parameters. ```python DATABASE = { @@ -157,7 +157,7 @@ DATABASE = { ### REDIS -Redis is a in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. See the [configuration documentation](../configuration/required-settings.md#redis) for more detail on individual parameters. +Redis is a in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. See the [configuration documentation](../configuration/required-parameters.md#redis) for more detail on individual parameters. Note that NetBox requires the specification of two separate Redis databases: `tasks` and `caching`. These may both be provided by the same Redis service, however each should have a unique numeric database ID. @@ -209,7 +209,7 @@ sudo sh -c "echo 'napalm' >> /opt/netbox/local_requirements.txt" ### Remote File Storage -By default, NetBox will use the local filesystem to store uploaded files. To use a remote filesystem, install the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) library and configure your [desired storage backend](../configuration/optional-settings.md#storage_backend) in `configuration.py`. +By default, NetBox will use the local filesystem to store uploaded files. To use a remote filesystem, install the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) library and configure your [desired storage backend](../configuration/system.md#storage_backend) in `configuration.py`. ```no-highlight sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt" diff --git a/docs/installation/6-ldap.md b/docs/installation/6-ldap.md index 281554f75..163ace70d 100644 --- a/docs/installation/6-ldap.md +++ b/docs/installation/6-ldap.md @@ -142,7 +142,7 @@ AUTH_LDAP_CACHE_TIMEOUT = 3600 `systemctl restart netbox` restarts the NetBox service, and initiates any changes made to `ldap_config.py`. If there are syntax errors present, the NetBox process will not spawn an instance, and errors should be logged to `/var/log/messages`. -For troubleshooting LDAP user/group queries, add or merge the following [logging](../configuration/optional-settings.md#logging) configuration to `configuration.py`: +For troubleshooting LDAP user/group queries, add or merge the following [logging](../configuration/system.md#logging) configuration to `configuration.py`: ```python LOGGING = { diff --git a/docs/plugins/development/models.md b/docs/plugins/development/models.md index 6d7075b80..c58621b81 100644 --- a/docs/plugins/development/models.md +++ b/docs/plugins/development/models.md @@ -156,7 +156,7 @@ class StatusChoices(ChoiceSet): key = 'MyModel.status' ``` -To extend or replace the default values for this choice set, a NetBox administrator can then reference it under the [`FIELD_CHOICES`](../../configuration/optional-settings.md#field_choices) configuration parameter. For example, the `status` field on `MyModel` in `my_plugin` would be referenced as: +To extend or replace the default values for this choice set, a NetBox administrator can then reference it under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. For example, the `status` field on `MyModel` in `my_plugin` would be referenced as: ```python FIELD_CHOICES = { diff --git a/docs/release-notes/version-3.0.md b/docs/release-notes/version-3.0.md index 7d6341f44..93ff33d95 100644 --- a/docs/release-notes/version-3.0.md +++ b/docs/release-notes/version-3.0.md @@ -367,7 +367,7 @@ More information about IP ranges is available [in the documentation](../models/i #### Custom Model Validation ([#5963](https://github.com/netbox-community/netbox/issues/5963)) -This release introduces the [`CUSTOM_VALIDATORS`](../configuration/dynamic-settings.md#custom_validators) configuration parameter, which allows administrators to map NetBox models to custom validator classes to enforce custom validation logic. For example, the following configuration requires every site to have a name of at least ten characters and a description: +This release introduces the [`CUSTOM_VALIDATORS`](../configuration/data-validation.md#custom_validators) configuration parameter, which allows administrators to map NetBox models to custom validator classes to enforce custom validation logic. For example, the following configuration requires every site to have a name of at least ten characters and a description: ```python from extras.validators import CustomValidator diff --git a/docs/release-notes/version-3.1.md b/docs/release-notes/version-3.1.md index 27ba4e69e..9dce1dfd4 100644 --- a/docs/release-notes/version-3.1.md +++ b/docs/release-notes/version-3.1.md @@ -313,8 +313,6 @@ Some parameters of NetBox's configuration are now accessible via the admin UI. T Dynamic configuration parameters may also still be defined within `configuration.py`, and the settings defined here take precedence over those defined via the user interface. -For a complete list of supported parameters, please see the [dynamic configuration documentation](../configuration/dynamic-settings.md). - #### First Hop Redundancy Protocol (FHRP) Groups ([#6235](https://github.com/netbox-community/netbox/issues/6235)) A new FHRP group model has been introduced to aid in modeling the configurations of protocols such as HSRP, VRRP, and GLBP. Each FHRP group may be assigned one or more virtual IP addresses, as well as an authentication type and key. Member device and VM interfaces may be associated with one or more FHRP groups, with each assignment receiving a numeric priority designation. diff --git a/docs/release-notes/version-3.2.md b/docs/release-notes/version-3.2.md index c36344912..10ccaeb4d 100644 --- a/docs/release-notes/version-3.2.md +++ b/docs/release-notes/version-3.2.md @@ -267,7 +267,7 @@ Custom field object assignment is fully supported in the REST API, and functions #### Custom Status Choices ([#8054](https://github.com/netbox-community/netbox/issues/8054)) -Custom choices can be now added to most object status fields in NetBox. This is done by defining the [`FIELD_CHOICES`](../configuration/optional-settings.md#field_choices) configuration parameter to map field identifiers to an iterable of custom choices an (optionally) colors. These choices are populated automatically when NetBox initializes. For example, the following configuration will add three custom choices for the site status field, each with a designated color: +Custom choices can be now added to most object status fields in NetBox. This is done by defining the [`FIELD_CHOICES`](../configuration/data-validation.md#field_choices) configuration parameter to map field identifiers to an iterable of custom choices an (optionally) colors. These choices are populated automatically when NetBox initializes. For example, the following configuration will add three custom choices for the site status field, each with a designated color: ```python FIELD_CHOICES = { @@ -291,7 +291,7 @@ FIELD_CHOICES = { #### Improved User Preferences ([#7759](https://github.com/netbox-community/netbox/issues/7759)) -A robust new mechanism for managing user preferences is included in this release. The user preferences form has been improved for better usability, and administrators can now define default preferences for all users with the [`DEFAULT_USER_PREFERENCES`](../configuration/dynamic-settings.md##default_user_preferences) configuration parameter. For example, this can be used to define the columns which appear by default in a table: +A robust new mechanism for managing user preferences is included in this release. The user preferences form has been improved for better usability, and administrators can now define default preferences for all users with the [`DEFAULT_USER_PREFERENCES`](../configuration/default-values.md#default_user_preferences) configuration parameter. For example, this can be used to define the columns which appear by default in a table: ```python DEFAULT_USER_PREFERENCES = { diff --git a/docs/rest-api/authentication.md b/docs/rest-api/authentication.md index 18b6bc4f8..411063338 100644 --- a/docs/rest-api/authentication.md +++ b/docs/rest-api/authentication.md @@ -20,7 +20,7 @@ https://netbox/api/dcim/sites/ } ``` -A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/optional-settings.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response: +A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/security.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response: ``` $ curl https://netbox/api/dcim/sites/ diff --git a/docs/rest-api/overview.md b/docs/rest-api/overview.md index 27a9b6a7e..5fc4f18bb 100644 --- a/docs/rest-api/overview.md +++ b/docs/rest-api/overview.md @@ -308,7 +308,7 @@ Vary: Accept } ``` -The default page is determined by the [`PAGINATE_COUNT`](../configuration/dynamic-settings.md#paginate_count) configuration parameter, which defaults to 50. However, this can be overridden per request by specifying the desired `offset` and `limit` query parameters. For example, if you wish to retrieve a hundred devices at a time, you would make a request for: +The default page is determined by the [`PAGINATE_COUNT`](../configuration/default-values.md#paginate_count) configuration parameter, which defaults to 50. However, this can be overridden per request by specifying the desired `offset` and `limit` query parameters. For example, if you wish to retrieve a hundred devices at a time, you would make a request for: ``` http://netbox/api/dcim/devices/?limit=100 @@ -325,7 +325,7 @@ The response will return devices 1 through 100. The URL provided in the `next` a } ``` -The maximum number of objects that can be returned is limited by the [`MAX_PAGE_SIZE`](../configuration/dynamic-settings.md#max_page_size) configuration parameter, which is 1000 by default. Setting this to `0` or `None` will remove the maximum limit. An API consumer can then pass `?limit=0` to retrieve _all_ matching objects with a single request. +The maximum number of objects that can be returned is limited by the [`MAX_PAGE_SIZE`](../configuration/miscellaneous.md#max_page_size) configuration parameter, which is 1000 by default. Setting this to `0` or `None` will remove the maximum limit. An API consumer can then pass `?limit=0` to retrieve _all_ matching objects with a single request. !!! warning Disabling the page size limit introduces a potential for very resource-intensive requests, since one API request can effectively retrieve an entire table from the database. diff --git a/mkdocs.yml b/mkdocs.yml index 2203b8934..3acb157aa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,11 +72,18 @@ nav: - Populating Data: 'getting-started/populating-data.md' - Configuration: - Configuring NetBox: 'configuration/index.md' - - Required Settings: 'configuration/required-settings.md' - - Optional Settings: 'configuration/optional-settings.md' - - Dynamic Settings: 'configuration/dynamic-settings.md' - - Error Reporting: 'configuration/error-reporting.md' + - Required Parameters: 'configuration/required-parameters.md' + - System: 'configuration/system.md' + - Security: 'configuration/security.md' - Remote Authentication: 'configuration/remote-authentication.md' + - Data & Validation: 'configuration/data-validation.md' + - Default Values: 'configuration/default-values.md' + - Error Reporting: 'configuration/error-reporting.md' + - Plugins: 'configuration/plugins.md' + - NAPALM: 'configuration/napalm.md' + - Date & Time: 'configuration/date-time.md' + - Miscellaneous: 'configuration/miscellaneous.md' + - Development: 'configuration/development.md' - Customization: - Custom Fields: 'customization/custom-fields.md' - Custom Validation: 'customization/custom-validation.md' From 1cd407548813bc959f4959f7009b3d800fe71311 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 29 Jul 2022 16:23:45 -0400 Subject: [PATCH 193/245] Add mermaid flowcharts showing rough data model dependencies --- docs/getting-started/planning.md | 116 ++++++++++++++++++++++--------- mkdocs.yml | 6 +- 2 files changed, 87 insertions(+), 35 deletions(-) diff --git a/docs/getting-started/planning.md b/docs/getting-started/planning.md index 00640ca44..5c431a4d2 100644 --- a/docs/getting-started/planning.md +++ b/docs/getting-started/planning.md @@ -50,38 +50,86 @@ When starting with a completely empty database, it might not be immediately clea Below is the (rough) recommended order in which NetBox objects should be created or imported. While it is not required to follow this exact order, doing so will help ensure the smoothest workflow. - +1. Tenant groups and tenants +2. Regions, site groups, sites, and locations +3. Rack roles and racks +4. Manufacturers, device types, and module types +5. Platforms and device roles +6. Devices and modules +7. Providers and provider networks +8. Circuit types and circuits +9. Wireless LAN groups and wireless LANs +10. Route targets and VRFs +11. RIRs and aggregates +12. IP/VLAN roles +13. Prefixes, IP ranges, and IP addresses +14. VLAN groups and VLANs +15. Cluster types, cluster groups, and clusters +16. Virtual machines and VM interfaces -1. Tenant groups -2. Tenants -3. Regions and/or site groups -4. Sites -5. Locations -6. Rack roles -7. Racks -8. Platforms -9. Manufacturers -10. Device types -11. Module types -12. Device roles -13. Devices -14. Providers -15. Provider networks -16. Circuit types -17. Circuits -18. Wireless LAN groups -19. Wireless LANs & links -20. Route targets -21. VRFs -22. RIRs -23. Aggregates -24. IP/VLAN roles -25. Prefixes -26. IP ranges & addresses -27. VLAN groups -28. VLANs -29. Services -30. Clusters -31. Virtual machines -32. VM interfaces -33. L2 VPNs +This is not a comprehensive list, but should suffice for the initial data imports. Beyond these, it the order in which objects are added doesn't have much if any impact. + +The graphs below illustrate some of the core dependencies among different models in NetBox for your reference. + +!!! note "Self-Nesting Models" + Each model in the graphs below which show a looping arrow pointing back to itself can be nested in a recursive hierarchy. For example, you can have regions representing both countries and cities, with the latter nested underneath the former. + +### Tenancy + +```mermaid +flowchart TD + TenantGroup --> TenantGroup + TenantGroup --> Tenant + Tenant --> Site & Device & Prefix & VLAN & ... +``` + +### Sites, Racks, and Devices + +```mermaid +flowchart TD + Region --> Region + SiteGroup --> SiteGroup + DeviceRole & Platform --> Device + Region & SiteGroup --> Site + Site --> Location & Device + Location --> Location + Location --> Rack & Device + Rack --> Device + Manufacturer --> DeviceType & ModuleType + DeviceType --> Device + Device & ModuleType ---> Module + Device & Module --> Interface +``` + +### VRFs, Prefixes, IP Addresses, and VLANs + +```mermaid +flowchart TD + VLANGroup --> VLAN + Role --> VLAN & IPRange & Prefix + RIR --> Aggregate + RouteTarget --> VRF + Aggregate & VRF --> Prefix + VRF --> IPRange & IPAddress + Prefix --> VLAN & IPRange & IPAddress +``` + +### Circuits + +```mermaid +flowchart TD + Provider & CircuitType --> Circuit + Provider --> ProviderNetwork + Circuit --> CircuitTermination +``` + +### Clusters and Virtual Machines + +```mermaid +flowchart TD + ClusterGroup & ClusterType --> Cluster + Cluster --> VirtualMachine + Site --> Cluster & VirtualMachine + Device & Platform --> VirtualMachine + VirtualMachine --> VMInterface +``` diff --git a/mkdocs.yml b/mkdocs.yml index 3acb157aa..4c5279127 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,7 +53,11 @@ markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true nav: From 6904666e2a6e9be451be3acbdd669af012aec45b Mon Sep 17 00:00:00 2001 From: Kim Johansson Date: Sat, 30 Jul 2022 01:18:30 +0200 Subject: [PATCH 194/245] Remove deprecated usage of prefetch_related Fixes #9699 --- netbox/circuits/views.py | 15 ++++-- netbox/dcim/views.py | 90 +++++++++++++++++----------------- netbox/extras/views.py | 4 +- netbox/ipam/views.py | 61 +++++++++++------------ netbox/tenancy/views.py | 10 ++-- netbox/virtualization/views.py | 15 +++--- 6 files changed, 101 insertions(+), 94 deletions(-) diff --git a/netbox/circuits/views.py b/netbox/circuits/views.py index 11f211b27..423bd67d6 100644 --- a/netbox/circuits/views.py +++ b/netbox/circuits/views.py @@ -30,7 +30,8 @@ class ProviderView(generic.ObjectView): circuits = Circuit.objects.restrict(request.user, 'view').filter( provider=instance ).prefetch_related( - 'type', 'tenant', 'tenant__group', 'terminations__site' + 'tenant__group', 'termination_a__site', 'termination_z__site', + 'termination_a__provider_network', 'termination_z__provider_network', ) circuits_table = tables.CircuitTable(circuits, user=request.user, exclude=('provider',)) circuits_table.configure(request) @@ -91,7 +92,8 @@ class ProviderNetworkView(generic.ObjectView): Q(termination_a__provider_network=instance.pk) | Q(termination_z__provider_network=instance.pk) ).prefetch_related( - 'type', 'tenant', 'tenant__group', 'terminations__site' + 'tenant__group', 'termination_a__site', 'termination_z__site', + 'termination_a__provider_network', 'termination_z__provider_network', ) circuits_table = tables.CircuitTable(circuits, user=request.user) circuits_table.configure(request) @@ -192,7 +194,8 @@ class CircuitTypeBulkDeleteView(generic.BulkDeleteView): class CircuitListView(generic.ObjectListView): queryset = Circuit.objects.prefetch_related( - 'provider', 'type', 'tenant', 'tenant__group', 'termination_a', 'termination_z' + 'tenant__group', 'termination_a__site', 'termination_z__site', + 'termination_a__provider_network', 'termination_z__provider_network', ) filterset = filtersets.CircuitFilterSet filterset_form = forms.CircuitFilterForm @@ -220,7 +223,8 @@ class CircuitBulkImportView(generic.BulkImportView): class CircuitBulkEditView(generic.BulkEditView): queryset = Circuit.objects.prefetch_related( - 'provider', 'type', 'tenant', 'terminations' + 'termination_a__site', 'termination_z__site', + 'termination_a__provider_network', 'termination_z__provider_network', ) filterset = filtersets.CircuitFilterSet table = tables.CircuitTable @@ -229,7 +233,8 @@ class CircuitBulkEditView(generic.BulkEditView): class CircuitBulkDeleteView(generic.BulkDeleteView): queryset = Circuit.objects.prefetch_related( - 'provider', 'type', 'tenant', 'terminations' + 'termination_a__site', 'termination_z__site', + 'termination_a__provider_network', 'termination_z__provider_network', ) filterset = filtersets.CircuitFilterSet table = tables.CircuitTable diff --git a/netbox/dcim/views.py b/netbox/dcim/views.py index 12e070e70..6daecb3a6 100644 --- a/netbox/dcim/views.py +++ b/netbox/dcim/views.py @@ -324,7 +324,7 @@ class SiteListView(generic.ObjectListView): class SiteView(generic.ObjectView): - queryset = Site.objects.prefetch_related('region', 'tenant__group') + queryset = Site.objects.prefetch_related('tenant__group') def get_extra_context(self, request, instance): stats = { @@ -359,7 +359,7 @@ class SiteView(generic.ObjectView): site=instance, position__isnull=True, parent_bay__isnull=True - ).prefetch_related('device_type__manufacturer') + ).prefetch_related('device_type__manufacturer', 'parent_bay', 'device_role') asns = ASN.objects.restrict(request.user, 'view').filter(sites=instance) asn_count = asns.count() @@ -391,14 +391,14 @@ class SiteBulkImportView(generic.BulkImportView): class SiteBulkEditView(generic.BulkEditView): - queryset = Site.objects.prefetch_related('region', 'tenant') + queryset = Site.objects.all() filterset = filtersets.SiteFilterSet table = tables.SiteTable form = forms.SiteBulkEditForm class SiteBulkDeleteView(generic.BulkDeleteView): - queryset = Site.objects.prefetch_related('region', 'tenant') + queryset = Site.objects.all() filterset = filtersets.SiteFilterSet table = tables.SiteTable @@ -454,7 +454,7 @@ class LocationView(generic.ObjectView): location=instance, position__isnull=True, parent_bay__isnull=True - ).prefetch_related('device_type__manufacturer') + ).prefetch_related('device_type__manufacturer', 'parent_bay', 'device_role') return { 'rack_count': rack_count, @@ -572,7 +572,7 @@ class RackRoleBulkDeleteView(generic.BulkDeleteView): # class RackListView(generic.ObjectListView): - queryset = Rack.objects.prefetch_related('devices__device_type').annotate( + queryset = Rack.objects.annotate( device_count=count_related(Device, 'rack') ) filterset = filtersets.RackFilterSet @@ -631,7 +631,7 @@ class RackView(generic.ObjectView): rack=instance, position__isnull=True, parent_bay__isnull=True - ).prefetch_related('device_type__manufacturer') + ).prefetch_related('device_type__manufacturer', 'parent_bay', 'device_role') peer_racks = Rack.objects.restrict(request.user, 'view').filter(site=instance.site) @@ -682,14 +682,14 @@ class RackBulkImportView(generic.BulkImportView): class RackBulkEditView(generic.BulkEditView): - queryset = Rack.objects.prefetch_related('site', 'location', 'tenant', 'role') + queryset = Rack.objects.all() filterset = filtersets.RackFilterSet table = tables.RackTable form = forms.RackBulkEditForm class RackBulkDeleteView(generic.BulkDeleteView): - queryset = Rack.objects.prefetch_related('site', 'location', 'tenant', 'role') + queryset = Rack.objects.all() filterset = filtersets.RackFilterSet table = tables.RackTable @@ -706,7 +706,7 @@ class RackReservationListView(generic.ObjectListView): class RackReservationView(generic.ObjectView): - queryset = RackReservation.objects.prefetch_related('rack') + queryset = RackReservation.objects.all() class RackReservationEditView(generic.ObjectEditView): @@ -742,14 +742,14 @@ class RackReservationImportView(generic.BulkImportView): class RackReservationBulkEditView(generic.BulkEditView): - queryset = RackReservation.objects.prefetch_related('rack', 'user') + queryset = RackReservation.objects.all() filterset = filtersets.RackReservationFilterSet table = tables.RackReservationTable form = forms.RackReservationBulkEditForm class RackReservationBulkDeleteView(generic.BulkDeleteView): - queryset = RackReservation.objects.prefetch_related('rack', 'user') + queryset = RackReservation.objects.all() filterset = filtersets.RackReservationFilterSet table = tables.RackReservationTable @@ -831,7 +831,7 @@ class ManufacturerBulkDeleteView(generic.BulkDeleteView): # class DeviceTypeListView(generic.ObjectListView): - queryset = DeviceType.objects.prefetch_related('manufacturer').annotate( + queryset = DeviceType.objects.annotate( instance_count=count_related(Device, 'device_type') ) filterset = filtersets.DeviceTypeFilterSet @@ -840,7 +840,7 @@ class DeviceTypeListView(generic.ObjectListView): class DeviceTypeView(generic.ObjectView): - queryset = DeviceType.objects.prefetch_related('manufacturer') + queryset = DeviceType.objects.all() def get_extra_context(self, request, instance): instance_count = Device.objects.restrict(request.user).filter(device_type=instance).count() @@ -964,7 +964,7 @@ class DeviceTypeImportView(generic.ObjectImportView): class DeviceTypeBulkEditView(generic.BulkEditView): - queryset = DeviceType.objects.prefetch_related('manufacturer').annotate( + queryset = DeviceType.objects.annotate( instance_count=count_related(Device, 'device_type') ) filterset = filtersets.DeviceTypeFilterSet @@ -973,7 +973,7 @@ class DeviceTypeBulkEditView(generic.BulkEditView): class DeviceTypeBulkDeleteView(generic.BulkDeleteView): - queryset = DeviceType.objects.prefetch_related('manufacturer').annotate( + queryset = DeviceType.objects.annotate( instance_count=count_related(Device, 'device_type') ) filterset = filtersets.DeviceTypeFilterSet @@ -985,7 +985,7 @@ class DeviceTypeBulkDeleteView(generic.BulkDeleteView): # class ModuleTypeListView(generic.ObjectListView): - queryset = ModuleType.objects.prefetch_related('manufacturer').annotate( + queryset = ModuleType.objects.annotate( instance_count=count_related(Module, 'module_type') ) filterset = filtersets.ModuleTypeFilterSet @@ -994,7 +994,7 @@ class ModuleTypeListView(generic.ObjectListView): class ModuleTypeView(generic.ObjectView): - queryset = ModuleType.objects.prefetch_related('manufacturer') + queryset = ModuleType.objects.all() def get_extra_context(self, request, instance): instance_count = Module.objects.restrict(request.user).filter(module_type=instance).count() @@ -1091,7 +1091,7 @@ class ModuleTypeImportView(generic.ObjectImportView): class ModuleTypeBulkEditView(generic.BulkEditView): - queryset = ModuleType.objects.prefetch_related('manufacturer').annotate( + queryset = ModuleType.objects.annotate( instance_count=count_related(Module, 'module_type') ) filterset = filtersets.ModuleTypeFilterSet @@ -1100,7 +1100,7 @@ class ModuleTypeBulkEditView(generic.BulkEditView): class ModuleTypeBulkDeleteView(generic.BulkDeleteView): - queryset = ModuleType.objects.prefetch_related('manufacturer').annotate( + queryset = ModuleType.objects.annotate( instance_count=count_related(Module, 'module_type') ) filterset = filtersets.ModuleTypeFilterSet @@ -1611,9 +1611,7 @@ class DeviceListView(generic.ObjectListView): class DeviceView(generic.ObjectView): - queryset = Device.objects.prefetch_related( - 'site__region', 'location', 'rack', 'tenant__group', 'device_role', 'platform', 'primary_ip4', 'primary_ip6' - ) + queryset = Device.objects.all() def get_extra_context(self, request, instance): # VirtualChassis members @@ -1790,14 +1788,14 @@ class ChildDeviceBulkImportView(generic.BulkImportView): class DeviceBulkEditView(generic.BulkEditView): - queryset = Device.objects.prefetch_related('tenant', 'site', 'rack', 'device_role', 'device_type__manufacturer') + queryset = Device.objects.prefetch_related('device_type__manufacturer') filterset = filtersets.DeviceFilterSet table = tables.DeviceTable form = forms.DeviceBulkEditForm class DeviceBulkDeleteView(generic.BulkDeleteView): - queryset = Device.objects.prefetch_related('tenant', 'site', 'rack', 'device_role', 'device_type__manufacturer') + queryset = Device.objects.prefetch_related('device_type__manufacturer') filterset = filtersets.DeviceFilterSet table = tables.DeviceTable @@ -1807,7 +1805,7 @@ class DeviceBulkDeleteView(generic.BulkDeleteView): # class ModuleListView(generic.ObjectListView): - queryset = Module.objects.prefetch_related('device', 'module_type__manufacturer') + queryset = Module.objects.prefetch_related('module_type__manufacturer') filterset = filtersets.ModuleFilterSet filterset_form = forms.ModuleFilterForm table = tables.ModuleTable @@ -1833,14 +1831,14 @@ class ModuleBulkImportView(generic.BulkImportView): class ModuleBulkEditView(generic.BulkEditView): - queryset = Module.objects.prefetch_related('device', 'module_type__manufacturer') + queryset = Module.objects.prefetch_related('module_type__manufacturer') filterset = filtersets.ModuleFilterSet table = tables.ModuleTable form = forms.ModuleBulkEditForm class ModuleBulkDeleteView(generic.BulkDeleteView): - queryset = Module.objects.prefetch_related('device', 'module_type__manufacturer') + queryset = Module.objects.prefetch_related('module_type__manufacturer') filterset = filtersets.ModuleFilterSet table = tables.ModuleTable @@ -2566,7 +2564,7 @@ class InventoryItemBulkImportView(generic.BulkImportView): class InventoryItemBulkEditView(generic.BulkEditView): - queryset = InventoryItem.objects.prefetch_related('device', 'manufacturer', 'role') + queryset = InventoryItem.objects.all() filterset = filtersets.InventoryItemFilterSet table = tables.InventoryItemTable form = forms.InventoryItemBulkEditForm @@ -2577,7 +2575,7 @@ class InventoryItemBulkRenameView(generic.BulkRenameView): class InventoryItemBulkDeleteView(generic.BulkDeleteView): - queryset = InventoryItem.objects.prefetch_related('device', 'manufacturer', 'role') + queryset = InventoryItem.objects.all() table = tables.InventoryItemTable template_name = 'dcim/inventoryitem_bulk_delete.html' @@ -2867,14 +2865,20 @@ class CableBulkImportView(generic.BulkImportView): class CableBulkEditView(generic.BulkEditView): - queryset = Cable.objects.prefetch_related('terminations') + queryset = Cable.objects.prefetch_related( + 'terminations__termination', 'terminations___device', 'terminations___rack', 'terminations___location', + 'terminations___site', + ) filterset = filtersets.CableFilterSet table = tables.CableTable form = forms.CableBulkEditForm class CableBulkDeleteView(generic.BulkDeleteView): - queryset = Cable.objects.prefetch_related('terminations') + queryset = Cable.objects.prefetch_related( + 'terminations__termination', 'terminations___device', 'terminations___rack', 'terminations___location', + 'terminations___site', + ) filterset = filtersets.CableFilterSet table = tables.CableTable @@ -2930,7 +2934,7 @@ class InterfaceConnectionsListView(generic.ObjectListView): # class VirtualChassisListView(generic.ObjectListView): - queryset = VirtualChassis.objects.prefetch_related('master').annotate( + queryset = VirtualChassis.objects.annotate( member_count=count_related(Device, 'virtual_chassis') ) table = tables.VirtualChassisTable @@ -3158,9 +3162,7 @@ class VirtualChassisBulkDeleteView(generic.BulkDeleteView): # class PowerPanelListView(generic.ObjectListView): - queryset = PowerPanel.objects.prefetch_related( - 'site', 'location' - ).annotate( + queryset = PowerPanel.objects.annotate( powerfeed_count=count_related(PowerFeed, 'power_panel') ) filterset = filtersets.PowerPanelFilterSet @@ -3169,10 +3171,10 @@ class PowerPanelListView(generic.ObjectListView): class PowerPanelView(generic.ObjectView): - queryset = PowerPanel.objects.prefetch_related('site', 'location') + queryset = PowerPanel.objects.all() def get_extra_context(self, request, instance): - power_feeds = PowerFeed.objects.restrict(request.user).filter(power_panel=instance).prefetch_related('rack') + power_feeds = PowerFeed.objects.restrict(request.user).filter(power_panel=instance) powerfeed_table = tables.PowerFeedTable( data=power_feeds, orderable=False @@ -3202,16 +3204,14 @@ class PowerPanelBulkImportView(generic.BulkImportView): class PowerPanelBulkEditView(generic.BulkEditView): - queryset = PowerPanel.objects.prefetch_related('site', 'location') + queryset = PowerPanel.objects.all() filterset = filtersets.PowerPanelFilterSet table = tables.PowerPanelTable form = forms.PowerPanelBulkEditForm class PowerPanelBulkDeleteView(generic.BulkDeleteView): - queryset = PowerPanel.objects.prefetch_related( - 'site', 'location' - ).annotate( + queryset = PowerPanel.objects.annotate( powerfeed_count=count_related(PowerFeed, 'power_panel') ) filterset = filtersets.PowerPanelFilterSet @@ -3230,7 +3230,7 @@ class PowerFeedListView(generic.ObjectListView): class PowerFeedView(generic.ObjectView): - queryset = PowerFeed.objects.prefetch_related('power_panel', 'rack') + queryset = PowerFeed.objects.all() class PowerFeedEditView(generic.ObjectEditView): @@ -3249,7 +3249,7 @@ class PowerFeedBulkImportView(generic.BulkImportView): class PowerFeedBulkEditView(generic.BulkEditView): - queryset = PowerFeed.objects.prefetch_related('power_panel', 'rack') + queryset = PowerFeed.objects.all() filterset = filtersets.PowerFeedFilterSet table = tables.PowerFeedTable form = forms.PowerFeedBulkEditForm @@ -3260,6 +3260,6 @@ class PowerFeedBulkDisconnectView(BulkDisconnectView): class PowerFeedBulkDeleteView(generic.BulkDeleteView): - queryset = PowerFeed.objects.prefetch_related('power_panel', 'rack') + queryset = PowerFeed.objects.all() filterset = filtersets.PowerFeedFilterSet table = tables.PowerFeedTable diff --git a/netbox/extras/views.py b/netbox/extras/views.py index bb99536c3..5b589c181 100644 --- a/netbox/extras/views.py +++ b/netbox/extras/views.py @@ -492,14 +492,14 @@ class JournalEntryDeleteView(generic.ObjectDeleteView): class JournalEntryBulkEditView(generic.BulkEditView): - queryset = JournalEntry.objects.prefetch_related('created_by') + queryset = JournalEntry.objects.all() filterset = filtersets.JournalEntryFilterSet table = tables.JournalEntryTable form = forms.JournalEntryBulkEditForm class JournalEntryBulkDeleteView(generic.BulkDeleteView): - queryset = JournalEntry.objects.prefetch_related('created_by') + queryset = JournalEntry.objects.all() filterset = filtersets.JournalEntryFilterSet table = tables.JournalEntryTable diff --git a/netbox/ipam/views.py b/netbox/ipam/views.py index 72b223b55..880ddb83b 100644 --- a/netbox/ipam/views.py +++ b/netbox/ipam/views.py @@ -40,11 +40,11 @@ class VRFView(generic.ObjectView): ipaddress_count = IPAddress.objects.restrict(request.user, 'view').filter(vrf=instance).count() import_targets_table = tables.RouteTargetTable( - instance.import_targets.prefetch_related('tenant'), + instance.import_targets.all(), orderable=False ) export_targets_table = tables.RouteTargetTable( - instance.export_targets.prefetch_related('tenant'), + instance.export_targets.all(), orderable=False ) @@ -72,14 +72,14 @@ class VRFBulkImportView(generic.BulkImportView): class VRFBulkEditView(generic.BulkEditView): - queryset = VRF.objects.prefetch_related('tenant') + queryset = VRF.objects.all() filterset = filtersets.VRFFilterSet table = tables.VRFTable form = forms.VRFBulkEditForm class VRFBulkDeleteView(generic.BulkDeleteView): - queryset = VRF.objects.prefetch_related('tenant') + queryset = VRF.objects.all() filterset = filtersets.VRFFilterSet table = tables.VRFTable @@ -100,11 +100,11 @@ class RouteTargetView(generic.ObjectView): def get_extra_context(self, request, instance): importing_vrfs_table = tables.VRFTable( - instance.importing_vrfs.prefetch_related('tenant'), + instance.importing_vrfs.all(), orderable=False ) exporting_vrfs_table = tables.VRFTable( - instance.exporting_vrfs.prefetch_related('tenant'), + instance.exporting_vrfs.all(), orderable=False ) @@ -130,14 +130,14 @@ class RouteTargetBulkImportView(generic.BulkImportView): class RouteTargetBulkEditView(generic.BulkEditView): - queryset = RouteTarget.objects.prefetch_related('tenant') + queryset = RouteTarget.objects.all() filterset = filtersets.RouteTargetFilterSet table = tables.RouteTargetTable form = forms.RouteTargetBulkEditForm class RouteTargetBulkDeleteView(generic.BulkDeleteView): - queryset = RouteTarget.objects.prefetch_related('tenant') + queryset = RouteTarget.objects.all() filterset = filtersets.RouteTargetFilterSet table = tables.RouteTargetTable @@ -334,14 +334,14 @@ class AggregateBulkImportView(generic.BulkImportView): class AggregateBulkEditView(generic.BulkEditView): - queryset = Aggregate.objects.prefetch_related('rir') + queryset = Aggregate.objects.all() filterset = filtersets.AggregateFilterSet table = tables.AggregateTable form = forms.AggregateBulkEditForm class AggregateBulkDeleteView(generic.BulkDeleteView): - queryset = Aggregate.objects.prefetch_related('rir') + queryset = Aggregate.objects.all() filterset = filtersets.AggregateFilterSet table = tables.AggregateTable @@ -417,7 +417,7 @@ class PrefixListView(generic.ObjectListView): class PrefixView(generic.ObjectView): - queryset = Prefix.objects.prefetch_related('vrf', 'site__region', 'tenant__group', 'vlan__group', 'role') + queryset = Prefix.objects.all() def get_extra_context(self, request, instance): try: @@ -433,7 +433,7 @@ class PrefixView(generic.ObjectView): ).filter( prefix__net_contains=str(instance.prefix) ).prefetch_related( - 'site', 'role', 'tenant' + 'site', 'role', 'tenant', 'vlan', ) parent_prefix_table = tables.PrefixTable( list(parent_prefixes), @@ -447,7 +447,7 @@ class PrefixView(generic.ObjectView): ).exclude( pk=instance.pk ).prefetch_related( - 'site', 'role' + 'site', 'role', 'tenant', 'vlan', ) duplicate_prefix_table = tables.PrefixTable( list(duplicate_prefixes), @@ -500,7 +500,7 @@ class PrefixIPRangesView(generic.ObjectChildrenView): def get_children(self, request, parent): return parent.get_child_ranges().restrict(request.user, 'view').prefetch_related( - 'vrf', 'role', 'tenant', 'tenant__group', + 'tenant__group', ) def get_extra_context(self, request, instance): @@ -519,7 +519,7 @@ class PrefixIPAddressesView(generic.ObjectChildrenView): template_name = 'ipam/prefix/ip_addresses.html' def get_children(self, request, parent): - return parent.get_child_ips().restrict(request.user, 'view').prefetch_related('vrf', 'tenant') + return parent.get_child_ips().restrict(request.user, 'view').prefetch_related('vrf', 'tenant', 'tenant__group') def prep_table_data(self, request, queryset, parent): show_available = bool(request.GET.get('show_available', 'true') == 'true') @@ -552,14 +552,14 @@ class PrefixBulkImportView(generic.BulkImportView): class PrefixBulkEditView(generic.BulkEditView): - queryset = Prefix.objects.prefetch_related('site', 'vrf__tenant', 'tenant', 'vlan', 'role') + queryset = Prefix.objects.prefetch_related('vrf__tenant') filterset = filtersets.PrefixFilterSet table = tables.PrefixTable form = forms.PrefixBulkEditForm class PrefixBulkDeleteView(generic.BulkDeleteView): - queryset = Prefix.objects.prefetch_related('site', 'vrf__tenant', 'tenant', 'vlan', 'role') + queryset = Prefix.objects.prefetch_related('vrf__tenant') filterset = filtersets.PrefixFilterSet table = tables.PrefixTable @@ -611,14 +611,14 @@ class IPRangeBulkImportView(generic.BulkImportView): class IPRangeBulkEditView(generic.BulkEditView): - queryset = IPRange.objects.prefetch_related('vrf', 'tenant') + queryset = IPRange.objects.all() filterset = filtersets.IPRangeFilterSet table = tables.IPRangeTable form = forms.IPRangeBulkEditForm class IPRangeBulkDeleteView(generic.BulkDeleteView): - queryset = IPRange.objects.prefetch_related('vrf', 'tenant') + queryset = IPRange.objects.all() filterset = filtersets.IPRangeFilterSet table = tables.IPRangeTable @@ -789,14 +789,14 @@ class IPAddressBulkImportView(generic.BulkImportView): class IPAddressBulkEditView(generic.BulkEditView): - queryset = IPAddress.objects.prefetch_related('vrf__tenant', 'tenant') + queryset = IPAddress.objects.prefetch_related('vrf__tenant') filterset = filtersets.IPAddressFilterSet table = tables.IPAddressTable form = forms.IPAddressBulkEditForm class IPAddressBulkDeleteView(generic.BulkDeleteView): - queryset = IPAddress.objects.prefetch_related('vrf__tenant', 'tenant') + queryset = IPAddress.objects.prefetch_related('vrf__tenant') filterset = filtersets.IPAddressFilterSet table = tables.IPAddressTable @@ -819,7 +819,8 @@ class VLANGroupView(generic.ObjectView): def get_extra_context(self, request, instance): vlans = VLAN.objects.restrict(request.user, 'view').filter(group=instance).prefetch_related( - Prefetch('prefixes', queryset=Prefix.objects.restrict(request.user)) + Prefetch('prefixes', queryset=Prefix.objects.restrict(request.user)), + 'tenant', 'site', 'role', ).order_by('vid') vlans_count = vlans.count() vlans = add_available_vlans(vlans, vlan_group=instance) @@ -894,7 +895,7 @@ class FHRPGroupView(generic.ObjectView): def get_extra_context(self, request, instance): # Get assigned IP addresses ipaddress_table = tables.AssignedIPAddressesTable( - data=instance.ip_addresses.restrict(request.user, 'view').prefetch_related('vrf', 'tenant'), + data=instance.ip_addresses.restrict(request.user, 'view'), orderable=False ) @@ -984,11 +985,11 @@ class VLANListView(generic.ObjectListView): class VLANView(generic.ObjectView): - queryset = VLAN.objects.prefetch_related('site__region', 'tenant__group', 'role') + queryset = VLAN.objects.all() def get_extra_context(self, request, instance): prefixes = Prefix.objects.restrict(request.user, 'view').filter(vlan=instance).prefetch_related( - 'vrf', 'site', 'role' + 'vrf', 'site', 'role', 'tenant' ) prefix_table = tables.PrefixTable(list(prefixes), exclude=('vlan', 'utilization'), orderable=False) @@ -1046,14 +1047,14 @@ class VLANBulkImportView(generic.BulkImportView): class VLANBulkEditView(generic.BulkEditView): - queryset = VLAN.objects.prefetch_related('site', 'group', 'tenant', 'role') + queryset = VLAN.objects.all() filterset = filtersets.VLANFilterSet table = tables.VLANTable form = forms.VLANBulkEditForm class VLANBulkDeleteView(generic.BulkDeleteView): - queryset = VLAN.objects.prefetch_related('site', 'group', 'tenant', 'role') + queryset = VLAN.objects.all() filterset = filtersets.VLANFilterSet table = tables.VLANTable @@ -1106,14 +1107,14 @@ class ServiceTemplateBulkDeleteView(generic.BulkDeleteView): # class ServiceListView(generic.ObjectListView): - queryset = Service.objects.all() + queryset = Service.objects.prefetch_related('device', 'virtual_machine') filterset = filtersets.ServiceFilterSet filterset_form = forms.ServiceFilterForm table = tables.ServiceTable class ServiceView(generic.ObjectView): - queryset = Service.objects.prefetch_related('ipaddresses') + queryset = Service.objects.all() class ServiceCreateView(generic.ObjectEditView): @@ -1123,7 +1124,7 @@ class ServiceCreateView(generic.ObjectEditView): class ServiceEditView(generic.ObjectEditView): - queryset = Service.objects.prefetch_related('ipaddresses') + queryset = Service.objects.all() form = forms.ServiceForm template_name = 'ipam/service_edit.html' diff --git a/netbox/tenancy/views.py b/netbox/tenancy/views.py index 07a25b5a4..9a2fe6ab9 100644 --- a/netbox/tenancy/views.py +++ b/netbox/tenancy/views.py @@ -95,7 +95,7 @@ class TenantListView(generic.ObjectListView): class TenantView(generic.ObjectView): - queryset = Tenant.objects.prefetch_related('group') + queryset = Tenant.objects.all() def get_extra_context(self, request, instance): stats = { @@ -140,14 +140,14 @@ class TenantBulkImportView(generic.BulkImportView): class TenantBulkEditView(generic.BulkEditView): - queryset = Tenant.objects.prefetch_related('group') + queryset = Tenant.objects.all() filterset = filtersets.TenantFilterSet table = tables.TenantTable form = forms.TenantBulkEditForm class TenantBulkDeleteView(generic.BulkDeleteView): - queryset = Tenant.objects.prefetch_related('group') + queryset = Tenant.objects.all() filterset = filtersets.TenantFilterSet table = tables.TenantTable @@ -337,14 +337,14 @@ class ContactBulkImportView(generic.BulkImportView): class ContactBulkEditView(generic.BulkEditView): - queryset = Contact.objects.prefetch_related('group') + queryset = Contact.objects.all() filterset = filtersets.ContactFilterSet table = tables.ContactTable form = forms.ContactBulkEditForm class ContactBulkDeleteView(generic.BulkDeleteView): - queryset = Contact.objects.prefetch_related('group') + queryset = Contact.objects.all() filterset = filtersets.ContactFilterSet table = tables.ContactTable diff --git a/netbox/virtualization/views.py b/netbox/virtualization/views.py index 4cd7da30d..5b26f8503 100644 --- a/netbox/virtualization/views.py +++ b/netbox/virtualization/views.py @@ -209,14 +209,14 @@ class ClusterBulkImportView(generic.BulkImportView): class ClusterBulkEditView(generic.BulkEditView): - queryset = Cluster.objects.prefetch_related('type', 'group', 'site') + queryset = Cluster.objects.all() filterset = filtersets.ClusterFilterSet table = tables.ClusterTable form = forms.ClusterBulkEditForm class ClusterBulkDeleteView(generic.BulkDeleteView): - queryset = Cluster.objects.prefetch_related('type', 'group', 'site') + queryset = Cluster.objects.all() filterset = filtersets.ClusterFilterSet table = tables.ClusterTable @@ -308,7 +308,7 @@ class ClusterRemoveDevicesView(generic.ObjectEditView): # class VirtualMachineListView(generic.ObjectListView): - queryset = VirtualMachine.objects.all() + queryset = VirtualMachine.objects.prefetch_related('primary_ip4', 'primary_ip6') filterset = filtersets.VirtualMachineFilterSet filterset_form = forms.VirtualMachineFilterForm table = tables.VirtualMachineTable @@ -334,7 +334,8 @@ class VirtualMachineView(generic.ObjectView): services = Service.objects.restrict(request.user, 'view').filter( virtual_machine=instance ).prefetch_related( - Prefetch('ipaddresses', queryset=IPAddress.objects.restrict(request.user)) + Prefetch('ipaddresses', queryset=IPAddress.objects.restrict(request.user)), + 'virtual_machine' ) return { @@ -383,14 +384,14 @@ class VirtualMachineBulkImportView(generic.BulkImportView): class VirtualMachineBulkEditView(generic.BulkEditView): - queryset = VirtualMachine.objects.prefetch_related('cluster', 'tenant', 'role') + queryset = VirtualMachine.objects.prefetch_related('primary_ip4', 'primary_ip6') filterset = filtersets.VirtualMachineFilterSet table = tables.VirtualMachineTable form = forms.VirtualMachineBulkEditForm class VirtualMachineBulkDeleteView(generic.BulkDeleteView): - queryset = VirtualMachine.objects.prefetch_related('cluster', 'tenant', 'role') + queryset = VirtualMachine.objects.prefetch_related('primary_ip4', 'primary_ip6') filterset = filtersets.VirtualMachineFilterSet table = tables.VirtualMachineTable @@ -413,7 +414,7 @@ class VMInterfaceView(generic.ObjectView): def get_extra_context(self, request, instance): # Get assigned IP addresses ipaddress_table = AssignedIPAddressesTable( - data=instance.ip_addresses.restrict(request.user, 'view').prefetch_related('vrf', 'tenant'), + data=instance.ip_addresses.restrict(request.user, 'view'), orderable=False ) From 262a0cf397e1bf2cee4d11567b747c163161a838 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 1 Aug 2022 13:29:39 -0400 Subject: [PATCH 195/245] Fixes #9789: Fix rendering of cable traces ending at provider networks --- docs/release-notes/version-3.3.md | 1 + netbox/dcim/api/views.py | 18 +++++++++--------- netbox/dcim/models/device_components.py | 11 +++++++---- netbox/dcim/svg/cables.py | 6 ++++-- 4 files changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 68cff0547..e30ff011c 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -104,6 +104,7 @@ Custom field UI visibility has no impact on API operation. * [#9730](https://github.com/netbox-community/netbox/issues/9730) - Fix validation error when creating a new cable via UI form * [#9733](https://github.com/netbox-community/netbox/issues/9733) - Handle split paths during trace when fanning out to front ports with differing cables * [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view +* [#9789](https://github.com/netbox-community/netbox/issues/9789) - Fix rendering of cable traces ending at provider networks * [#9794](https://github.com/netbox-community/netbox/issues/9794) - Fix link to connect a rear port to a circuit termination * [#9818](https://github.com/netbox-community/netbox/issues/9818) - Fix circuit side selection when connecting a cable to a circuit termination * [#9829](https://github.com/netbox-community/netbox/issues/9829) - Arrange custom fields by group when editing objects diff --git a/netbox/dcim/api/views.py b/netbox/dcim/api/views.py index 59445d97b..32cc3dbba 100644 --- a/netbox/dcim/api/views.py +++ b/netbox/dcim/api/views.py @@ -64,20 +64,20 @@ class PathEndpointMixin(object): return HttpResponse(drawing.render().tostring(), content_type='image/svg+xml') # Serialize path objects, iterating over each three-tuple in the path - for near_end, cable, far_end in obj.trace(): - if near_end is not None: - serializer_a = get_serializer_for_model(near_end[0], prefix=NESTED_SERIALIZER_PREFIX) - near_end = serializer_a(near_end, many=True, context={'request': request}).data + for near_ends, cable, far_ends in obj.trace(): + if near_ends: + serializer_a = get_serializer_for_model(near_ends[0], prefix=NESTED_SERIALIZER_PREFIX) + near_ends = serializer_a(near_ends, many=True, context={'request': request}).data else: # Path is split; stop here break - if cable is not None: + if cable: cable = serializers.TracedCableSerializer(cable[0], context={'request': request}).data - if far_end is not None: - serializer_b = get_serializer_for_model(far_end[0], prefix=NESTED_SERIALIZER_PREFIX) - far_end = serializer_b(far_end, many=True, context={'request': request}).data + if far_ends: + serializer_b = get_serializer_for_model(far_ends[0], prefix=NESTED_SERIALIZER_PREFIX) + far_ends = serializer_b(far_ends, many=True, context={'request': request}).data - path.append((near_end, cable, far_end)) + path.append((near_ends, cable, far_ends)) return Response(path) diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 8f62b0626..5e2fc348e 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -212,10 +212,13 @@ class PathEndpoint(models.Model): break path.extend(origin._path.path_objects) - while (len(path)) % 3: - # Pad to ensure we have complete three-tuples (e.g. for paths that end at a non-connected FrontPort) - # by inserting empty entries immediately prior to the path's destination node(s) - path.append([]) + + # If the path ends at a non-connected pass-through port, pad out the link and far-end terminations + if len(path) % 3 == 1: + path.extend(([], [])) + # If the path ends at a site or provider network, inject a null "link" to render an attachment + elif len(path) % 3 == 2: + path.insert(-1, []) # Check for a bridged relationship to continue the trace destinations = origin._path.destinations diff --git a/netbox/dcim/svg/cables.py b/netbox/dcim/svg/cables.py index f9c614b67..3b259eca2 100644 --- a/netbox/dcim/svg/cables.py +++ b/netbox/dcim/svg/cables.py @@ -369,14 +369,16 @@ class CableTraceSVG: parent_objects = set(end.parent_object for end in far_ends) self.draw_parent_objects(parent_objects) + # Render a far-end object not connected via a link (e.g. a ProviderNetwork or Site associated with + # a CircuitTermination) elif far_ends: # Attachment attachment = self.draw_attachment() self.connectors.append(attachment) - # ProviderNetwork - self.draw_parent_objects(set(end.parent_object for end in far_ends)) + # Object + self.draw_parent_objects(far_ends) # Determine drawing size self.drawing = svgwrite.Drawing( From 29a611c7293741100f3e5351243dffbae8e5b481 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 1 Aug 2022 16:51:44 -0400 Subject: [PATCH 196/245] Closes #9896: Discontinue arbitrary use of OrderedDict --- netbox/dcim/api/views.py | 3 +- netbox/dcim/views.py | 44 +++++++++++----------- netbox/extras/reports.py | 17 ++++----- netbox/extras/scripts.py | 5 +-- netbox/extras/templatetags/custom_links.py | 4 +- netbox/ipam/api/serializers.py | 32 ++++++++-------- netbox/netbox/api/fields.py | 10 ++--- netbox/netbox/api/views.py | 25 ++++++------ netbox/utilities/utils.py | 3 +- 9 files changed, 65 insertions(+), 78 deletions(-) diff --git a/netbox/dcim/api/views.py b/netbox/dcim/api/views.py index 32cc3dbba..c18eab01f 100644 --- a/netbox/dcim/api/views.py +++ b/netbox/dcim/api/views.py @@ -1,5 +1,4 @@ import socket -from collections import OrderedDict from django.http import Http404, HttpResponse, HttpResponseForbidden from django.shortcuts import get_object_or_404 @@ -484,7 +483,7 @@ class DeviceViewSet(ConfigContextQuerySetMixin, NetBoxModelViewSet): return HttpResponseForbidden() napalm_methods = request.GET.getlist('method') - response = OrderedDict([(m, None) for m in napalm_methods]) + response = {m: None for m in napalm_methods} config = get_config() username = config.NAPALM_USERNAME diff --git a/netbox/dcim/views.py b/netbox/dcim/views.py index 6daecb3a6..4480bee6e 100644 --- a/netbox/dcim/views.py +++ b/netbox/dcim/views.py @@ -1,5 +1,3 @@ -from collections import OrderedDict - from django.contrib import messages from django.contrib.contenttypes.models import ContentType from django.core.paginator import EmptyPage, PageNotAnInteger @@ -945,18 +943,18 @@ class DeviceTypeImportView(generic.ObjectImportView): ] queryset = DeviceType.objects.all() model_form = forms.DeviceTypeImportForm - related_object_forms = OrderedDict(( - ('console-ports', forms.ConsolePortTemplateImportForm), - ('console-server-ports', forms.ConsoleServerPortTemplateImportForm), - ('power-ports', forms.PowerPortTemplateImportForm), - ('power-outlets', forms.PowerOutletTemplateImportForm), - ('interfaces', forms.InterfaceTemplateImportForm), - ('rear-ports', forms.RearPortTemplateImportForm), - ('front-ports', forms.FrontPortTemplateImportForm), - ('module-bays', forms.ModuleBayTemplateImportForm), - ('device-bays', forms.DeviceBayTemplateImportForm), - ('inventory-items', forms.InventoryItemTemplateImportForm), - )) + related_object_forms = { + 'console-ports': forms.ConsolePortTemplateImportForm, + 'console-server-ports': forms.ConsoleServerPortTemplateImportForm, + 'power-ports': forms.PowerPortTemplateImportForm, + 'power-outlets': forms.PowerOutletTemplateImportForm, + 'interfaces': forms.InterfaceTemplateImportForm, + 'rear-ports': forms.RearPortTemplateImportForm, + 'front-ports': forms.FrontPortTemplateImportForm, + 'module-bays': forms.ModuleBayTemplateImportForm, + 'device-bays': forms.DeviceBayTemplateImportForm, + 'inventory-items': forms.InventoryItemTemplateImportForm, + } def prep_related_object_data(self, parent, data): data.update({'device_type': parent}) @@ -1075,15 +1073,15 @@ class ModuleTypeImportView(generic.ObjectImportView): ] queryset = ModuleType.objects.all() model_form = forms.ModuleTypeImportForm - related_object_forms = OrderedDict(( - ('console-ports', forms.ConsolePortTemplateImportForm), - ('console-server-ports', forms.ConsoleServerPortTemplateImportForm), - ('power-ports', forms.PowerPortTemplateImportForm), - ('power-outlets', forms.PowerOutletTemplateImportForm), - ('interfaces', forms.InterfaceTemplateImportForm), - ('rear-ports', forms.RearPortTemplateImportForm), - ('front-ports', forms.FrontPortTemplateImportForm), - )) + related_object_forms = { + 'console-ports': forms.ConsolePortTemplateImportForm, + 'console-server-ports': forms.ConsoleServerPortTemplateImportForm, + 'power-ports': forms.PowerPortTemplateImportForm, + 'power-outlets': forms.PowerOutletTemplateImportForm, + 'interfaces': forms.InterfaceTemplateImportForm, + 'rear-ports': forms.RearPortTemplateImportForm, + 'front-ports': forms.FrontPortTemplateImportForm, + } def prep_related_object_data(self, parent, data): data.update({'module_type': parent}) diff --git a/netbox/extras/reports.py b/netbox/extras/reports.py index 0a8a8d89b..43d916aff 100644 --- a/netbox/extras/reports.py +++ b/netbox/extras/reports.py @@ -3,7 +3,6 @@ import inspect import logging import pkgutil import traceback -from collections import OrderedDict from django.conf import settings from django.utils import timezone @@ -114,7 +113,7 @@ class Report(object): def __init__(self): - self._results = OrderedDict() + self._results = {} self.active_test = None self.failed = False @@ -125,13 +124,13 @@ class Report(object): for method in dir(self): if method.startswith('test_') and callable(getattr(self, method)): test_methods.append(method) - self._results[method] = OrderedDict([ - ('success', 0), - ('info', 0), - ('warning', 0), - ('failure', 0), - ('log', []), - ]) + self._results[method] = { + 'success': 0, + 'info': 0, + 'warning': 0, + 'failure': 0, + 'log': [], + } if not test_methods: raise Exception("A report must contain at least one test method.") self.test_methods = test_methods diff --git a/netbox/extras/scripts.py b/netbox/extras/scripts.py index cee264878..6e4478304 100644 --- a/netbox/extras/scripts.py +++ b/netbox/extras/scripts.py @@ -6,7 +6,6 @@ import pkgutil import sys import traceback import threading -from collections import OrderedDict import yaml from django import forms @@ -496,7 +495,7 @@ def get_scripts(use_names=False): Return a dict of dicts mapping all scripts to their modules. Set use_names to True to use each module's human- defined name in place of the actual module name. """ - scripts = OrderedDict() + scripts = {} # Iterate through all modules within the scripts path. These are the user-created files in which reports are # defined. for importer, module_name, _ in pkgutil.iter_modules([settings.SCRIPTS_ROOT]): @@ -510,7 +509,7 @@ def get_scripts(use_names=False): if use_names and hasattr(module, 'name'): module_name = module.name - module_scripts = OrderedDict() + module_scripts = {} script_order = getattr(module, "script_order", ()) ordered_scripts = [cls for cls in script_order if is_script(cls)] unordered_scripts = [cls for _, cls in inspect.getmembers(module, is_script) if cls not in script_order] diff --git a/netbox/extras/templatetags/custom_links.py b/netbox/extras/templatetags/custom_links.py index d963bd25a..a73eb3fb4 100644 --- a/netbox/extras/templatetags/custom_links.py +++ b/netbox/extras/templatetags/custom_links.py @@ -1,5 +1,3 @@ -from collections import OrderedDict - from django import template from django.contrib.contenttypes.models import ContentType from django.utils.safestring import mark_safe @@ -50,7 +48,7 @@ def custom_links(context, obj): 'perms': context['perms'], # django.contrib.auth.context_processors.auth } template_code = '' - group_names = OrderedDict() + group_names = {} for cl in custom_links: diff --git a/netbox/ipam/api/serializers.py b/netbox/ipam/api/serializers.py index b3a3589fd..91a81d3b2 100644 --- a/netbox/ipam/api/serializers.py +++ b/netbox/ipam/api/serializers.py @@ -1,5 +1,3 @@ -from collections import OrderedDict - from django.contrib.contenttypes.models import ContentType from drf_yasg.utils import swagger_serializer_method from rest_framework import serializers @@ -227,13 +225,13 @@ class AvailableVLANSerializer(serializers.Serializer): group = NestedVLANGroupSerializer(read_only=True) def to_representation(self, instance): - return OrderedDict([ - ('vid', instance), - ('group', NestedVLANGroupSerializer( + return { + 'vid': instance, + 'group': NestedVLANGroupSerializer( self.context['group'], context={'request': self.context['request']} - ).data), - ]) + ).data, + } class CreateAvailableVLANSerializer(NetBoxModelSerializer): @@ -318,11 +316,11 @@ class AvailablePrefixSerializer(serializers.Serializer): vrf = NestedVRFSerializer(self.context['vrf'], context={'request': self.context['request']}).data else: vrf = None - return OrderedDict([ - ('family', instance.version), - ('prefix', str(instance)), - ('vrf', vrf), - ]) + return { + 'family': instance.version, + 'prefix': str(instance), + 'vrf': vrf, + } # @@ -397,11 +395,11 @@ class AvailableIPSerializer(serializers.Serializer): vrf = NestedVRFSerializer(self.context['vrf'], context={'request': self.context['request']}).data else: vrf = None - return OrderedDict([ - ('family', self.context['parent'].family), - ('address', f"{instance}/{self.context['parent'].mask_length}"), - ('vrf', vrf), - ]) + return { + 'family': self.context['parent'].family, + 'address': f"{instance}/{self.context['parent'].mask_length}", + 'vrf': vrf, + } # diff --git a/netbox/netbox/api/fields.py b/netbox/netbox/api/fields.py index 1f3c40dc2..52343c2f6 100644 --- a/netbox/netbox/api/fields.py +++ b/netbox/netbox/api/fields.py @@ -1,5 +1,3 @@ -from collections import OrderedDict - from django.core.exceptions import ObjectDoesNotExist from netaddr import IPNetwork from rest_framework import serializers @@ -48,10 +46,10 @@ class ChoiceField(serializers.Field): def to_representation(self, obj): if obj == '': return None - return OrderedDict([ - ('value', obj), - ('label', self._choices[obj]) - ]) + return { + 'value': obj, + 'label': self._choices[obj], + } def to_internal_value(self, data): if data == '': diff --git a/netbox/netbox/api/views.py b/netbox/netbox/api/views.py index 835ebc6a9..6c6083959 100644 --- a/netbox/netbox/api/views.py +++ b/netbox/netbox/api/views.py @@ -1,5 +1,4 @@ import platform -from collections import OrderedDict from django import __version__ as DJANGO_VERSION from django.apps import apps @@ -26,18 +25,18 @@ class APIRootView(APIView): def get(self, request, format=None): - return Response(OrderedDict(( - ('circuits', reverse('circuits-api:api-root', request=request, format=format)), - ('dcim', reverse('dcim-api:api-root', request=request, format=format)), - ('extras', reverse('extras-api:api-root', request=request, format=format)), - ('ipam', reverse('ipam-api:api-root', request=request, format=format)), - ('plugins', reverse('plugins-api:api-root', request=request, format=format)), - ('status', reverse('api-status', request=request, format=format)), - ('tenancy', reverse('tenancy-api:api-root', request=request, format=format)), - ('users', reverse('users-api:api-root', request=request, format=format)), - ('virtualization', reverse('virtualization-api:api-root', request=request, format=format)), - ('wireless', reverse('wireless-api:api-root', request=request, format=format)), - ))) + return Response({ + 'circuits': reverse('circuits-api:api-root', request=request, format=format), + 'dcim': reverse('dcim-api:api-root', request=request, format=format), + 'extras': reverse('extras-api:api-root', request=request, format=format), + 'ipam': reverse('ipam-api:api-root', request=request, format=format), + 'plugins': reverse('plugins-api:api-root', request=request, format=format), + 'status': reverse('api-status', request=request, format=format), + 'tenancy': reverse('tenancy-api:api-root', request=request, format=format), + 'users': reverse('users-api:api-root', request=request, format=format), + 'virtualization': reverse('virtualization-api:api-root', request=request, format=format), + 'wireless': reverse('wireless-api:api-root', request=request, format=format), + }) class StatusView(APIView): diff --git a/netbox/utilities/utils.py b/netbox/utilities/utils.py index fa0534ec0..1dece76c8 100644 --- a/netbox/utilities/utils.py +++ b/netbox/utilities/utils.py @@ -1,7 +1,6 @@ import datetime import decimal import json -from collections import OrderedDict from decimal import Decimal from itertools import count, groupby @@ -218,7 +217,7 @@ def deepmerge(original, new): """ Deep merge two dictionaries (new into original) and return a new dict """ - merged = OrderedDict(original) + merged = dict(original) for key, val in new.items(): if key in original and isinstance(original[key], dict) and val and isinstance(val, dict): merged[key] = deepmerge(original[key], val) From e96620260a6c1b5cf8cff2112d40d061984a7b2c Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 2 Aug 2022 13:49:34 -0400 Subject: [PATCH 197/245] Closes #9903: Implement a mechanism for automatically updating denormalized fields --- docs/release-notes/version-3.3.md | 1 + netbox/extras/registry.py | 1 + netbox/netbox/denormalized.py | 54 +++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+) create mode 100644 netbox/netbox/denormalized.py diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index e30ff011c..49d6891e2 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -124,6 +124,7 @@ Custom field UI visibility has no impact on API operation. * [#9261](https://github.com/netbox-community/netbox/issues/9261) - `NetBoxTable` no longer automatically clears pre-existing calls to `prefetch_related()` on its queryset * [#9434](https://github.com/netbox-community/netbox/issues/9434) - Enabled `django-rich` test runner for more user-friendly output +* [#9903](https://github.com/netbox-community/netbox/issues/9903) - Implement a mechanism for automatically updating denormalized fields ### REST API Changes diff --git a/netbox/extras/registry.py b/netbox/extras/registry.py index 07fd4cc24..e1437c00e 100644 --- a/netbox/extras/registry.py +++ b/netbox/extras/registry.py @@ -28,3 +28,4 @@ registry = Registry() registry['model_features'] = { feature: collections.defaultdict(set) for feature in EXTRAS_FEATURES } +registry['denormalized_fields'] = collections.defaultdict(list) diff --git a/netbox/netbox/denormalized.py b/netbox/netbox/denormalized.py new file mode 100644 index 000000000..5808acddc --- /dev/null +++ b/netbox/netbox/denormalized.py @@ -0,0 +1,54 @@ +import logging + +from django.db.models.signals import post_save +from django.dispatch import receiver + +from extras.registry import registry + + +logger = logging.getLogger('netbox.denormalized') + + +def register(model, field_name, mappings): + """ + Register a denormalized model field to ensure that it is kept up-to-date with the related object. + + Args: + model: The class being updated + field_name: The name of the field related to the triggering instance + mappings: Dictionary mapping of local to remote fields + """ + logger.debug(f'Registering denormalized field {model}.{field_name}') + + field = model._meta.get_field(field_name) + rel_model = field.related_model + + registry['denormalized_fields'][rel_model].append( + (model, field_name, mappings) + ) + + +@receiver(post_save) +def update_denormalized_fields(sender, instance, created, raw, **kwargs): + """ + Check if the sender has denormalized fields registered, and update them as necessary. + """ + # Skip for new objects or those being populated from raw data + if created or raw: + return + + # Look up any denormalized fields referencing this model from the application registry + for model, field_name, mappings in registry['denormalized_fields'].get(sender, []): + logger.debug(f'Updating denormalized values for {model}.{field_name}') + filter_params = { + field_name: instance.pk, + } + update_params = { + # Map the denormalized field names to the instance's values + denorm: getattr(instance, origin) for denorm, origin in mappings.items() + } + + # TODO: Improve efficiency here by placing conditions on the query? + # Update all the denormalized fields with the triggering object's new values + count = model.objects.filter(**filter_params).update(**update_params) + logger.debug(f'Updated {count} rows') From 5b3ef045506100c6fdf6ae9a15d7f717a1fd0f15 Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Tue, 2 Aug 2022 12:38:16 -0500 Subject: [PATCH 198/245] #9888 - Add filter and columns for device and site --- netbox/ipam/filtersets.py | 83 +++++++++++++++++++++++++++------ netbox/ipam/forms/filtersets.py | 44 ++++++++++++++++- netbox/ipam/models/l2vpn.py | 15 ++++++ netbox/ipam/tables/l2vpn.py | 11 ++++- 4 files changed, 136 insertions(+), 17 deletions(-) diff --git a/netbox/ipam/filtersets.py b/netbox/ipam/filtersets.py index edd1867ed..132094325 100644 --- a/netbox/ipam/filtersets.py +++ b/netbox/ipam/filtersets.py @@ -980,21 +980,65 @@ class L2VPNTerminationFilterSet(NetBoxModelFilterSet): to_field_name='slug', label='L2VPN (slug)', ) - device = MultiValueCharFilter( - method='filter_device', - field_name='name', - label='Device (name)', + region = MultiValueCharFilter( + method='filter_region', + field_name='slug', + label='Region (slug)', ) - device_id = MultiValueNumberFilter( - method='filter_device', + region_id = MultiValueNumberFilter( + method='filter_region', + field_name='pk', + label='Region (ID)', + ) + site = MultiValueCharFilter( + method='filter_site', + field_name='slug', + label='Device (slug)', + ) + site_id = MultiValueNumberFilter( + method='filter_site', field_name='pk', label='Device (ID)', ) + device = django_filters.ModelMultipleChoiceFilter( + field_name='interface__device__name', + queryset=Device.objects.all(), + to_field_name='name', + label='Device (name)', + ) + device_id = django_filters.ModelMultipleChoiceFilter( + field_name='interface__device', + queryset=Device.objects.all(), + label='Device (ID)', + ) + virtual_machine = django_filters.ModelMultipleChoiceFilter( + field_name='vminterface__virtual_machine__name', + queryset=VirtualMachine.objects.all(), + to_field_name='name', + label='Virtual machine (name)', + ) + virtual_machine_id = django_filters.ModelMultipleChoiceFilter( + field_name='vminterface__virtual_machine', + queryset=VirtualMachine.objects.all(), + label='Virtual machine (ID)', + ) + interface = django_filters.ModelMultipleChoiceFilter( + field_name='interface__name', + queryset=Interface.objects.all(), + to_field_name='name', + label='Interface (name)', + ) interface_id = django_filters.ModelMultipleChoiceFilter( field_name='interface', queryset=Interface.objects.all(), label='Interface (ID)', ) + vminterface = django_filters.ModelMultipleChoiceFilter( + field_name='vminterface__name', + queryset=VMInterface.objects.all(), + to_field_name='name', + label='VM interface (name)', + ) vminterface_id = django_filters.ModelMultipleChoiceFilter( field_name='vminterface', queryset=VMInterface.objects.all(), @@ -1027,13 +1071,22 @@ class L2VPNTerminationFilterSet(NetBoxModelFilterSet): qs_filter = Q(l2vpn__name__icontains=value) return queryset.filter(qs_filter) - def filter_device(self, queryset, name, value): - devices = Device.objects.filter(**{'{}__in'.format(name): value}) - if not devices.exists(): - return queryset.none() - interface_ids = [] - for device in devices: - interface_ids.extend(device.vc_interfaces().values_list('id', flat=True)) - return queryset.filter( - interface__in=interface_ids + def filter_site(self, queryset, name, value): + qs = queryset.filter( + Q( + Q(**{'vlan__site__{}__in'.format(name): value}) | + Q(**{'interface__device__site__{}__in'.format(name): value}) | + Q(**{'vminterface__virtual_machine__site__{}__in'.format(name): value}) + ) ) + return qs + + def filter_region(self, queryset, name, value): + qs = queryset.filter( + Q( + Q(**{'vlan__site__region__{}__in'.format(name): value}) | + Q(**{'interface__device__site__region__{}__in'.format(name): value}) | + Q(**{'vminterface__virtual_machine__site__region__{}__in'.format(name): value}) + ) + ) + return qs diff --git a/netbox/ipam/forms/filtersets.py b/netbox/ipam/forms/filtersets.py index 384a4da33..d93bd16d0 100644 --- a/netbox/ipam/forms/filtersets.py +++ b/netbox/ipam/forms/filtersets.py @@ -508,7 +508,8 @@ class L2VPNFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm): class L2VPNTerminationFilterForm(NetBoxModelFilterSetForm): model = L2VPNTermination fieldsets = ( - (None, ('l2vpn_id', 'assigned_object_type_id')), + (None, ('l2vpn_id', 'assigned_object_type_id', )), + ('Assigned Object', ('region_id', 'site_id', 'device_id', 'virtual_machine_id', 'vlan_id')), ) l2vpn_id = DynamicModelChoiceField( queryset=L2VPN.objects.all(), @@ -520,3 +521,44 @@ class L2VPNTerminationFilterForm(NetBoxModelFilterSetForm): required=False, label='Object type' ) + region_id = DynamicModelMultipleChoiceField( + queryset=Region.objects.all(), + required=False, + label=_('Region') + ) + site_id = DynamicModelMultipleChoiceField( + queryset=Site.objects.all(), + required=False, + null_option='None', + query_params={ + 'region_id': '$region_id' + }, + label=_('Site') + ) + device_id = DynamicModelMultipleChoiceField( + queryset=Device.objects.all(), + required=False, + null_option='None', + query_params={ + 'site_id': '$site_id' + }, + label=_('Device') + ) + vlan_id = DynamicModelMultipleChoiceField( + queryset=VLAN.objects.all(), + required=False, + null_option='None', + query_params={ + 'site_id': '$site_id' + }, + label=_('VLAN') + ) + virtual_machine_id = DynamicModelMultipleChoiceField( + queryset=VirtualMachine.objects.all(), + required=False, + null_option='None', + query_params={ + 'site_id': '$site_id' + }, + label=_('Virtual Machine') + ) diff --git a/netbox/ipam/models/l2vpn.py b/netbox/ipam/models/l2vpn.py index 5d85fe915..5adf5e05d 100644 --- a/netbox/ipam/models/l2vpn.py +++ b/netbox/ipam/models/l2vpn.py @@ -113,3 +113,18 @@ class L2VPNTermination(NetBoxModel): f'{l2vpn_type} L2VPNs cannot have more than two terminations; found {terminations_count} already ' f'defined.' ) + + @property + def assigned_object_parent(self): + obj_type = ContentType.objects.get_for_model(self.assigned_object) + if obj_type.model == 'vminterface': + return self.assigned_object.virtual_machine + elif obj_type.model == 'interface': + return self.assigned_object.device + elif obj_type.model == 'vminterface': + return self.assigned_object.virtual_machine + return None + + @property + def assigned_object_site(self): + return self.assigned_object_parent.site diff --git a/netbox/ipam/tables/l2vpn.py b/netbox/ipam/tables/l2vpn.py index 5be525343..e2eae7a32 100644 --- a/netbox/ipam/tables/l2vpn.py +++ b/netbox/ipam/tables/l2vpn.py @@ -53,8 +53,17 @@ class L2VPNTerminationTable(NetBoxTable): linkify=True, orderable=False ) + assigned_object_parent = tables.Column( + linkify=True, + orderable=False + ) + assigned_object_site = tables.Column( + linkify=True, + orderable=False + ) class Meta(NetBoxTable.Meta): model = L2VPNTermination - fields = ('pk', 'l2vpn', 'assigned_object_type', 'assigned_object', 'actions') + fields = ('pk', 'l2vpn', 'assigned_object_type', 'assigned_object', 'assigned_object_parent', + 'assigned_object_site', 'actions') default_columns = ('pk', 'l2vpn', 'assigned_object_type', 'assigned_object', 'actions') From d3a567a2f565097d7409d888dacabda2c59f42f6 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 2 Aug 2022 13:56:52 -0400 Subject: [PATCH 199/245] Fixes #9788: Ensure denormalized fields on CableTermination are kept in sync with related objects --- docs/release-notes/version-3.3.md | 1 + netbox/dcim/apps.py | 18 +++++++++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 49d6891e2..5d043a777 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -104,6 +104,7 @@ Custom field UI visibility has no impact on API operation. * [#9730](https://github.com/netbox-community/netbox/issues/9730) - Fix validation error when creating a new cable via UI form * [#9733](https://github.com/netbox-community/netbox/issues/9733) - Handle split paths during trace when fanning out to front ports with differing cables * [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view +* [#9788](https://github.com/netbox-community/netbox/issues/9788) - Ensure denormalized fields on CableTermination are kept in sync with related objects * [#9789](https://github.com/netbox-community/netbox/issues/9789) - Fix rendering of cable traces ending at provider networks * [#9794](https://github.com/netbox-community/netbox/issues/9794) - Fix link to connect a rear port to a circuit termination * [#9818](https://github.com/netbox-community/netbox/issues/9818) - Fix circuit side selection when connecting a cable to a circuit termination diff --git a/netbox/dcim/apps.py b/netbox/dcim/apps.py index 78a243f84..4be2df659 100644 --- a/netbox/dcim/apps.py +++ b/netbox/dcim/apps.py @@ -1,10 +1,26 @@ from django.apps import AppConfig +from netbox import denormalized + class DCIMConfig(AppConfig): name = "dcim" verbose_name = "DCIM" def ready(self): - import dcim.signals + from .models import CableTermination + + # Register denormalized fields + denormalized.register(CableTermination, '_device', { + '_rack': 'rack', + '_location': 'location', + '_site': 'site', + }) + denormalized.register(CableTermination, '_rack', { + '_location': 'location', + '_site': 'site', + }) + denormalized.register(CableTermination, '_location', { + '_site': 'site', + }) From 37c4f1a7d3509f137a5a81d1b570d10a7533ccae Mon Sep 17 00:00:00 2001 From: Daniel Sheppard Date: Tue, 2 Aug 2022 13:38:17 -0500 Subject: [PATCH 200/245] Fix up a few minor mistakes. Add tests. --- netbox/ipam/filtersets.py | 4 ++-- netbox/ipam/forms/filtersets.py | 11 ++++++----- netbox/ipam/tests/test_filtersets.py | 21 +++++++++++++++++++++ 3 files changed, 29 insertions(+), 7 deletions(-) diff --git a/netbox/ipam/filtersets.py b/netbox/ipam/filtersets.py index 132094325..49ec15fc1 100644 --- a/netbox/ipam/filtersets.py +++ b/netbox/ipam/filtersets.py @@ -993,12 +993,12 @@ class L2VPNTerminationFilterSet(NetBoxModelFilterSet): site = MultiValueCharFilter( method='filter_site', field_name='slug', - label='Device (slug)', + label='Site (slug)', ) site_id = MultiValueNumberFilter( method='filter_site', field_name='pk', - label='Device (ID)', + label='Site (ID)', ) device = django_filters.ModelMultipleChoiceFilter( field_name='interface__device__name', diff --git a/netbox/ipam/forms/filtersets.py b/netbox/ipam/forms/filtersets.py index d93bd16d0..ecf63b49f 100644 --- a/netbox/ipam/forms/filtersets.py +++ b/netbox/ipam/forms/filtersets.py @@ -11,7 +11,7 @@ from netbox.forms import NetBoxModelFilterSetForm from tenancy.forms import TenancyFilterForm from utilities.forms import ( add_blank_choice, ContentTypeMultipleChoiceField, DynamicModelChoiceField, DynamicModelMultipleChoiceField, - MultipleChoiceField, StaticSelect, TagFilterField, BOOLEAN_WITH_BLANK_CHOICES, + MultipleChoiceField, StaticSelect, TagFilterField, BOOLEAN_WITH_BLANK_CHOICES, APISelectMultiple, ) from virtualization.models import VirtualMachine @@ -508,8 +508,8 @@ class L2VPNFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm): class L2VPNTerminationFilterForm(NetBoxModelFilterSetForm): model = L2VPNTermination fieldsets = ( - (None, ('l2vpn_id', 'assigned_object_type_id', )), - ('Assigned Object', ('region_id', 'site_id', 'device_id', 'virtual_machine_id', 'vlan_id')), + (None, ('l2vpn_id', )), + ('Assigned Object', ('assigned_object_type_id', 'region_id', 'site_id', 'device_id', 'virtual_machine_id', 'vlan_id')), ) l2vpn_id = DynamicModelChoiceField( queryset=L2VPN.objects.all(), @@ -517,9 +517,10 @@ class L2VPNTerminationFilterForm(NetBoxModelFilterSetForm): label='L2VPN' ) assigned_object_type_id = ContentTypeMultipleChoiceField( - queryset=ContentType.objects.all(), + queryset=ContentType.objects.filter(L2VPN_ASSIGNMENT_MODELS), required=False, - label='Object type' + label=_('Assigned Object Type'), + limit_choices_to=L2VPN_ASSIGNMENT_MODELS ) region_id = DynamicModelMultipleChoiceField( queryset=Region.objects.all(), diff --git a/netbox/ipam/tests/test_filtersets.py b/netbox/ipam/tests/test_filtersets.py index 9106a4965..081f6e11d 100644 --- a/netbox/ipam/tests/test_filtersets.py +++ b/netbox/ipam/tests/test_filtersets.py @@ -1600,3 +1600,24 @@ class L2VPNTerminationTestCase(TestCase, ChangeLoggedFilterSetTests): self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) params = {'vlan': ['VLAN 1', 'VLAN 2']} self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2) + + def test_site(self): + site = Site.objects.all().first() + params = {'site_id': [site.pk]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 3) + params = {'site': ['site-1']} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 3) + + def test_device(self): + device = Device.objects.all().first() + params = {'device_id': [device.pk]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 3) + params = {'device': ['Device 1']} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 3) + + def test_virtual_machine(self): + virtual_machine = VirtualMachine.objects.all().first() + params = {'virtual_machine_id': [virtual_machine.pk]} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 3) + params = {'virtual_machine': ['Virtual Machine 1']} + self.assertEqual(self.filterset(params, self.queryset).qs.count(), 3) From b9678c7c0e50c9b2f24aec95a0d8c13c1b20f3dd Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 3 Aug 2022 10:50:35 -0400 Subject: [PATCH 201/245] Closes #9853: Show full object in cable A/B termination lists --- netbox/netbox/api/serializers/generic.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/netbox/netbox/api/serializers/generic.py b/netbox/netbox/api/serializers/generic.py index 8b4069c98..5016bdaab 100644 --- a/netbox/netbox/api/serializers/generic.py +++ b/netbox/netbox/api/serializers/generic.py @@ -1,7 +1,10 @@ from django.contrib.contenttypes.models import ContentType +from drf_yasg.utils import swagger_serializer_method from rest_framework import serializers from netbox.api.fields import ContentTypeField +from netbox.constants import NESTED_SERIALIZER_PREFIX +from utilities.api import get_serializer_for_model from utilities.utils import content_type_identifier __all__ = ( @@ -17,6 +20,7 @@ class GenericObjectSerializer(serializers.Serializer): queryset=ContentType.objects.all() ) object_id = serializers.IntegerField() + object = serializers.SerializerMethodField(read_only=True) def to_internal_value(self, data): data = super().to_internal_value(data) @@ -25,7 +29,17 @@ class GenericObjectSerializer(serializers.Serializer): def to_representation(self, instance): ct = ContentType.objects.get_for_model(instance) - return { + data = { 'object_type': content_type_identifier(ct), 'object_id': instance.pk, } + if 'request' in self.context: + data['object'] = self.get_object(instance) + + return data + + @swagger_serializer_method(serializer_or_field=serializers.DictField) + def get_object(self, obj): + serializer = get_serializer_for_model(obj, prefix=NESTED_SERIALIZER_PREFIX) + # context = {'request': self.context['request']} + return serializer(obj, context=self.context).data From 367bf25618d1be55c10b7e707101f2759711e855 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 3 Aug 2022 12:46:16 -0400 Subject: [PATCH 202/245] Fixes #9778: Fix exception during cable deletion after deleting a connected termination --- docs/release-notes/version-3.3.md | 1 + netbox/dcim/models/cables.py | 24 +++++++++++++----------- netbox/dcim/signals.py | 5 ++++- netbox/dcim/svg/cables.py | 5 ++++- netbox/dcim/utils.py | 5 +++-- netbox/templates/dcim/interface.html | 2 +- 6 files changed, 26 insertions(+), 16 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 5d043a777..6099e8a61 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -104,6 +104,7 @@ Custom field UI visibility has no impact on API operation. * [#9730](https://github.com/netbox-community/netbox/issues/9730) - Fix validation error when creating a new cable via UI form * [#9733](https://github.com/netbox-community/netbox/issues/9733) - Handle split paths during trace when fanning out to front ports with differing cables * [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view +* [#9778](https://github.com/netbox-community/netbox/issues/9778) - Fix exception during cable deletion after deleting a connected termination * [#9788](https://github.com/netbox-community/netbox/issues/9788) - Ensure denormalized fields on CableTermination are kept in sync with related objects * [#9789](https://github.com/netbox-community/netbox/issues/9789) - Fix rendering of cable traces ending at provider networks * [#9794](https://github.com/netbox-community/netbox/issues/9794) - Fix link to connect a rear port to a circuit termination diff --git a/netbox/dcim/models/cables.py b/netbox/dcim/models/cables.py index e0a489f5b..321d808ff 100644 --- a/netbox/dcim/models/cables.py +++ b/netbox/dcim/models/cables.py @@ -431,11 +431,7 @@ class CablePath(models.Model): """ Return the list of originating objects. """ - if hasattr(self, '_path_objects'): - return self.path_objects[0] - return [ - path_node_to_object(node) for node in self.path[0] - ] + return self.path_objects[0] @property def destinations(self): @@ -444,11 +440,7 @@ class CablePath(models.Model): """ if not self.is_complete: return [] - if hasattr(self, '_path_objects'): - return self.path_objects[-1] - return [ - path_node_to_object(node) for node in self.path[-1] - ] + return self.path_objects[-1] @property def segment_count(self): @@ -463,6 +455,9 @@ class CablePath(models.Model): """ from circuits.models import CircuitTermination + if not terminations: + return None + # Ensure all originating terminations are attached to the same link if len(terminations) > 1: assert all(t.link == terminations[0].link for t in terminations[1:]) @@ -529,6 +524,9 @@ class CablePath(models.Model): ]) # Step 6: Determine the "next hop" terminations, if applicable + if not remote_terminations: + break + if isinstance(remote_terminations[0], FrontPort): # Follow FrontPorts to their corresponding RearPorts rear_ports = RearPort.objects.filter( @@ -640,7 +638,11 @@ class CablePath(models.Model): nodes = [] for node in step: ct_id, object_id = decompile_path_node(node) - nodes.append(prefetched[ct_id][object_id]) + try: + nodes.append(prefetched[ct_id][object_id]) + except KeyError: + # Ignore stale (deleted) object IDs + pass path.append(nodes) return path diff --git a/netbox/dcim/signals.py b/netbox/dcim/signals.py index 2293f8840..b990daf1a 100644 --- a/netbox/dcim/signals.py +++ b/netbox/dcim/signals.py @@ -116,7 +116,10 @@ def retrace_cable_paths(instance, **kwargs): @receiver(post_delete, sender=CableTermination) def nullify_connected_endpoints(instance, **kwargs): """ - Disassociate the Cable from the termination object. + Disassociate the Cable from the termination object, and retrace any affected CablePaths. """ model = instance.termination_type.model_class() model.objects.filter(pk=instance.termination_id).update(cable=None, cable_end='') + + for cablepath in CablePath.objects.filter(_nodes__contains=instance.cable): + cablepath.retrace() diff --git a/netbox/dcim/svg/cables.py b/netbox/dcim/svg/cables.py index 3b259eca2..26d16fafe 100644 --- a/netbox/dcim/svg/cables.py +++ b/netbox/dcim/svg/cables.py @@ -362,8 +362,11 @@ class CableTraceSVG: terminations = self.draw_terminations(far_ends) for term in terminations: self.draw_fanout(term, cable) - else: + elif far_ends: self.draw_terminations(far_ends) + else: + # Link is not connected to anything + break # Far end parent parent_objects = set(end.parent_object for end in far_ends) diff --git a/netbox/dcim/utils.py b/netbox/dcim/utils.py index 26b6e2e25..eadd2da96 100644 --- a/netbox/dcim/utils.py +++ b/netbox/dcim/utils.py @@ -24,11 +24,12 @@ def object_to_path_node(obj): def path_node_to_object(repr): """ - Given the string representation of a path node, return the corresponding instance. + Given the string representation of a path node, return the corresponding instance. If the object no longer + exists, return None. """ ct_id, object_id = decompile_path_node(repr) ct = ContentType.objects.get_for_id(ct_id) - return ct.model_class().objects.get(pk=object_id) + return ct.model_class().objects.filter(pk=object_id).first() def create_cablepath(terminations): diff --git a/netbox/templates/dcim/interface.html b/netbox/templates/dcim/interface.html index 3a7fe986a..11e776872 100644 --- a/netbox/templates/dcim/interface.html +++ b/netbox/templates/dcim/interface.html @@ -219,7 +219,7 @@
    Path Status - {% if object.path.is_active %} + {% if object.path.is_complete and object.path.is_active %} Reachable {% else %} Not Reachable From f11a6f0135fc40bb2b695f38b5668a09ec46e3be Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 3 Aug 2022 14:41:50 -0400 Subject: [PATCH 203/245] Release v3.3-beta2 --- .github/ISSUE_TEMPLATE/bug_report.yaml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yaml | 2 +- docs/release-notes/version-3.3.md | 2 +- netbox/netbox/settings.py | 2 +- requirements.txt | 10 +++++----- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 88fbb1df9..dc8dd8275 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -14,7 +14,7 @@ body: attributes: label: NetBox version description: What version of NetBox are you currently running? - placeholder: v3.3-beta1 + placeholder: v3.3-beta2 validations: required: true - type: dropdown diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml index 1035c02fb..d9e5a26fd 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yaml +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -14,7 +14,7 @@ body: attributes: label: NetBox version description: What version of NetBox are you currently running? - placeholder: v3.3-beta1 + placeholder: v3.3-beta2 validations: required: true - type: dropdown diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 6099e8a61..2a3935e5e 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -1,6 +1,6 @@ # NetBox v3.3 -## v3.3.0 (FUTURE) +## v3.3-beta2 (2022-08-03) ### Breaking Changes diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index e0ec8e1ec..0dcde9cf6 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -29,7 +29,7 @@ django.utils.encoding.force_text = force_str # Environment setup # -VERSION = '3.3-beta1' +VERSION = '3.3-beta2' # Hostname HOSTNAME = platform.node() diff --git a/requirements.txt b/requirements.txt index 4c8e5e5ce..8a7dd79d4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ bleach==5.0.1 -Django==4.0.6 +Django==4.0.7 django-cors-headers==3.13.0 django-debug-toolbar==3.5.0 django-filter==22.1 @@ -14,19 +14,19 @@ django-tables2==2.4.1 django-taggit==3.0.0 django-timezone-field==5.0 djangorestframework==3.13.1 -drf-yasg[validation]==1.20.0 +drf-yasg[validation]==1.21.3 graphene-django==2.15.0 gunicorn==20.1.0 Jinja2==3.1.2 -Markdown==3.3.7 -markdown-include==0.6.0 +Markdown==3.4.1 +markdown-include==0.7.0 mkdocs-material==8.3.9 mkdocstrings[python-legacy]==0.19.0 netaddr==0.8.0 Pillow==9.2.0 psycopg2-binary==2.9.3 PyYAML==6.0 -sentry-sdk==1.7.1 +sentry-sdk==1.9.0 social-auth-app-django==5.0.0 social-auth-core==4.3.0 svgwrite==1.4.3 From 56433cf85520edee9cf0d440bfeb82524eac7fc7 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 4 Aug 2022 10:42:44 -0400 Subject: [PATCH 204/245] Fix denormalization logic to be compatible with loading fixture data --- netbox/netbox/denormalized.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/netbox/netbox/denormalized.py b/netbox/netbox/denormalized.py index 5808acddc..cd4a869d2 100644 --- a/netbox/netbox/denormalized.py +++ b/netbox/netbox/denormalized.py @@ -33,6 +33,10 @@ def update_denormalized_fields(sender, instance, created, raw, **kwargs): """ Check if the sender has denormalized fields registered, and update them as necessary. """ + def _get_field_value(instance, field_name): + field = instance._meta.get_field(field_name) + return field.value_from_object(instance) + # Skip for new objects or those being populated from raw data if created or raw: return @@ -45,7 +49,7 @@ def update_denormalized_fields(sender, instance, created, raw, **kwargs): } update_params = { # Map the denormalized field names to the instance's values - denorm: getattr(instance, origin) for denorm, origin in mappings.items() + denorm: _get_field_value(instance, origin) for denorm, origin in mappings.items() } # TODO: Improve efficiency here by placing conditions on the query? From 5da3cab4de0469c8e8f19726600286abc590c7c3 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 4 Aug 2022 14:11:52 -0400 Subject: [PATCH 205/245] Reorganize documentation --- docs/additional-features/webhooks.md | 57 ----------- docs/administration/permissions.md | 71 ++++++++++++- docs/configuration/miscellaneous.md | 2 +- docs/configuration/napalm.md | 2 +- docs/customization/custom-fields.md | 75 +++++++++++++- .../custom-links.md} | 0 docs/customization/export-templates.md | 39 +++++++- docs/development/models.md | 8 +- .../change-logging.md | 0 docs/features/circuits.md | 3 + docs/features/contacts.md | 3 + .../context-data.md} | 0 docs/features/customization.md | 3 + docs/features/devices-cabling.md | 3 + docs/features/facilities.md | 3 + docs/features/ipam.md | 3 + .../journaling.md | 0 docs/features/l2vpn-overlay.md | 3 + docs/features/permissions.md | 3 + docs/features/power-tracking.md | 3 + docs/features/services.md | 3 + docs/features/sso.md | 3 + .../extras/tag.md => features/tags.md} | 0 docs/features/tenancy.md | 3 + docs/features/vlan-management.md | 3 + .../webhook.md => features/webhooks.md} | 56 +++++++++++ docs/features/wireless.md | 3 + docs/getting-started/populating-data.md | 2 +- docs/installation/3-netbox.md | 2 +- .../graphql-api.md} | 0 .../napalm.md | 0 .../prometheus-metrics.md | 0 .../overview.md => integrations/rest-api.md} | 99 ++++++++++++++++++- docs/models/extras/customfield.md | 73 -------------- docs/models/extras/exporttemplate.md | 37 ------- docs/models/extras/imageattachment.md | 3 - docs/models/users/objectpermission.md | 69 ------------- docs/models/users/token.md | 19 ---- docs/{rest-api => reference}/filtering.md | 0 docs/release-notes/version-3.0.md | 2 +- docs/rest-api/authentication.md | 73 -------------- mkdocs.yml | 47 +++++---- 42 files changed, 412 insertions(+), 366 deletions(-) delete mode 100644 docs/additional-features/webhooks.md rename docs/{models/extras/customlink.md => customization/custom-links.md} (100%) rename docs/{additional-features => features}/change-logging.md (100%) create mode 100644 docs/features/circuits.md create mode 100644 docs/features/contacts.md rename docs/{models/extras/configcontext.md => features/context-data.md} (100%) create mode 100644 docs/features/customization.md create mode 100644 docs/features/devices-cabling.md create mode 100644 docs/features/facilities.md create mode 100644 docs/features/ipam.md rename docs/{additional-features => features}/journaling.md (100%) create mode 100644 docs/features/l2vpn-overlay.md create mode 100644 docs/features/permissions.md create mode 100644 docs/features/power-tracking.md create mode 100644 docs/features/services.md create mode 100644 docs/features/sso.md rename docs/{models/extras/tag.md => features/tags.md} (100%) create mode 100644 docs/features/tenancy.md create mode 100644 docs/features/vlan-management.md rename docs/{models/extras/webhook.md => features/webhooks.md} (67%) create mode 100644 docs/features/wireless.md rename docs/{graphql-api/overview.md => integrations/graphql-api.md} (100%) rename docs/{additional-features => integrations}/napalm.md (100%) rename docs/{additional-features => integrations}/prometheus-metrics.md (100%) rename docs/{rest-api/overview.md => integrations/rest-api.md} (78%) delete mode 100644 docs/models/extras/customfield.md delete mode 100644 docs/models/extras/exporttemplate.md delete mode 100644 docs/models/extras/imageattachment.md delete mode 100644 docs/models/users/objectpermission.md delete mode 100644 docs/models/users/token.md rename docs/{rest-api => reference}/filtering.md (100%) delete mode 100644 docs/rest-api/authentication.md diff --git a/docs/additional-features/webhooks.md b/docs/additional-features/webhooks.md deleted file mode 100644 index 5077f3a68..000000000 --- a/docs/additional-features/webhooks.md +++ /dev/null @@ -1,57 +0,0 @@ -{!models/extras/webhook.md!} - -## Conditional Webhooks - -A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": - -```json -{ - "and": [ - { - "attr": "status.value", - "value": "active" - } - ] -} -``` - -For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md). - -## Webhook Processing - -When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. - -A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. - -## Troubleshooting - -To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: - -```no-highlight -$ python netbox/manage.py webhook_receiver -Listening on port http://localhost:9000. Stop with CONTROL-C. -``` - -You can test the receiver itself by sending any HTTP request to it. For example: - -```no-highlight -$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' -``` - -The server will print output similar to the following: - -```no-highlight -[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - -Host: localhost:9000 -User-Agent: curl/7.58.0 -Accept: */* -Content-Length: 14 -Content-Type: application/x-www-form-urlencoded - -{"foo": "bar"} ------------- -``` - -Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. - -Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/docs/administration/permissions.md b/docs/administration/permissions.md index 60717c28a..21f259979 100644 --- a/docs/administration/permissions.md +++ b/docs/administration/permissions.md @@ -1,8 +1,75 @@ -# Permissions +# Object-Based Permissions NetBox v2.9 introduced a new object-based permissions framework, which replaces Django's built-in permissions model. Object-based permissions enable an administrator to grant users or groups the ability to perform an action on arbitrary subsets of objects in NetBox, rather than all objects of a certain type. For example, it is possible to grant a user permission to view only sites within a particular region, or to modify only VLANs with a numeric ID within a certain range. -{!models/users/objectpermission.md!} +A permission in NetBox represents a relationship shared by several components: + +* Object type(s) - One or more types of object in NetBox +* User(s)/Group(s) - One or more users or groups of users +* Action(s) - The action(s) that can be performed on an object +* Constraints - An arbitrary filter used to limit the granted action(s) to a specific subset of objects + +At a minimum, a permission assignment must specify one object type, one user or group, and one action. The specification of constraints is optional: A permission without any constraints specified will apply to all instances of the selected model(s). + +## Actions + +There are four core actions that can be permitted for each type of object within NetBox, roughly analogous to the CRUD convention (create, read, update, and delete): + +* **View** - Retrieve an object from the database +* **Add** - Create a new object +* **Change** - Modify an existing object +* **Delete** - Delete an existing object + +In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `napalm_read` permission on the device model allows a user to execute NAPALM queries on a device via NetBox's REST API. These can be specified when granting a permission in the "additional actions" field. + +!!! note + Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named `actions`. + +## Constraints + +Constraints are expressed as a JSON object or list representing a [Django query filter](https://docs.djangoproject.com/en/stable/ref/models/querysets/#field-lookups). This is the same syntax that you would pass to the QuerySet `filter()` method when performing a query using the Django ORM. As with query filters, double underscores can be used to traverse related objects or invoke lookup expressions. Some example queries and their corresponding definitions are shown below. + +All attributes defined within a single JSON object are applied with a logical AND. For example, suppose you assign a permission for the site model with the following constraints. + +```json +{ + "status": "active", + "region__name": "Americas" +} +``` + +The permission will grant access only to sites which have a status of "active" **and** which are assigned to the "Americas" region. + +To achieve a logical OR with a different set of constraints, define multiple objects within a list. For example, if you want to constrain the permission to VLANs with an ID between 100 and 199 _or_ a status of "reserved," do the following: + +```json +[ + { + "vid__gte": 100, + "vid__lt": 200 + }, + { + "status": "reserved" + } +] +``` + +Additionally, where multiple permissions have been assigned for an object type, their collective constraints will be merged using a logical "OR" operation. + +### User Token + +!!! info "This feature was introduced in NetBox v3.3" + +When defining a permission constraint, administrators may use the special token `$user` to reference the current user at the time of evaluation. This can be helpful to restrict users to editing only their own journal entries, for example. Such a constraint might be defined as: + +```json +{ + "created_by": "$user" +} +``` + +The `$user` token can be used only as a constraint value, or as an item within a list of values. It cannot be modified or extended to reference specific user attributes. + #### Example Constraint Definitions diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md index 2aa21b7e5..614e90eac 100644 --- a/docs/configuration/miscellaneous.md +++ b/docs/configuration/miscellaneous.md @@ -127,7 +127,7 @@ A web user or API consumer can request an arbitrary number of objects by appendi Default: False -Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../additional-features/prometheus-metrics.md) documentation for more details. +Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../integrations/prometheus-metrics.md) documentation for more details. --- diff --git a/docs/configuration/napalm.md b/docs/configuration/napalm.md index 925ec17e6..253bea297 100644 --- a/docs/configuration/napalm.md +++ b/docs/configuration/napalm.md @@ -6,7 +6,7 @@ !!! tip "Dynamic Configuration Parameter" -NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional. +NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../integrations/napalm.md), if installed. Both parameters are optional. !!! note If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed. diff --git a/docs/customization/custom-fields.md b/docs/customization/custom-fields.md index 757416626..bfe412edc 100644 --- a/docs/customization/custom-fields.md +++ b/docs/customization/custom-fields.md @@ -1,4 +1,77 @@ -{!models/extras/customfield.md!} +# Custom Fields + +Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. + +However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. + +Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. + +## Creating Custom Fields + +Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: + +* Text: Free-form text (intended for single-line use) +* Long text: Free-form of any length; supports Markdown rendering +* Integer: A whole number (positive or negative) +* Boolean: True or false +* Date: A date in ISO 8601 format (YYYY-MM-DD) +* URL: This will be presented as a link in the web UI +* JSON: Arbitrary data stored in JSON format +* Selection: A selection of one of several pre-defined custom choices +* Multiple selection: A selection field which supports the assignment of multiple values +* Object: A single NetBox object of the type defined by `object_type` +* Multiple object: One or more NetBox objects of the type defined by `object_type` + +Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. + +Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. + +A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. + +### Filtering + +The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. + +### Grouping + +!!! note + This feature was introduced in NetBox v3.3. + +Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) + +This parameter has no effect on the API representation of custom field data. + +### Visibility + +!!! note + This feature was introduced in NetBox v3.3. + +When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. + +* **Read/write** (default): The custom field is included when viewing and editing objects. +* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. + +Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. + +### Validation + +NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: + +* Text: Regular expression (optional) +* Integer: Minimum and/or maximum value (optional) +* Selection: Must exactly match one of the prescribed choices + +### Custom Selection Fields + +Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. + +If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. + +### Custom Object Fields + +An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. + ## Custom Fields in Templates diff --git a/docs/models/extras/customlink.md b/docs/customization/custom-links.md similarity index 100% rename from docs/models/extras/customlink.md rename to docs/customization/custom-links.md diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index 3c7ff7d20..640a97531 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -1,4 +1,41 @@ -{!models/extras/exporttemplate.md!} +# Export Templates + +NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. + +Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. + +Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). + +!!! note + The name `table` is reserved for internal use. + +!!! warning + Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. + +The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: + +```jinja2 +{% for rack in queryset %} +Rack: {{ rack.name }} +Site: {{ rack.site.name }} +Height: {{ rack.u_height }}U +{% endfor %} +``` + +To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. + +If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: +``` +{% for server in queryset %} +{% set data = server.get_config_context() %} +{{ data.syslog }} +{% endfor %} +``` + +The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) + +A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. + ## REST API Integration diff --git a/docs/development/models.md b/docs/development/models.md index b6b2e4da2..be3608a30 100644 --- a/docs/development/models.md +++ b/docs/development/models.md @@ -8,12 +8,12 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/ ### Features Matrix -* [Change logging](../additional-features/change-logging.md) - Changes to these objects are automatically recorded in the change log -* [Webhooks](../additional-features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects +* [Change logging](../features/change-logging.md) - Changes to these objects are automatically recorded in the change log +* [Webhooks](../features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects * [Custom fields](../customization/custom-fields.md) - These models support the addition of user-defined fields * [Export templates](../customization/export-templates.md) - Users can create custom export templates for these models -* [Tagging](../models/extras/tag.md) - The models can be tagged with user-defined tags -* [Journaling](../additional-features/journaling.md) - These models support persistent historical commentary +* [Tagging](../features/tags.md) - The models can be tagged with user-defined tags +* [Journaling](../features/journaling.md) - These models support persistent historical commentary * Nesting - These models can be nested recursively to create a hierarchy | Type | Change Logging | Webhooks | Custom Fields | Export Templates | Tags | Journaling | Nesting | diff --git a/docs/additional-features/change-logging.md b/docs/features/change-logging.md similarity index 100% rename from docs/additional-features/change-logging.md rename to docs/features/change-logging.md diff --git a/docs/features/circuits.md b/docs/features/circuits.md new file mode 100644 index 000000000..63c8bc970 --- /dev/null +++ b/docs/features/circuits.md @@ -0,0 +1,3 @@ +# Circuits + +TODO diff --git a/docs/features/contacts.md b/docs/features/contacts.md new file mode 100644 index 000000000..fb23e53da --- /dev/null +++ b/docs/features/contacts.md @@ -0,0 +1,3 @@ +# Contacts + +TODO diff --git a/docs/models/extras/configcontext.md b/docs/features/context-data.md similarity index 100% rename from docs/models/extras/configcontext.md rename to docs/features/context-data.md diff --git a/docs/features/customization.md b/docs/features/customization.md new file mode 100644 index 000000000..ae775312e --- /dev/null +++ b/docs/features/customization.md @@ -0,0 +1,3 @@ +# Customization + +TODO diff --git a/docs/features/devices-cabling.md b/docs/features/devices-cabling.md new file mode 100644 index 000000000..ab09b4443 --- /dev/null +++ b/docs/features/devices-cabling.md @@ -0,0 +1,3 @@ +# Devices & Cabling + +TODO diff --git a/docs/features/facilities.md b/docs/features/facilities.md new file mode 100644 index 000000000..5ace5b18b --- /dev/null +++ b/docs/features/facilities.md @@ -0,0 +1,3 @@ +# Facilities + +TODO \ No newline at end of file diff --git a/docs/features/ipam.md b/docs/features/ipam.md new file mode 100644 index 000000000..f263f3ab3 --- /dev/null +++ b/docs/features/ipam.md @@ -0,0 +1,3 @@ +# IP Address Management + +TODO diff --git a/docs/additional-features/journaling.md b/docs/features/journaling.md similarity index 100% rename from docs/additional-features/journaling.md rename to docs/features/journaling.md diff --git a/docs/features/l2vpn-overlay.md b/docs/features/l2vpn-overlay.md new file mode 100644 index 000000000..002c483f9 --- /dev/null +++ b/docs/features/l2vpn-overlay.md @@ -0,0 +1,3 @@ +# L2VPN & Overlay + +TODO diff --git a/docs/features/permissions.md b/docs/features/permissions.md new file mode 100644 index 000000000..a422ca7b3 --- /dev/null +++ b/docs/features/permissions.md @@ -0,0 +1,3 @@ +# Object-Based Permissions + +TODO diff --git a/docs/features/power-tracking.md b/docs/features/power-tracking.md new file mode 100644 index 000000000..1267af1e6 --- /dev/null +++ b/docs/features/power-tracking.md @@ -0,0 +1,3 @@ +# Power Tracking + +TODO diff --git a/docs/features/services.md b/docs/features/services.md new file mode 100644 index 000000000..338fc349a --- /dev/null +++ b/docs/features/services.md @@ -0,0 +1,3 @@ +# Services + +TODO diff --git a/docs/features/sso.md b/docs/features/sso.md new file mode 100644 index 000000000..b4f9782c2 --- /dev/null +++ b/docs/features/sso.md @@ -0,0 +1,3 @@ +# Single Sign-On (SSO) + +TODO diff --git a/docs/models/extras/tag.md b/docs/features/tags.md similarity index 100% rename from docs/models/extras/tag.md rename to docs/features/tags.md diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md new file mode 100644 index 000000000..20534b13c --- /dev/null +++ b/docs/features/tenancy.md @@ -0,0 +1,3 @@ +# Tenancy + +TODO diff --git a/docs/features/vlan-management.md b/docs/features/vlan-management.md new file mode 100644 index 000000000..3d4fd4d1f --- /dev/null +++ b/docs/features/vlan-management.md @@ -0,0 +1,3 @@ +# VLAN Management + +TODO diff --git a/docs/models/extras/webhook.md b/docs/features/webhooks.md similarity index 67% rename from docs/models/extras/webhook.md rename to docs/features/webhooks.md index 9f64401ae..4705243d1 100644 --- a/docs/models/extras/webhook.md +++ b/docs/features/webhooks.md @@ -81,3 +81,59 @@ If no body template is specified, the request body will be populated with a JSON } } ``` + +## Conditional Webhooks + +A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": + +```json +{ + "and": [ + { + "attr": "status.value", + "value": "active" + } + ] +} +``` + +For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md). + +## Webhook Processing + +When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. + +A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. + +## Troubleshooting + +To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: + +```no-highlight +$ python netbox/manage.py webhook_receiver +Listening on port http://localhost:9000. Stop with CONTROL-C. +``` + +You can test the receiver itself by sending any HTTP request to it. For example: + +```no-highlight +$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' +``` + +The server will print output similar to the following: + +```no-highlight +[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - +Host: localhost:9000 +User-Agent: curl/7.58.0 +Accept: */* +Content-Length: 14 +Content-Type: application/x-www-form-urlencoded + +{"foo": "bar"} +------------ +``` + +Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. + +Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/docs/features/wireless.md b/docs/features/wireless.md new file mode 100644 index 000000000..ff3d5d10b --- /dev/null +++ b/docs/features/wireless.md @@ -0,0 +1,3 @@ +# Wireless + +TODO diff --git a/docs/getting-started/populating-data.md b/docs/getting-started/populating-data.md index e182a9d52..bb0e8e17f 100644 --- a/docs/getting-started/populating-data.md +++ b/docs/getting-started/populating-data.md @@ -39,4 +39,4 @@ Sometimes you'll find that data you need to populate in NetBox can be easily red You can also use the REST API to facilitate the population of data in NetBox. The REST API offers full programmatic control over the creation of objects, subject to the same validation rules enforced by the UI forms. Additionally, the REST API supports the bulk creation of multiple objects using a single request. -For more information about this option, see the [REST API documentation](../rest-api/overview.md). +For more information about this option, see the [REST API documentation](../integrations/rest-api.md). diff --git a/docs/installation/3-netbox.md b/docs/installation/3-netbox.md index 7c4a60500..eeb5e6f20 100644 --- a/docs/installation/3-netbox.md +++ b/docs/installation/3-netbox.md @@ -201,7 +201,7 @@ All Python packages required by NetBox are listed in `requirements.txt` and will ### NAPALM -Integration with the [NAPALM automation](../additional-features/napalm.md) library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The `NAPALM_USERNAME` and `NAPALM_PASSWORD` configuration parameters define the credentials to be used when connecting to a device. +Integration with the [NAPALM automation](../integrations/napalm.md) library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The `NAPALM_USERNAME` and `NAPALM_PASSWORD` configuration parameters define the credentials to be used when connecting to a device. ```no-highlight sudo sh -c "echo 'napalm' >> /opt/netbox/local_requirements.txt" diff --git a/docs/graphql-api/overview.md b/docs/integrations/graphql-api.md similarity index 100% rename from docs/graphql-api/overview.md rename to docs/integrations/graphql-api.md diff --git a/docs/additional-features/napalm.md b/docs/integrations/napalm.md similarity index 100% rename from docs/additional-features/napalm.md rename to docs/integrations/napalm.md diff --git a/docs/additional-features/prometheus-metrics.md b/docs/integrations/prometheus-metrics.md similarity index 100% rename from docs/additional-features/prometheus-metrics.md rename to docs/integrations/prometheus-metrics.md diff --git a/docs/rest-api/overview.md b/docs/integrations/rest-api.md similarity index 78% rename from docs/rest-api/overview.md rename to docs/integrations/rest-api.md index 5fc4f18bb..3a5aed055 100644 --- a/docs/rest-api/overview.md +++ b/docs/integrations/rest-api.md @@ -91,7 +91,7 @@ Lists of objects can be filtered using a set of query parameters. For example, t GET /api/dcim/interfaces/?device_id=123 ``` -See the [filtering documentation](filtering.md) for more details. +See the [filtering documentation](../reference/filtering.md) for more details. ## Serialization @@ -269,7 +269,7 @@ The brief format is supported for both lists and individual objects. ### Excluding Config Contexts -When retrieving devices and virtual machines via the REST API, each will included its rendered [configuration context data](../models/extras/configcontext.md) by default. Users with large amounts of context data will likely observe suboptimal performance when returning multiple objects, particularly with very high page sizes. To combat this, context data may be excluded from the response data by attaching the query parameter `?exclude=config_context` to the request. This parameter works for both list and detail views. +When retrieving devices and virtual machines via the REST API, each will include its rendered [configuration context data](../features/context-data.md) by default. Users with large amounts of context data will likely observe suboptimal performance when returning multiple objects, particularly with very high page sizes. To combat this, context data may be excluded from the response data by attaching the query parameter `?exclude=config_context` to the request. This parameter works for both list and detail views. ## Pagination @@ -387,7 +387,7 @@ curl -s -X GET http://netbox/api/ipam/ip-addresses/5618/ | jq '.' ### Creating a New Object -To create a new object, make a `POST` request to the model's _list_ endpoint with JSON data pertaining to the object being created. Note that a REST API token is required for all write operations; see the [authentication documentation](authentication.md) for more information. Also be sure to set the `Content-Type` HTTP header to `application/json`. +To create a new object, make a `POST` request to the model's _list_ endpoint with JSON data pertaining to the object being created. Note that a REST API token is required for all write operations; see the [authentication section](#authenticating-to-the-api) for more information. Also be sure to set the `Content-Type` HTTP header to `application/json`. ```no-highlight curl -s -X POST \ @@ -561,3 +561,96 @@ http://netbox/api/dcim/sites/ \ !!! note The bulk deletion of objects is an all-or-none operation, meaning that if NetBox fails to delete any of the specified objects (e.g. due a dependency by a related object), the entire operation will be aborted and none of the objects will be deleted. + +## Authentication + +The NetBox REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browsable API. + +### Tokens + +A token is a unique identifier mapped to a NetBox user account. Each user may have one or more tokens which he or she can use for authentication when making REST API requests. To create a token, navigate to the API tokens page under your user profile. + +!!! note + All users can create and manage REST API tokens under the user control panel in the UI. The ability to view, add, change, or delete tokens via the REST API itself is controlled by the relevant model permissions, assigned to users and/or groups in the admin UI. These permissions should be used with great care to avoid accidentally permitting a user to create tokens for other user accounts. + +Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, NetBox allows you to specify a key in case you need to restore a previously deleted token to operation. + +By default, a token can be used to perform all actions via the API that a user would be permitted to do via the web UI. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only. + +Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox. + +#### Client IP Restriction + +!!! note + This feature was introduced in NetBox v3.3. + +Each API token can optionally be restricted by client IP address. If one or more allowed IP prefixes/addresses is defined for a token, authentication will fail for any client connecting from an IP address outside the defined range(s). This enables restricting the use a token to a specific client. (By default, any client IP address is permitted.) + + +### Authenticating to the API + +An authentication token is attached to a request by setting the `Authorization` header to the string `Token` followed by a space and the user's token: + +``` +$ curl -H "Authorization: Token $TOKEN" \ +-H "Accept: application/json; indent=4" \ +https://netbox/api/dcim/sites/ +{ + "count": 10, + "next": null, + "previous": null, + "results": [...] +} +``` + +A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/security.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response: + +``` +$ curl https://netbox/api/dcim/sites/ +{ + "detail": "Authentication credentials were not provided." +} +``` + +When a token is used to authenticate a request, its `last_updated` time updated to the current time if its last use was recorded more than 60 seconds ago (or was never recorded). This allows users to determine which tokens have been active recently. + +!!! note + The "last used" time for tokens will not be updated while maintenance mode is enabled. + +### Initial Token Provisioning + +Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. NetBox provides a special endpoint to provision tokens using a valid username and password combination. + +To provision a token via the REST API, make a `POST` request to the `/api/users/tokens/provision/` endpoint: + +``` +$ curl -X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json; indent=4" \ +https://netbox/api/users/tokens/provision/ \ +--data '{ + "username": "hankhill", + "password": "I<3C3H8", +}' +``` + +Note that we are _not_ passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled. + +```json +{ + "id": 6, + "url": "https://netbox/api/users/tokens/6/", + "display": "3c9cb9 (hankhill)", + "user": { + "id": 2, + "url": "https://netbox/api/users/users/2/", + "display": "hankhill", + "username": "hankhill" + }, + "created": "2021-06-11T20:09:13.339367Z", + "expires": null, + "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9", + "write_enabled": true, + "description": "" +} +``` diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md deleted file mode 100644 index 3f6860758..000000000 --- a/docs/models/extras/customfield.md +++ /dev/null @@ -1,73 +0,0 @@ -# Custom Fields - -Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. - -However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. - -Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. - -## Creating Custom Fields - -Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: - -* Text: Free-form text (intended for single-line use) -* Long text: Free-form of any length; supports Markdown rendering -* Integer: A whole number (positive or negative) -* Boolean: True or false -* Date: A date in ISO 8601 format (YYYY-MM-DD) -* URL: This will be presented as a link in the web UI -* JSON: Arbitrary data stored in JSON format -* Selection: A selection of one of several pre-defined custom choices -* Multiple selection: A selection field which supports the assignment of multiple values -* Object: A single NetBox object of the type defined by `object_type` -* Multiple object: One or more NetBox objects of the type defined by `object_type` - -Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. - -Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. - -A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. - -### Filtering - -The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. - -### Grouping - -!!! note - This feature was introduced in NetBox v3.3. - -Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) - -This parameter has no effect on the API representation of custom field data. - -### Visibility - -!!! note - This feature was introduced in NetBox v3.3. - -When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. - -* **Read/write** (default): The custom field is included when viewing and editing objects. -* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) -* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. - -Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. - -### Validation - -NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: - -* Text: Regular expression (optional) -* Integer: Minimum and/or maximum value (optional) -* Selection: Must exactly match one of the prescribed choices - -### Custom Selection Fields - -Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. - -If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. - -### Custom Object Fields - -An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. diff --git a/docs/models/extras/exporttemplate.md b/docs/models/extras/exporttemplate.md deleted file mode 100644 index e76a3ad47..000000000 --- a/docs/models/extras/exporttemplate.md +++ /dev/null @@ -1,37 +0,0 @@ -# Export Templates - -NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. - -Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. - -Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). - -!!! note - The name `table` is reserved for internal use. - -!!! warning - Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. - -The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: - -```jinja2 -{% for rack in queryset %} -Rack: {{ rack.name }} -Site: {{ rack.site.name }} -Height: {{ rack.u_height }}U -{% endfor %} -``` - -To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. - -If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: -``` -{% for server in queryset %} -{% set data = server.get_config_context() %} -{{ data.syslog }} -{% endfor %} -``` - -The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) - -A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. diff --git a/docs/models/extras/imageattachment.md b/docs/models/extras/imageattachment.md deleted file mode 100644 index da15462ab..000000000 --- a/docs/models/extras/imageattachment.md +++ /dev/null @@ -1,3 +0,0 @@ -# Image Attachments - -Certain objects in NetBox support the attachment of uploaded images. These will be saved to the NetBox server and made available whenever the object is viewed. diff --git a/docs/models/users/objectpermission.md b/docs/models/users/objectpermission.md deleted file mode 100644 index 82dbc955a..000000000 --- a/docs/models/users/objectpermission.md +++ /dev/null @@ -1,69 +0,0 @@ -# Object Permissions - -A permission in NetBox represents a relationship shared by several components: - -* Object type(s) - One or more types of object in NetBox -* User(s)/Group(s) - One or more users or groups of users -* Action(s) - The action(s) that can be performed on an object -* Constraints - An arbitrary filter used to limit the granted action(s) to a specific subset of objects - -At a minimum, a permission assignment must specify one object type, one user or group, and one action. The specification of constraints is optional: A permission without any constraints specified will apply to all instances of the selected model(s). - -## Actions - -There are four core actions that can be permitted for each type of object within NetBox, roughly analogous to the CRUD convention (create, read, update, and delete): - -* **View** - Retrieve an object from the database -* **Add** - Create a new object -* **Change** - Modify an existing object -* **Delete** - Delete an existing object - -In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `napalm_read` permission on the device model allows a user to execute NAPALM queries on a device via NetBox's REST API. These can be specified when granting a permission in the "additional actions" field. - -!!! note - Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named `actions`. - -## Constraints - -Constraints are expressed as a JSON object or list representing a [Django query filter](https://docs.djangoproject.com/en/stable/ref/models/querysets/#field-lookups). This is the same syntax that you would pass to the QuerySet `filter()` method when performing a query using the Django ORM. As with query filters, double underscores can be used to traverse related objects or invoke lookup expressions. Some example queries and their corresponding definitions are shown below. - -All attributes defined within a single JSON object are applied with a logical AND. For example, suppose you assign a permission for the site model with the following constraints. - -```json -{ - "status": "active", - "region__name": "Americas" -} -``` - -The permission will grant access only to sites which have a status of "active" **and** which are assigned to the "Americas" region. - -To achieve a logical OR with a different set of constraints, define multiple objects within a list. For example, if you want to constrain the permission to VLANs with an ID between 100 and 199 _or_ a status of "reserved," do the following: - -```json -[ - { - "vid__gte": 100, - "vid__lt": 200 - }, - { - "status": "reserved" - } -] -``` - -Additionally, where multiple permissions have been assigned for an object type, their collective constraints will be merged using a logical "OR" operation. - -### User Token - -!!! info "This feature was introduced in NetBox v3.3" - -When defining a permission constraint, administrators may use the special token `$user` to reference the current user at the time of evaluation. This can be helpful to restrict users to editing only their own journal entries, for example. Such a constraint might be defined as: - -```json -{ - "created_by": "$user" -} -``` - -The `$user` token can be used only as a constraint value, or as an item within a list of values. It cannot be modified or extended to reference specific user attributes. diff --git a/docs/models/users/token.md b/docs/models/users/token.md deleted file mode 100644 index f6c5bfe80..000000000 --- a/docs/models/users/token.md +++ /dev/null @@ -1,19 +0,0 @@ -## Tokens - -A token is a unique identifier mapped to a NetBox user account. Each user may have one or more tokens which he or she can use for authentication when making REST API requests. To create a token, navigate to the API tokens page under your user profile. - -!!! note - All users can create and manage REST API tokens under the user control panel in the UI. The ability to view, add, change, or delete tokens via the REST API itself is controlled by the relevant model permissions, assigned to users and/or groups in the admin UI. These permissions should be used with great care to avoid accidentally permitting a user to create tokens for other user accounts. - -Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, NetBox allows you to specify a key in case you need to restore a previously deleted token to operation. - -By default, a token can be used to perform all actions via the API that a user would be permitted to do via the web UI. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only. - -Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox. - -### Client IP Restriction - -!!! note - This feature was introduced in NetBox v3.3. - -Each API token can optionally be restricted by client IP address. If one or more allowed IP prefixes/addresses is defined for a token, authentication will fail for any client connecting from an IP address outside the defined range(s). This enables restricting the use a token to a specific client. (By default, any client IP address is permitted.) diff --git a/docs/rest-api/filtering.md b/docs/reference/filtering.md similarity index 100% rename from docs/rest-api/filtering.md rename to docs/reference/filtering.md diff --git a/docs/release-notes/version-3.0.md b/docs/release-notes/version-3.0.md index 93ff33d95..06b889c22 100644 --- a/docs/release-notes/version-3.0.md +++ b/docs/release-notes/version-3.0.md @@ -357,7 +357,7 @@ And the response: ... ``` -All GraphQL requests are made at the `/graphql` URL (which also serves the GraphiQL UI). The API is currently read-only, however users who wish to disable it until needed can do so by setting the `GRAPHQL_ENABLED` configuration parameter to False. For more detail on NetBox's GraphQL implementation, see [the GraphQL API documentation](../graphql-api/overview.md). +All GraphQL requests are made at the `/graphql` URL (which also serves the GraphiQL UI). The API is currently read-only, however users who wish to disable it until needed can do so by setting the `GRAPHQL_ENABLED` configuration parameter to False. For more detail on NetBox's GraphQL implementation, see [the GraphQL API documentation](../integrations/graphql-api.md). #### IP Ranges ([#834](https://github.com/netbox-community/netbox/issues/834)) diff --git a/docs/rest-api/authentication.md b/docs/rest-api/authentication.md deleted file mode 100644 index 411063338..000000000 --- a/docs/rest-api/authentication.md +++ /dev/null @@ -1,73 +0,0 @@ -# REST API Authentication - -The NetBox REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browsable API. - -{!models/users/token.md!} - -## Authenticating to the API - -An authentication token is attached to a request by setting the `Authorization` header to the string `Token` followed by a space and the user's token: - -``` -$ curl -H "Authorization: Token $TOKEN" \ --H "Accept: application/json; indent=4" \ -https://netbox/api/dcim/sites/ -{ - "count": 10, - "next": null, - "previous": null, - "results": [...] -} -``` - -A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/security.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response: - -``` -$ curl https://netbox/api/dcim/sites/ -{ - "detail": "Authentication credentials were not provided." -} -``` - -When a token is used to authenticate a request, its `last_updated` time updated to the current time if its last use was recorded more than 60 seconds ago (or was never recorded). This allows users to determine which tokens have been active recently. - -!!! note - The "last used" time for tokens will not be updated while maintenance mode is enabled. - -## Initial Token Provisioning - -Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. NetBox provides a special endpoint to provision tokens using a valid username and password combination. - -To provision a token via the REST API, make a `POST` request to the `/api/users/tokens/provision/` endpoint: - -``` -$ curl -X POST \ --H "Content-Type: application/json" \ --H "Accept: application/json; indent=4" \ -https://netbox/api/users/tokens/provision/ \ ---data '{ - "username": "hankhill", - "password": "I<3C3H8", -}' -``` - -Note that we are _not_ passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled. - -```json -{ - "id": 6, - "url": "https://netbox/api/users/tokens/6/", - "display": "3c9cb9 (hankhill)", - "user": { - "id": 2, - "url": "https://netbox/api/users/users/2/", - "display": "hankhill", - "username": "hankhill" - }, - "created": "2021-06-11T20:09:13.339367Z", - "expires": null, - "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9", - "write_enabled": true, - "description": "" -} -``` diff --git a/mkdocs.yml b/mkdocs.yml index 4c5279127..f76a91484 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,6 +62,26 @@ markdown_extensions: alternate_style: true nav: - Introduction: 'introduction.md' + - Features: + - Facilities: 'features/facilities.md' + - Tenancy: 'features/tenancy.md' + - Contacts: 'features/contacts.md' + - Devices & Cabling: 'features/devices-cabling.md' + - Power Tracking: 'features/power-tracking.md' + - IPAM: 'features/ipam.md' + - VLAN Management: 'features/vlan-management.md' + - Service Mapping: 'features/services.md' + - L2VPN & Overlay: 'features/l2vpn-overlay.md' + - Circuits: 'features/circuits.md' + - Wireless: 'features/wireless.md' + - Context Data: 'features/context-data.md' + - Change Logging: 'features/change-logging.md' + - Journaling: 'features/journaling.md' + - Webhooks: 'features/webhooks.md' + - Tags: 'features/tags.md' + - Customization: 'features/customization.md' + - Object-Based Permissions: 'features/permissions.md' + - Single Sign-On (SSO): 'features/sso.md' - Installation & Upgrade: - Installing NetBox: 'installation/index.md' - 1. PostgreSQL: 'installation/1-postgresql.md' @@ -90,19 +110,16 @@ nav: - Development: 'configuration/development.md' - Customization: - Custom Fields: 'customization/custom-fields.md' + - Custom Links: 'customization/custom-links.md' - Custom Validation: 'customization/custom-validation.md' - - Custom Links: 'models/extras/customlink.md' - Export Templates: 'customization/export-templates.md' - - Custom Scripts: 'customization/custom-scripts.md' - Reports: 'customization/reports.md' - - Additional Features: - - Change Logging: 'additional-features/change-logging.md' - - Context Data: 'models/extras/configcontext.md' - - Journaling: 'additional-features/journaling.md' - - NAPALM: 'additional-features/napalm.md' - - Prometheus Metrics: 'additional-features/prometheus-metrics.md' - - Tags: 'models/extras/tag.md' - - Webhooks: 'additional-features/webhooks.md' + - Custom Scripts: 'customization/custom-scripts.md' + - Integrations: + - REST API: 'integrations/rest-api.md' + - GraphQL API: 'integrations/graphql-api.md' + - NAPALM: 'integrations/napalm.md' + - Prometheus Metrics: 'integrations/prometheus-metrics.md' - Plugins: - Using Plugins: 'plugins/index.md' - Developing Plugins: @@ -128,12 +145,6 @@ nav: - Housekeeping: 'administration/housekeeping.md' - Replicating NetBox: 'administration/replicating-netbox.md' - NetBox Shell: 'administration/netbox-shell.md' - - REST API: - - Overview: 'rest-api/overview.md' - - Filtering & Ordering: 'rest-api/filtering.md' - - Authentication: 'rest-api/authentication.md' - - GraphQL API: - - Overview: 'graphql-api/overview.md' - Data Model: - Circuits: - Circuit: 'models/circuits/circuit.md' @@ -143,8 +154,6 @@ nav: - Provider Network: 'models/circuits/providernetwork.md' - DCIM: - Cable: 'models/dcim/cable.md' - - CablePath: 'models/dcim/cablepath.md' - - CableTermination: 'models/dcim/cabletermination.md' - ConsolePort: 'models/dcim/consoleport.md' - ConsolePortTemplate: 'models/dcim/consoleporttemplate.md' - ConsoleServerPort: 'models/dcim/consoleserverport.md' @@ -203,7 +212,6 @@ nav: - VRF: 'models/ipam/vrf.md' - Tenancy: - Contact: 'models/tenancy/contact.md' - - ContactAssignment: 'models/tenancy/contactassignment.md' - ContactGroup: 'models/tenancy/contactgroup.md' - ContactRole: 'models/tenancy/contactrole.md' - Tenant: 'models/tenancy/tenant.md' @@ -219,6 +227,7 @@ nav: - WirelessLANGroup: 'models/wireless/wirelesslangroup.md' - WirelessLink: 'models/wireless/wirelesslink.md' - Reference: + - Filtering: 'reference/filtering.md' - Conditions: 'reference/conditions.md' - Markdown: 'reference/markdown.md' - Development: From 4c899f151cce9fae6ae1596c481f2fa92e6a6cf9 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 4 Aug 2022 14:12:51 -0400 Subject: [PATCH 206/245] Drop markdown-include --- mkdocs.yml | 3 --- requirements.txt | 1 - 2 files changed, 4 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index f76a91484..78ca5031c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,9 +47,6 @@ extra_css: markdown_extensions: - admonition - attr_list - - markdown_include.include: - base_path: 'docs/' - headingOffset: 1 - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg diff --git a/requirements.txt b/requirements.txt index 8a7dd79d4..facf925f4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -19,7 +19,6 @@ graphene-django==2.15.0 gunicorn==20.1.0 Jinja2==3.1.2 Markdown==3.4.1 -markdown-include==0.7.0 mkdocs-material==8.3.9 mkdocstrings[python-legacy]==0.19.0 netaddr==0.8.0 From 8c0ef1a0a2e324a8b46af2591a9f1b087fcecb4d Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 4 Aug 2022 16:35:32 -0400 Subject: [PATCH 207/245] Started on feature docs --- docs/features/contacts.md | 23 +++++++++- docs/features/devices-cabling.md | 78 +++++++++++++++++++++++++++++++- docs/features/facilities.md | 57 ++++++++++++++++++++++- docs/features/tenancy.md | 18 +++++++- 4 files changed, 172 insertions(+), 4 deletions(-) diff --git a/docs/features/contacts.md b/docs/features/contacts.md index fb23e53da..7d717b2de 100644 --- a/docs/features/contacts.md +++ b/docs/features/contacts.md @@ -1,3 +1,24 @@ # Contacts -TODO +Much like [tenancy](./tenancy.md), contact assignment enables you to track ownership of resources modeled in NetBox. A contact represents an individual responsible for a resource within the context of its assigned role. + +```mermaid +flowchart TD + ContactGroup --> ContactGroup & Contact + ContactRole & Contact --> assignment([Assignment]) + assignment --> Object +``` + +## Contact Groups + +Contacts can be grouped arbitrarily into a recursive hierarchy, and a contact can be assigned to a group at any level within the hierarchy. + +## Contact Roles + +A contact role defines the relationship of a contact to an assigned object. For example, you might define roles for administrative, operational, and emergency contacts. + +## Contacts + +A contact should represent an individual or permanent point of contact. Each contact must define a name, and may optionally include a title, phone number, email address, and related details. + +Contacts are reused for assignments, so each unique contact must be created only once and can be assigned to any number of NetBox objects, and there is no limit to the number of assigned contacts an object may have. Most core objects in NetBox can have contacts assigned to them. diff --git a/docs/features/devices-cabling.md b/docs/features/devices-cabling.md index ab09b4443..7297f79ac 100644 --- a/docs/features/devices-cabling.md +++ b/docs/features/devices-cabling.md @@ -1,3 +1,79 @@ # Devices & Cabling -TODO +At its heart, NetBox is a tool for modeling your network infrastructure, and the device object is pivotal to that function. A device can be any piece of physical hardware installed within your network, such as server, router, or switch, and may optionally be mounted within a rack. Within each device, resources such as network interfaces and console ports are modeled as discrete components, which may optionally be grouped into modules. + +NetBox uses device types to represent unique real-world device models. This allows a user to define a device type and all its components once, and easily replicate an unlimited number of device instances from it. + +```mermaid +flowchart TD + Manufacturer -.-> Platform & DeviceType & ModuleType + Manufacturer --> DeviceType & ModuleType + DeviceRole & Platform & DeviceType --> Device + Device & ModuleType ---> Module + Device & Module --> Interface & ConsolePort & PowerPort & ... +``` + +## Manufacturers + +A manufacturer generally represents an organization which produces hardware devices. These can be defined by users, however they should represent an actual entity rather than some abstract idea. + +## Device Types + +A device type represents a unique combination of manufacturer and hardware model which maps to discrete make and model of device which exists in the real world. Each device type typically has a number of components created on it, representing network interfaces, device bays, and so on. New devices of this type can then be created in NetBox, and any associated components will be automatically replicated from the device type. This avoids needing to tediously recreate components for each device as it is added in NetBox. + +!!! tip "The Device Type Library" + While users are always free to create their own device types in NetBox, many find it convenient to draw from our [community library](https://github.com/netbox-community/devicetype-library) of pre-defined device types. This is possible because a particular make and model of device is applicable universally and never changes. + +All the following can be modeled as components: + +* Interfaces +* Console ports +* Console server ports +* Power ports +* Power outlets +* Pass-through ports (front and rear) +* Module bays (which house modules) +* Device bays (which house child devices) + +For example, a Juniper EX4300-48T device type might have the following component templates defined: + +* One template for a console port ("Console") +* Two templates for power ports ("PSU0" and "PSU1") +* 48 templates for 1GE interfaces ("ge-0/0/0" through "ge-0/0/47") +* Four templates for 10GE interfaces ("xe-0/2/0" through "xe-0/2/3") + +Once component templates have been created, every new device that you create as an instance of this type will automatically be assigned each of the components listed above. + +!!! note "Component Instantiation is not Retroactive" + The instantiation of components from a device type definition occurs only at the time of device creation. If you modify the components assigned to a device type, it will not affect devices which have already been created. This guards against any inadvertent changes to existing devices. However, you always have the option of adding, modifying, or deleting components on existing devices. (These changes can easily be applied to multiple devices at once using the bulk operations available in the UI.) + +## Devices + +Whereas a device type defines the make and model of a device, a device itself represents an actual piece of installed hardware somewhere in the real world. A device can be installed at a particular position within an equipment rack, or simply associated with a site (and optionally with a location within that site). + +Each device can have an operational status, functional role, and software platform assigned. Device components are instantiated automatically from the assigned device type upon creation. + +### Virtual Chassis + +Sometimes it is necessary to model a set of physical devices as sharing a single management plane. Perhaps the most common example of such a scenario is stackable switches. These can be modeled as virtual chassis in NetBox, with one device acting as the chassis master and the rest as members. All components of member devices will appear on the master. + +## Module Types & Modules + +Much like device types and devices, module types can instantiate discrete modules, which are hardware components installed within devices. Modules often have their own child components, which become available to the parent device. For example, when modeling a chassis-based switch with multiple line cards in NetBox, the chassis would be created (from a device type) as a device, and each of its line cards would be instantiated from a module type as a module installed in one of the device's module bays. + +!!! tip "Device Bays vs. Module Bays" + What's the difference between device bays and module bays? Device bays are appropriate when the installed hardware has its own management plane, isolated from the parent device. A common example is a blade server chassis in which the blades share power but operate independently. In contrast, a module bay holds a module which does _not_ operate independently of its parent device, as with the chassis switch line card example mentioned above. + +One especially nice feature of modules is that templated components can be automatically renamed according to the module bay into which the parent module is installed. For example, if we create a module type with interfaces named `Gi{module}/0/1-48` and install a module of this type into module bay 7 of a device, NetBox will create interfaces named `Gi7/0/1-48`. + +## Cables + +NetBox models cables as connections among certain types of device components and other objects. Each cable can be assigned a type, color, length, and label. NetBox will enforce basic sanity checks to prevent invalid connections. (For example, a network interface cannot be connected to a power outlet.) + +Either end of a cable may terminate to multiple objects of the same type. For example, a network interface can be connected via a fiber optic cable to two discrete ports on a patch panel (each port attaching to an individual fiber strand in the patch cable). + +```mermaid +flowchart LR + Interface --> Cable + Cable --> fp1[Front Port] & fp2[Front Port] +``` diff --git a/docs/features/facilities.md b/docs/features/facilities.md index 5ace5b18b..0fb65aae7 100644 --- a/docs/features/facilities.md +++ b/docs/features/facilities.md @@ -1,3 +1,58 @@ # Facilities -TODO \ No newline at end of file +From global regions down to individual equipment racks, NetBox allows you to model your network's entire presence. This is accomplished through the use of several purpose-built models. The graph below illustrates these models and their relationships. + +```mermaid +flowchart TD + Region --> Region + SiteGroup --> SiteGroup + Region & SiteGroup --> Site + Site --> Location & Device + Location --> Location + Location --> Rack & Device + Rack --> Device + Site --> Rack + RackRole --> Rack +``` + +## Regions + +Regions represent geographic domains in which your network or its customers have a presence. These are typically used to model countries, states, and cities, although NetBox does not prescribe any precise uses and your needs may differ. + +Regions are self-nesting, so you can define child regions within a parent, and grandchildren within each child. For example, you might create a hierarchy like this: + +* Europe + * France + * Germany + * Spain +* North America + * Canada + * United States + * California + * New York + * Texas + +Regions will always be listed alphabetically by name within each parent, and there is no maximum depth for the hierarchy. + +## Site Groups + +Like regions, site groups can be arranged in a recursive hierarchy for grouping sites. However, whereas regions are intended for geographic organization, site groups may be used for functional grouping. For example, you might classify sites as corporate, branch, or customer sites in addition to where they are physically located. + +The use of both regions and site groups affords to independent but complementary dimensions across which sites can be organized. + +## Site + +A site typically represents a building within a region and/or site group. Each site is assigned an operational status (e.g. active or planned), and can have a discrete mailing address and GPS coordinates assigned to it. + +## Location + +A location can be any logical subdivision within a building, such as a floor or room. Like regions and site groups, locations can be nested into a self-recursive hierarchy for maximum flexibility. And like sites, each location has an operational status assigned to it. + +## Rack + +Finally, NetBox models each equipment rack as a discrete object within a site and location. These are physical objects into which devices are installed. Each rack can be assigned an operational status, type, facility ID, and other attributes related to inventory tracking. Each rack also must define a height (in rack units) and width, and may optionally specify its physical dimensions. + +Each rack must be associated to a site, but the assignment to a location within that site is optional. Users can also create custom roles to which racks can be assigned. + +!!! tip "Devices" + You'll notice in the diagram above that a device can be installed within a site, location, or rack. This approach affords plenty of flexibility as not all sites need to define child locations, and not all devices reside in racks. diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md index 20534b13c..fe6d8e5a8 100644 --- a/docs/features/tenancy.md +++ b/docs/features/tenancy.md @@ -1,3 +1,19 @@ # Tenancy -TODO +Most core objects within NetBox's data model support _tenancy_. This is the association of an object with a particular tenant to convey ownership or dependency. For example, an enterprise might represent its internal business units as tenants, whereas a managed services provider might create a tenant in NetBox to represent each of its customers. + +```mermaid +flowchart TD + TenantGroup --> TenantGroup & Tenant + Tenant --> Site & Device & Prefix & Circuit & ... +``` + +## Tenant Groups + +Tenants can be grouped by any logic that your use case demands, and groups can nested recursively for maximum flexibility. For example, You might define a parent "Customers" group with child groups "Current" and "Past" within it. A tenant can be assigned to a group at any level within the hierarchy. + +## Tenants + +Typically, the tenant model is used to represent a customer or internal organization, however it can be used for whatever purpose meets your needs. + +Most core objects within NetBox can be assigned to particular tenant, so this model provides a very convenient way to correlate ownership across object types. For example, each of your customers might have its own racks, devices, IP addresses, circuits and so on: These can all be easily tracked via tenant assignment. From 602cf8c5fa371d767af70c6d0d9333c5732e9c7f Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 9 Aug 2022 11:29:42 -0400 Subject: [PATCH 208/245] Fixes #9939: Fix list of next nodes for split paths under trace view --- docs/release-notes/version-3.3.md | 17 ++--------------- netbox/dcim/models/cables.py | 4 ++-- 2 files changed, 4 insertions(+), 17 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 2a3935e5e..74ed7f10c 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -97,22 +97,9 @@ Custom field UI visibility has no impact on API operation. * [#9536](https://github.com/netbox-community/netbox/issues/9536) - Track API token usage times * [#9582](https://github.com/netbox-community/netbox/issues/9582) - Enable assigning config contexts based on device location -### Bug Fixes (from Beta1) +### Bug Fixes (from Beta2) -* [#9728](https://github.com/netbox-community/netbox/issues/9728) - Fix validation when assigning a virtual machine to a device -* [#9729](https://github.com/netbox-community/netbox/issues/9729) - Fix ordering of content type creation to ensure compatability with demo data -* [#9730](https://github.com/netbox-community/netbox/issues/9730) - Fix validation error when creating a new cable via UI form -* [#9733](https://github.com/netbox-community/netbox/issues/9733) - Handle split paths during trace when fanning out to front ports with differing cables -* [#9765](https://github.com/netbox-community/netbox/issues/9765) - Report correct segment count under cable trace UI view -* [#9778](https://github.com/netbox-community/netbox/issues/9778) - Fix exception during cable deletion after deleting a connected termination -* [#9788](https://github.com/netbox-community/netbox/issues/9788) - Ensure denormalized fields on CableTermination are kept in sync with related objects -* [#9789](https://github.com/netbox-community/netbox/issues/9789) - Fix rendering of cable traces ending at provider networks -* [#9794](https://github.com/netbox-community/netbox/issues/9794) - Fix link to connect a rear port to a circuit termination -* [#9818](https://github.com/netbox-community/netbox/issues/9818) - Fix circuit side selection when connecting a cable to a circuit termination -* [#9829](https://github.com/netbox-community/netbox/issues/9829) - Arrange custom fields by group when editing objects -* [#9843](https://github.com/netbox-community/netbox/issues/9843) - Fix rendering of custom field values (regression from #9647) -* [#9844](https://github.com/netbox-community/netbox/issues/9844) - Fix interface api request when creating/editing L2VPN termination -* [#9847](https://github.com/netbox-community/netbox/issues/9847) - Respect `desc_units` when ordering rack units +* [#9939](https://github.com/netbox-community/netbox/issues/9939) - Fix list of next nodes for split paths under trace view ### Plugins API diff --git a/netbox/dcim/models/cables.py b/netbox/dcim/models/cables.py index 321d808ff..2be64451f 100644 --- a/netbox/dcim/models/cables.py +++ b/netbox/dcim/models/cables.py @@ -677,6 +677,6 @@ class CablePath(models.Model): """ Return all available next segments in a split cable path. """ - rearport = path_node_to_object(self._nodes[-1]) + rearports = self.path_objects[-1] - return FrontPort.objects.filter(rear_port=rearport) + return FrontPort.objects.filter(rear_port__in=rearports) From 7dc2e02e226445cffc84deae682c8c9cdeed8dc3 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 9 Aug 2022 11:39:04 -0400 Subject: [PATCH 209/245] Fixes #9938: Exclude virtual interfaces from terminations list when connecting a cable --- docs/release-notes/version-3.3.md | 1 + netbox/dcim/forms/connections.py | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 74ed7f10c..c7d1a30ff 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -99,6 +99,7 @@ Custom field UI visibility has no impact on API operation. ### Bug Fixes (from Beta2) +* [#9938](https://github.com/netbox-community/netbox/issues/9938) - Exclude virtual interfaces from terminations list when connecting a cable * [#9939](https://github.com/netbox-community/netbox/issues/9939) - Fix list of next nodes for split paths under trace view ### Plugins API diff --git a/netbox/dcim/forms/connections.py b/netbox/dcim/forms/connections.py index 7552c0c87..cc5cf362f 100644 --- a/netbox/dcim/forms/connections.py +++ b/netbox/dcim/forms/connections.py @@ -84,6 +84,7 @@ def get_cable_form(a_type, b_type): disabled_indicator='_occupied', query_params={ 'device_id': f'$termination_{cable_end}_device', + 'kind': 'physical', # Exclude virtual interfaces } ) From c1d9cace117fb593fd8e332c370e05096017dac5 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 9 Aug 2022 14:21:27 -0400 Subject: [PATCH 210/245] Fixes #9900: Pre-populate site & rack fields for cable connection form --- docs/release-notes/version-3.3.md | 1 + netbox/dcim/tables/template_code.py | 50 ++++++++++---------- netbox/templates/dcim/consoleport.html | 6 +-- netbox/templates/dcim/consoleserverport.html | 6 +-- netbox/templates/dcim/frontport.html | 12 ++--- netbox/templates/dcim/interface.html | 8 ++-- netbox/templates/dcim/powerfeed.html | 2 +- netbox/templates/dcim/poweroutlet.html | 2 +- netbox/templates/dcim/powerport.html | 4 +- netbox/templates/dcim/rearport.html | 8 ++-- 10 files changed, 50 insertions(+), 49 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index c7d1a30ff..9ec4eb9b5 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -99,6 +99,7 @@ Custom field UI visibility has no impact on API operation. ### Bug Fixes (from Beta2) +* [#9900](https://github.com/netbox-community/netbox/issues/9900) - Pre-populate site & rack fields for cable connection form * [#9938](https://github.com/netbox-community/netbox/issues/9938) - Exclude virtual interfaces from terminations list when connecting a cable * [#9939](https://github.com/netbox-community/netbox/issues/9939) - Fix list of next nodes for split paths under trace view diff --git a/netbox/dcim/tables/template_code.py b/netbox/dcim/tables/template_code.py index 082df56df..04ef74192 100644 --- a/netbox/dcim/tables/template_code.py +++ b/netbox/dcim/tables/template_code.py @@ -121,9 +121,9 @@ CONSOLEPORT_BUTTONS = """ {% else %} @@ -153,9 +153,9 @@ CONSOLESERVERPORT_BUTTONS = """ {% else %} @@ -185,8 +185,8 @@ POWERPORT_BUTTONS = """ {% else %} @@ -212,7 +212,7 @@ POWEROUTLET_BUTTONS = """ {% if not record.mark_connected %} - + {% else %} @@ -262,10 +262,10 @@ INTERFACE_BUTTONS = """ {% else %} @@ -301,12 +301,12 @@ FRONTPORT_BUTTONS = """ {% else %} @@ -338,12 +338,12 @@ REARPORT_BUTTONS = """ {% else %} diff --git a/netbox/templates/dcim/consoleport.html b/netbox/templates/dcim/consoleport.html index f132a4ed8..39ffbf552 100644 --- a/netbox/templates/dcim/consoleport.html +++ b/netbox/templates/dcim/consoleport.html @@ -111,13 +111,13 @@ diff --git a/netbox/templates/dcim/consoleserverport.html b/netbox/templates/dcim/consoleserverport.html index f4da080e8..642e758a3 100644 --- a/netbox/templates/dcim/consoleserverport.html +++ b/netbox/templates/dcim/consoleserverport.html @@ -113,13 +113,13 @@ diff --git a/netbox/templates/dcim/frontport.html b/netbox/templates/dcim/frontport.html index e5f1df5ae..2ef955fe9 100644 --- a/netbox/templates/dcim/frontport.html +++ b/netbox/templates/dcim/frontport.html @@ -109,22 +109,22 @@ diff --git a/netbox/templates/dcim/interface.html b/netbox/templates/dcim/interface.html index 11e776872..7503e1be2 100644 --- a/netbox/templates/dcim/interface.html +++ b/netbox/templates/dcim/interface.html @@ -263,16 +263,16 @@ diff --git a/netbox/templates/dcim/powerfeed.html b/netbox/templates/dcim/powerfeed.html index 3972b30f3..584454df8 100644 --- a/netbox/templates/dcim/powerfeed.html +++ b/netbox/templates/dcim/powerfeed.html @@ -158,7 +158,7 @@ {% if not object.mark_connected and not object.cable %}
    {% if perms.dcim.add_cable %} - + Connect {% endif %} diff --git a/netbox/templates/dcim/poweroutlet.html b/netbox/templates/dcim/poweroutlet.html index 930d60996..26f4a07f8 100644 --- a/netbox/templates/dcim/poweroutlet.html +++ b/netbox/templates/dcim/poweroutlet.html @@ -111,7 +111,7 @@
    Not Connected {% if perms.dcim.add_cable %} - + Connect {% endif %} diff --git a/netbox/templates/dcim/powerport.html b/netbox/templates/dcim/powerport.html index 6da35617d..c5eccbf14 100644 --- a/netbox/templates/dcim/powerport.html +++ b/netbox/templates/dcim/powerport.html @@ -117,10 +117,10 @@ diff --git a/netbox/templates/dcim/rearport.html b/netbox/templates/dcim/rearport.html index ae7b55316..dc53746db 100644 --- a/netbox/templates/dcim/rearport.html +++ b/netbox/templates/dcim/rearport.html @@ -105,16 +105,16 @@ From 1a0b6d6cb03c144caf770f9ccd02ce0970b8c37e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 9 Aug 2022 16:49:28 -0400 Subject: [PATCH 211/245] Continued work on feature docs --- docs/features/facilities.md | 8 ++--- docs/features/ipam.md | 55 ++++++++++++++++++++++++++++++++- docs/features/power-tracking.md | 19 +++++++++++- 3 files changed, 76 insertions(+), 6 deletions(-) diff --git a/docs/features/facilities.md b/docs/features/facilities.md index 0fb65aae7..f105bd4c5 100644 --- a/docs/features/facilities.md +++ b/docs/features/facilities.md @@ -40,19 +40,19 @@ Like regions, site groups can be arranged in a recursive hierarchy for grouping The use of both regions and site groups affords to independent but complementary dimensions across which sites can be organized. -## Site +## Sites A site typically represents a building within a region and/or site group. Each site is assigned an operational status (e.g. active or planned), and can have a discrete mailing address and GPS coordinates assigned to it. -## Location +## Locations A location can be any logical subdivision within a building, such as a floor or room. Like regions and site groups, locations can be nested into a self-recursive hierarchy for maximum flexibility. And like sites, each location has an operational status assigned to it. -## Rack +## Racks Finally, NetBox models each equipment rack as a discrete object within a site and location. These are physical objects into which devices are installed. Each rack can be assigned an operational status, type, facility ID, and other attributes related to inventory tracking. Each rack also must define a height (in rack units) and width, and may optionally specify its physical dimensions. -Each rack must be associated to a site, but the assignment to a location within that site is optional. Users can also create custom roles to which racks can be assigned. +Each rack must be associated to a site, but the assignment to a location within that site is optional. Users can also create custom roles to which racks can be assigned. NetBox supports tracking rack space in half-unit increments, so it's possible to mount devices at e.g. position 2.5 within a rack. !!! tip "Devices" You'll notice in the diagram above that a device can be installed within a site, location, or rack. This approach affords plenty of flexibility as not all sites need to define child locations, and not all devices reside in racks. diff --git a/docs/features/ipam.md b/docs/features/ipam.md index f263f3ab3..7832fab44 100644 --- a/docs/features/ipam.md +++ b/docs/features/ipam.md @@ -1,3 +1,56 @@ # IP Address Management -TODO +IP address management (IPAM) is one of NetBox's core features. It supports full parity for IP4 and IPv6, advanced VRF assignment, automatic hierarchy formation, and much more. + +## IP Hierarchy + +NetBox employs several object types to represent a hierarchy of IP resources: + +* **Aggregate** - A prefix which represents the root of an addressing hierarchy. This is typically a large swath of public or private address space allocated for use by your organization. Each aggregate is assigned to an authoritative RIR. +* **Prefix** - A subnet defined within an aggregate. Prefixes extend the hierarchy by nesting within one another. (For example, 192.168.123.0/24 will appear within 192.168.0.0/16.) Each prefix can be assigned a functional role as well as an operational status. +* **IP Range** - An arbitrary range of individual IP addresses within a prefix, all sharing the same mask. Ranges are commonly affiliated with DHCP scopes, but can be used for any similar purpose. +* **IP Address** - An individual IP address along with its subnet mask, automatically arranged beneath its parent prefix. + +```mermaid +flowchart TD + RIR --> Aggregate + Aggregate & Role --> Prefix + Prefix --> Prefix + Prefix --> IPRange & IPAddress +``` + +!!! tip "Automatic Hierarchies" + IP objects in NetBox never need to be manually assigned to the parent objects. The construction of hierarchies is handled automatically by the application according to the inherent rules of IP addressing. + +An example hierarchy might look like this: + +* 100.64.0.0/10 (aggregate) + * 100.64.0.0/20 (prefix) + * 100.64.16.0/20 (prefix) + * 100.64.16.0/24 (prefix) + * 100.64.16.1/24 (address) + * 100.64.16.2/24 (address) + * 100.64.16.3/24 (address) + * 100.64.16.9/24 (prefix) + * 100.64.32.0/20 (prefix) + * 100.64.32.1/24 (address) + * 100.64.32.10-99/24 (range) + +## Utilization Stats + +The utilization rate for each prefix is calculated automatically depending on its status. _Container_ prefixes are those which house child prefixes; their utilization rate is determined based on how much of their available IP space is consumed by child prefixes. The utilization rate for any other type of prefix is determined by the aggregate usage of any child IP addresses and/or ranges defined. + +Similarly, utilization rates for aggregates is determined based on the space consumed by their child prefixes. + +## VRF Tracking + +NetBox supports the modeling of discrete virtual routing and forwarding (VRF) instances to represent multiple routing tables, including those with overlapping address space. Each type of IP object within an aggregate - prefix, IP range, and IP address - can be assigned to a particular VRF. Consequently, each VRF maintains its own isolated IP hierarchy. This makes it very easy to track overlapping IP space. + +VRF modeling in NetBox very closely follows what you find in real-world network configurations, with each VRF assigned a standards-compliant route distinguisher. You can even create route targets to manage the import and export of routing information among VRFs. + +!!! tip "Enforcing Unique IP Space" + Each VRF can be independently configured to permit or prohibit duplicate IP objects. For example, a VRF which has been configured to enforce unique IP space will not allow the creation of two 192.0.2.0/24 prefixes. The ability to toggle this restriction per VRF affords the user maximum flexibility in modeling their IP space. + +## AS Numbers + +An often overlooked component of IPAM, NetBox also tracks autonomous system (AS) numbers and their assignment to sites. Both 16- and 32-bit AS numbers are supported, and like aggregates each ASN is assigned to an authoritative RIR. diff --git a/docs/features/power-tracking.md b/docs/features/power-tracking.md index 1267af1e6..e19ec421b 100644 --- a/docs/features/power-tracking.md +++ b/docs/features/power-tracking.md @@ -1,3 +1,20 @@ # Power Tracking -TODO +As part of its DCIM feature set, NetBox supports modeling facility power as discrete power panels and feeds. These are most commonly used to document power distribution within a data center, but can serve more traditional environments as well. + +![Power distribution model](../media/power_distribution.png) + +## Power Panels + +A power panel is the furthest upstream power element modeled in NetBox. It typically represents a power distribution panel (or breaker panel) where facility power is split into multiple discrete circuits, which are modeled as feeds. + +Each power panel is associated with a site, and may optionally be associated with a particular location within that site. There is no limit to how many power feeds a single panel can supply, however both of these object types should map to real-world objects. + +## Power Feeds + +A power feed represents a discrete power circuit originating from an upstream power panel. Each power feed can be assigned a name, operational status, and various electrical characteristics such as supply (AC or DC), voltage, amperage, and so on. + +A device power port can be connected to a power feed via a cable. Only one port can be connected to a feed: Where multiple devices draw power from the same feed, a power distribution unit (PDU) must be modeled as an individual device mapping a power port to multiple power outlets to which the downstream devices can connect (as in the example above). + +!!! tip "Primary and Redundant Power" + Each power feed in NetBox is assigned a type: primary or redundant. This allows easily modeling redundant power distribution topologies. In scenarios involving only a single, non-redundant power supply, mark all power feeds as primary. From e69be8f9a631e255caf08b838951d2041efbf4b1 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 10 Aug 2022 12:51:21 -0400 Subject: [PATCH 212/245] Continued work on feature docs --- docs/features/circuits.md | 26 +++++++++++++++++++++++++- docs/features/ipam.md | 6 ++++++ docs/features/l2vpn-overlay.md | 4 +++- docs/features/services.md | 3 --- docs/features/vlan-management.md | 19 ++++++++++++++++++- docs/features/wireless.md | 25 ++++++++++++++++++++++++- mkdocs.yml | 1 - 7 files changed, 76 insertions(+), 8 deletions(-) delete mode 100644 docs/features/services.md diff --git a/docs/features/circuits.md b/docs/features/circuits.md index 63c8bc970..f0c5832c4 100644 --- a/docs/features/circuits.md +++ b/docs/features/circuits.md @@ -1,3 +1,27 @@ # Circuits -TODO +NetBox is ideal for managing your network's transit and peering providers and circuits. It provides all the flexibility needed to model physical circuits in both data center and enterprise environments, and allows for "connecting" circuits directly to device interfaces via cables. + +```mermaid +flowchart TD + ASN --> Provider + Provider --> ProviderNetwork & Circuit + CircuitType --> Circuit +``` + +## Providers + +A provider is any organization which provides Internet or private connectivity. Typically, these are large carriers, however they might also include regional providers or even internal services. Each provider can be assigned account and contact details, and may have one or more AS numbers assigned to it. + +Sometimes you'll need to model provider networks into which you don't have full visibility; these are typically represented on topology diagrams with cloud icons. NetBox facilitates this through its provider network model: A provider network represents a "black box" network to which your circuits can connect. A common example is a provider MPLS network connecting multiple sites. + +## Circuits + +A circuit is a physical connection between two points, which is installed and maintained by an external provider. For example, an Internet connection delivered as a fiber optic cable would be modeled as a circuit in NetBox. + +Each circuit is associated with a provider and assigned a circuit ID, which must be unique to that provider. A circuit is also assigned a user-defined type, operational status, and various other operating characteristics. + +Each circuit may have up to two terminations (A and Z) defined. Each termination can be associated with a particular site or provider network. In the case of the former, a cable can be connected between the circuit termination and a device component to map its physical connectivity. + +!!! warning "Physical vs. Virtual Circuits" + The circuit model in NetBox represents **physical** connections. Don't confuse these with _virtual_ circuits which may be offered by providers overlaid on physical infrastructure. (For example, a VLAN-tagged subinterface would be a virtual circuit.) A good rule of thumb: If you can't point to it, it's not a physical circuit. diff --git a/docs/features/ipam.md b/docs/features/ipam.md index 7832fab44..45a6a0221 100644 --- a/docs/features/ipam.md +++ b/docs/features/ipam.md @@ -54,3 +54,9 @@ VRF modeling in NetBox very closely follows what you find in real-world network ## AS Numbers An often overlooked component of IPAM, NetBox also tracks autonomous system (AS) numbers and their assignment to sites. Both 16- and 32-bit AS numbers are supported, and like aggregates each ASN is assigned to an authoritative RIR. + +## Service Mapping + +NetBox models network applications as discrete service objects associated with devices and/or virtual machines, and optionally with specific IP addresses attached to those parent objects. These can be used to catalog the applications running on your network for reference by other objects or integrated tools. + +To model services in NetBox, begin by creating a service template defining the name, protocol, and port number(s) on which the service listens. This template can then be easily instantiated to "attach" new services to a device or virtual machine. It's also possible to create new services by hand, without a template, however this approach can be tedious. diff --git a/docs/features/l2vpn-overlay.md b/docs/features/l2vpn-overlay.md index 002c483f9..51fbf2a78 100644 --- a/docs/features/l2vpn-overlay.md +++ b/docs/features/l2vpn-overlay.md @@ -1,3 +1,5 @@ # L2VPN & Overlay -TODO +L2VPN and overlay networks, such as VXLAN and EVPN, can be defined in NetBox and tied to interfaces and VLANs. This allows for easy tracking of overlay assets and their relationships with underlay resources. + +Each L2VPN instance has a type and optional unique identifier. Like VRFs, L2VPNs can also have import and export route targets assigned to them. Terminations can then be created to assign VLANs and/or device and virtual machine interfaces to the overlay. diff --git a/docs/features/services.md b/docs/features/services.md deleted file mode 100644 index 338fc349a..000000000 --- a/docs/features/services.md +++ /dev/null @@ -1,3 +0,0 @@ -# Services - -TODO diff --git a/docs/features/vlan-management.md b/docs/features/vlan-management.md index 3d4fd4d1f..4af05dea3 100644 --- a/docs/features/vlan-management.md +++ b/docs/features/vlan-management.md @@ -1,3 +1,20 @@ # VLAN Management -TODO +Complementing its IPAM capabilities, NetBox also tracks VLAN information to assist with layer two network configurations. VLANs are defined per IEEE 802.1Q and related standards, and can be assigned to groups and functional roles. + +```mermaid +flowchart TD + VLANGroup & Role --> VLAN +``` + +## VLAN Groups + +A VLAN group is a collection of VLANs defined within a particular scope. Each VLAN group can be associated with a particular site, location, rack, or similar object to indicate its domain, and designates a minimum and maximum VLAN ID within the group. (By default, these are the standard minimum and maximum values of 1 and 4094, respectively.) + +Within a group, each VLAN must have a unique ID and name. There is no limit to how many groups can be created per scope. + +## VLANs + +NetBox models VLANs according to their definition under IEEE 802.1Q, with a 12-bit VLAN ID and a name. Each VLAN also has an operational status, and may be assigned a function role, just like prefixes. Each VLAN can be assigned to a VLAN group or site to convey the domain in which the VLAN exists. + +Once defined, VLANs can be associated with device and virtual machine interfaces. Each interface can be assigned an 802.1Q mode (access or tagged), and the relevant VLANs can be applied as tagged or untagged. diff --git a/docs/features/wireless.md b/docs/features/wireless.md index ff3d5d10b..215d1a682 100644 --- a/docs/features/wireless.md +++ b/docs/features/wireless.md @@ -1,3 +1,26 @@ # Wireless -TODO +Just as NetBox provides robust modeling for physical cable plants, it also supports modeling wireless LANs and point-to-point links. + +## Wireless LANs + +```mermaid +flowchart TD + WirelessLANGroup --> WirelessLANGroup & WirelessLAN +``` + +A wireless LAN is a multi-access network shared by multiple wireless clients, identified by a common service set identifier (SSID) and authentication parameters. Wireless LANs can be organized into self-nesting groups, and each wireless LAN may optionally be bound to a particular VLAN. This allows easily mapping wireless networks to their wired counterparts. + +Authentication attributes for wireless LANs include: + +* **Type** - Open, WEP, WPA, etc. +* **Cipher** - Auto, TKIP, or AES +* **Pre-shared key (PSK)** - The secret key configured on all participating clients + +The definition of authentication parameters is optional. + +## Wireless Links + +Whereas a wireless LAN represents a physical multi-access segment with any number of clients, a wireless link is a point-to-point connection between exactly two stations. These links behave much like cables, but more accurately model the nature of wireless communications. + +Like wireless LANs, wireless links also have an SSID and (optional) authentication attributes. diff --git a/mkdocs.yml b/mkdocs.yml index 78ca5031c..784e4498e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,7 +67,6 @@ nav: - Power Tracking: 'features/power-tracking.md' - IPAM: 'features/ipam.md' - VLAN Management: 'features/vlan-management.md' - - Service Mapping: 'features/services.md' - L2VPN & Overlay: 'features/l2vpn-overlay.md' - Circuits: 'features/circuits.md' - Wireless: 'features/wireless.md' From 9733cee3d208d017382c44d966e2ab8f80a1f31f Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 10 Aug 2022 14:07:51 -0400 Subject: [PATCH 213/245] Continued work on feature docs --- docs/development/models.md | 2 +- docs/features/context-data.md | 79 ++++++--------------- docs/features/customization.md | 38 ++++++++++ docs/features/integrations.md | 41 +++++++++++ docs/features/tags.md | 17 ----- docs/{features => integrations}/webhooks.md | 0 docs/models/extras/configcontext.md | 69 ++++++++++++++++++ docs/models/extras/tag.md | 17 +++++ mkdocs.yml | 6 +- 9 files changed, 193 insertions(+), 76 deletions(-) create mode 100644 docs/features/integrations.md rename docs/{features => integrations}/webhooks.md (100%) create mode 100644 docs/models/extras/configcontext.md create mode 100644 docs/models/extras/tag.md diff --git a/docs/development/models.md b/docs/development/models.md index be3608a30..3c7aaaa78 100644 --- a/docs/development/models.md +++ b/docs/development/models.md @@ -9,7 +9,7 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/ ### Features Matrix * [Change logging](../features/change-logging.md) - Changes to these objects are automatically recorded in the change log -* [Webhooks](../features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects +* [Webhooks](../integrations/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects * [Custom fields](../customization/custom-fields.md) - These models support the addition of user-defined fields * [Export templates](../customization/export-templates.md) - Users can create custom export templates for these models * [Tagging](../features/tags.md) - The models can be tagged with user-defined tags diff --git a/docs/features/context-data.md b/docs/features/context-data.md index 08b5f4fd5..d202482da 100644 --- a/docs/features/context-data.md +++ b/docs/features/context-data.md @@ -1,69 +1,34 @@ -# Configuration Contexts +# Context Data -Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments: - -* Region -* Site group -* Site -* Location (devices only) -* Device type (devices only) -* Role -* Platform -* Cluster type (VMs only) -* Cluster group (VMs only) -* Cluster (VMs only) -* Tenant group -* Tenant -* Tag - -## Hierarchical Rendering - -Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object. - -For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data: - -```json -{ - "ntp-servers": [ - "172.16.10.22", - "172.16.10.33" - ], - "syslog-servers": [ - "172.16.9.100", - "172.16.9.101" - ] -} -``` - -But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data: +Configuration context data (or "config contexts" for short) is a powerful feature that enables users to define arbitrary data that applies to device and virtual machines based on certain characteristics. For example, suppose you want to define syslog servers for devices assigned to sites within a particular region. In NetBox, you can create a config context instance containing this data and apply it to the desired region. All devices within this region will now include this data when fetched via an API. ```json { "syslog-servers": [ - "192.168.43.107" + "192.168.43.107", + "192.168.48.112" ] } ``` -When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following: +While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases. -```json -{ - "ntp-servers": [ - "172.16.10.22", - "172.16.10.33" - ], - "syslog-servers": [ - "192.168.43.107" - ] -} -``` +There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. Additionally, each device and VM may have local context data defined: This data is stored directly on the assigned object, and applies to it only. This is a convenient way for "attaching" miscellaneous data to a single device or VM as needed. -Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved. +Config contexts can be computed for objects based on the following criteria: -## Local Context Data - -Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object. - -!!! warning - If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution. +| Type | Devices | Virtual Machines | +|---------------|------------------|------------------| +| Region | :material-check: | :material-check: | +| Site group | :material-check: | :material-check: | +| Site | :material-check: | :material-check: | +| Location | :material-check: | | +| Device type | :material-check: | | +| Role | :material-check: | :material-check: | +| Platform | :material-check: | :material-check: | +| Cluster type | | :material-check: | +| Cluster group | | :material-check: | +| Cluster | | :material-check: | +| Tenant group | :material-check: | :material-check: | +| Tenant | :material-check: | :material-check: | +| Tag | :material-check: | :material-check: | diff --git a/docs/features/customization.md b/docs/features/customization.md index ae775312e..5b42d5e43 100644 --- a/docs/features/customization.md +++ b/docs/features/customization.md @@ -1,3 +1,41 @@ # Customization +While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs. + +## Custom Fields + +While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs. + +NetBox supports many types of custom field, from basic data types like strings and integers, to complex structures like selection lists or raw JSON. It's even possible to add a custom field which references other NetBox objects. Custom field data is stored directly alongside the object to which it is applied in the database, which ensures minimal performance impact. And custom field data can be written and read via the REST API, just like built-in fields. + +To learn more about this feature, check out the [custom field documentation](../customization/custom-fields.md). + +## Custom Links + TODO + +To learn more about this feature, check out the [custom link documentation](../customization/custom-links.md). + +## Custom Validation + +TODO + +To learn more about this feature, check out the [custom validation documentation](../customization/custom-validation.md). + +## Export Templates + +TODO + +To learn more about this feature, check out the [export template documentation](../customization/export-templates.md). + +## Reports + +TODO + +To learn more about this feature, check out the [documentation for reports](../customization/reports.md). + +## Custom Scripts + +TODO + +To learn more about this feature, check out the [documentation for custom scripts](../customization/custom-scripts.md). diff --git a/docs/features/integrations.md b/docs/features/integrations.md new file mode 100644 index 000000000..c2f68c5c8 --- /dev/null +++ b/docs/features/integrations.md @@ -0,0 +1,41 @@ +# Integrations + +NetBox includes a slew of features which enable integration with other tools and resources powering your network. + +## REST API + +NetBox's REST API, powered by the [Django REST Framework](https://www.django-rest-framework.org/), provides a robust yet accessible interface for creating, modifying, and deleting objects. Employing HTTP for transfer and JSON for data encapsulation, the REST API is easily consumed by clients on any platform and extremely well suited for automation tasks. + +```no-highlight +curl -s -X POST \ +-H "Authorization: Token $TOKEN" \ +-H "Content-Type: application/json" \ +http://netbox/api/ipam/prefixes/ \ +--data '{"prefix": "192.0.2.0/24", "site": {"name": "Branch 12"}}' +``` + +The REST API employs token-based authentication, which maps API clients to user accounts and their assigned permissions. The API endpoints are fully documented using OpenAPI, and NetBox even includes a convenient browser-based version of the API for exploration. The open source [pynetbox](https://github.com/netbox-community/pynetbox) and [go-netbox](https://github.com/netbox-community/go-netbox) API client libraries are also available for Python and Go, respectively. + +To learn more about this feature, check out the [REST API documentation](../integrations/rest-api.md). + +## GraphQL API + +NetBox also provides a [GraphQL](https://graphql.org/) API to complement its REST API. GraphQL enables complex queries for arbitrary objects and fields, enabling the client to retrieve only the specific data it needs from NetBox. This is a special-purpose read-only API intended for efficient queries. Like the REST API, the GraphQL API employs token-based authentication. + +To learn more about this feature, check out the [GraphQL API documentation](../integrations/graphql-api.md). + +## Webhooks + +A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are an excellent mechanism for building event-based automation processes. + +To learn more about this feature, check out the [webhooks documentation](../integrations/webhooks.md). + +## NAPALM + +[NAPALM](https://github.com/napalm-automation/napalm) is a Python library which enables direct interaction with network devices of various platforms. When configured, NetBox supports fetching live operational and status data directly from network devices to be compared to what has been defined in NetBox. This allows for easily validating the device's operational state against its desired state. Additionally, NetBox's REST API can act as a sort of proxy for NAPALM commands, allowing external clients to interact with network devices by sending HTTP requests to the appropriate API endpoint. + +To learn more about this feature, check out the [NAPALM documentation](../integrations/napalm.md). + +## Prometheus Metrics + +NetBox includes a special `/metrics` view which exposes metrics for a [Prometheus](https://prometheus.io/) scraper, powered by the open source [django-prometheus](https://github.com/korfuri/django-prometheus) library. To learn more about this feature, check out the [Prometheus metrics documentation](../integrations/prometheus-metrics.md). diff --git a/docs/features/tags.md b/docs/features/tags.md index fe6a1ef36..e69de29bb 100644 --- a/docs/features/tags.md +++ b/docs/features/tags.md @@ -1,17 +0,0 @@ -# Tags - -Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects. - -Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose. - -Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": - -```no-highlight -GET /api/dcim/devices/?tag=monitored -``` - -The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned: - -```no-highlight -GET /api/dcim/devices/?tag=monitored&tag=deprecated -``` diff --git a/docs/features/webhooks.md b/docs/integrations/webhooks.md similarity index 100% rename from docs/features/webhooks.md rename to docs/integrations/webhooks.md diff --git a/docs/models/extras/configcontext.md b/docs/models/extras/configcontext.md new file mode 100644 index 000000000..08b5f4fd5 --- /dev/null +++ b/docs/models/extras/configcontext.md @@ -0,0 +1,69 @@ +# Configuration Contexts + +Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments: + +* Region +* Site group +* Site +* Location (devices only) +* Device type (devices only) +* Role +* Platform +* Cluster type (VMs only) +* Cluster group (VMs only) +* Cluster (VMs only) +* Tenant group +* Tenant +* Tag + +## Hierarchical Rendering + +Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object. + +For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data: + +```json +{ + "ntp-servers": [ + "172.16.10.22", + "172.16.10.33" + ], + "syslog-servers": [ + "172.16.9.100", + "172.16.9.101" + ] +} +``` + +But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data: + +```json +{ + "syslog-servers": [ + "192.168.43.107" + ] +} +``` + +When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following: + +```json +{ + "ntp-servers": [ + "172.16.10.22", + "172.16.10.33" + ], + "syslog-servers": [ + "192.168.43.107" + ] +} +``` + +Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved. + +## Local Context Data + +Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object. + +!!! warning + If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution. diff --git a/docs/models/extras/tag.md b/docs/models/extras/tag.md new file mode 100644 index 000000000..fe6a1ef36 --- /dev/null +++ b/docs/models/extras/tag.md @@ -0,0 +1,17 @@ +# Tags + +Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects. + +Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose. + +Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": + +```no-highlight +GET /api/dcim/devices/?tag=monitored +``` + +The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned: + +```no-highlight +GET /api/dcim/devices/?tag=monitored&tag=deprecated +``` diff --git a/mkdocs.yml b/mkdocs.yml index 784e4498e..95672cede 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,8 +73,8 @@ nav: - Context Data: 'features/context-data.md' - Change Logging: 'features/change-logging.md' - Journaling: 'features/journaling.md' - - Webhooks: 'features/webhooks.md' - Tags: 'features/tags.md' + - Integrations: 'features/integrations.md' - Customization: 'features/customization.md' - Object-Based Permissions: 'features/permissions.md' - Single Sign-On (SSO): 'features/sso.md' @@ -114,6 +114,7 @@ nav: - Integrations: - REST API: 'integrations/rest-api.md' - GraphQL API: 'integrations/graphql-api.md' + - Webhooks: 'integrations/webhooks.md' - NAPALM: 'integrations/napalm.md' - Prometheus Metrics: 'integrations/prometheus-metrics.md' - Plugins: @@ -188,6 +189,9 @@ nav: - Site: 'models/dcim/site.md' - SiteGroup: 'models/dcim/sitegroup.md' - VirtualChassis: 'models/dcim/virtualchassis.md' + - Extras: + - ConfigContext: 'models/extras/configcontext.md' + - Tag: 'models/extras/tag.md' - IPAM: - ASN: 'models/ipam/asn.md' - Aggregate: 'models/ipam/aggregate.md' From 8cd5a24409c993cc3533a1bfa03a95cf2a2f42b6 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 09:58:37 -0400 Subject: [PATCH 214/245] #9414: Clean up clone_fields on all models --- netbox/circuits/models/circuits.py | 4 ++-- netbox/circuits/models/providers.py | 4 ++-- netbox/dcim/models/device_components.py | 23 +++++++++++++---------- netbox/dcim/models/devices.py | 11 ++++++----- netbox/dcim/models/power.py | 6 +++--- netbox/dcim/models/racks.py | 4 ++-- netbox/dcim/models/sites.py | 10 +++++----- netbox/ipam/models/fhrp.py | 2 +- netbox/ipam/models/ip.py | 18 +++++++++--------- netbox/ipam/models/vrfs.py | 4 ++-- netbox/tenancy/models/contacts.py | 8 ++++---- netbox/tenancy/models/tenants.py | 4 ++-- netbox/virtualization/models.py | 10 +++++----- netbox/wireless/models.py | 2 ++ 14 files changed, 58 insertions(+), 52 deletions(-) diff --git a/netbox/circuits/models/circuits.py b/netbox/circuits/models/circuits.py index d82878cde..c78ea81c7 100644 --- a/netbox/circuits/models/circuits.py +++ b/netbox/circuits/models/circuits.py @@ -125,9 +125,9 @@ class Circuit(NetBoxModel): null=True ) - clone_fields = [ + clone_fields = ( 'provider', 'type', 'status', 'tenant', 'install_date', 'termination_date', 'commit_rate', 'description', - ] + ) class Meta: ordering = ['provider', 'cid'] diff --git a/netbox/circuits/models/providers.py b/netbox/circuits/models/providers.py index 4211a54a6..e136e13ea 100644 --- a/netbox/circuits/models/providers.py +++ b/netbox/circuits/models/providers.py @@ -61,9 +61,9 @@ class Provider(NetBoxModel): to='tenancy.ContactAssignment' ) - clone_fields = [ + clone_fields = ( 'asn', 'account', 'portal_url', 'noc_contact', 'admin_contact', - ] + ) class Meta: ordering = ['name'] diff --git a/netbox/dcim/models/device_components.py b/netbox/dcim/models/device_components.py index 5e2fc348e..838336e21 100644 --- a/netbox/dcim/models/device_components.py +++ b/netbox/dcim/models/device_components.py @@ -263,7 +263,7 @@ class ConsolePort(ModularComponentModel, CabledObjectModel, PathEndpoint): help_text='Port speed in bits per second' ) - clone_fields = ['device', 'type', 'speed'] + clone_fields = ('device', 'module', 'type', 'speed') class Meta: ordering = ('device', '_name') @@ -290,7 +290,7 @@ class ConsoleServerPort(ModularComponentModel, CabledObjectModel, PathEndpoint): help_text='Port speed in bits per second' ) - clone_fields = ['device', 'type', 'speed'] + clone_fields = ('device', 'module', 'type', 'speed') class Meta: ordering = ('device', '_name') @@ -327,7 +327,7 @@ class PowerPort(ModularComponentModel, CabledObjectModel, PathEndpoint): help_text="Allocated power draw (watts)" ) - clone_fields = ['device', 'maximum_draw', 'allocated_draw'] + clone_fields = ('device', 'module', 'maximum_draw', 'allocated_draw') class Meta: ordering = ('device', '_name') @@ -441,7 +441,7 @@ class PowerOutlet(ModularComponentModel, CabledObjectModel, PathEndpoint): help_text="Phase (for three-phase feeds)" ) - clone_fields = ['device', 'type', 'power_port', 'feed_leg'] + clone_fields = ('device', 'module', 'type', 'power_port', 'feed_leg') class Meta: ordering = ('device', '_name') @@ -672,7 +672,10 @@ class Interface(ModularComponentModel, BaseInterface, CabledObjectModel, PathEnd related_query_name='interface', ) - clone_fields = ['device', 'parent', 'bridge', 'lag', 'type', 'mgmt_only', 'poe_mode', 'poe_type'] + clone_fields = ( + 'device', 'module', 'parent', 'bridge', 'lag', 'type', 'mgmt_only', 'mtu', 'mode', 'speed', 'duplex', 'rf_role', + 'rf_channel', 'rf_channel_frequency', 'rf_channel_width', 'tx_power', 'poe_mode', 'poe_type', 'vrf', + ) class Meta: ordering = ('device', CollateAsChar('_name')) @@ -890,7 +893,7 @@ class FrontPort(ModularComponentModel, CabledObjectModel): ] ) - clone_fields = ['device', 'type'] + clone_fields = ('device', 'type', 'color') class Meta: ordering = ('device', '_name') @@ -937,7 +940,7 @@ class RearPort(ModularComponentModel, CabledObjectModel): MaxValueValidator(REARPORT_POSITIONS_MAX) ] ) - clone_fields = ['device', 'type', 'positions'] + clone_fields = ('device', 'type', 'color', 'positions') class Meta: ordering = ('device', '_name') @@ -972,7 +975,7 @@ class ModuleBay(ComponentModel): help_text='Identifier to reference when renaming installed components' ) - clone_fields = ['device'] + clone_fields = ('device',) class Meta: ordering = ('device', '_name') @@ -994,7 +997,7 @@ class DeviceBay(ComponentModel): null=True ) - clone_fields = ['device'] + clone_fields = ('device',) class Meta: ordering = ('device', '_name') @@ -1131,7 +1134,7 @@ class InventoryItem(MPTTModel, ComponentModel): objects = TreeManager() - clone_fields = ['device', 'parent', 'role', 'manufacturer', 'part_id'] + clone_fields = ('device', 'parent', 'role', 'manufacturer', 'part_id',) class Meta: ordering = ('device__id', 'parent__id', '_name') diff --git a/netbox/dcim/models/devices.py b/netbox/dcim/models/devices.py index f21176d8d..136fcf6cf 100644 --- a/netbox/dcim/models/devices.py +++ b/netbox/dcim/models/devices.py @@ -135,9 +135,9 @@ class DeviceType(NetBoxModel): blank=True ) - clone_fields = [ + clone_fields = ( 'manufacturer', 'u_height', 'is_full_depth', 'subdevice_role', 'airflow', - ] + ) class Meta: ordering = ['manufacturer', 'model'] @@ -630,9 +630,10 @@ class Device(NetBoxModel, ConfigContextModel): objects = ConfigContextModelQuerySet.as_manager() - clone_fields = [ - 'device_type', 'device_role', 'tenant', 'platform', 'site', 'location', 'rack', 'status', 'airflow', 'cluster', - ] + clone_fields = ( + 'device_type', 'device_role', 'tenant', 'platform', 'site', 'location', 'rack', 'face', 'status', 'airflow', + 'cluster', 'virtual_chassis', + ) class Meta: ordering = ('_name', 'pk') # Name may be null diff --git a/netbox/dcim/models/power.py b/netbox/dcim/models/power.py index 94767c6c4..c275691c0 100644 --- a/netbox/dcim/models/power.py +++ b/netbox/dcim/models/power.py @@ -126,10 +126,10 @@ class PowerFeed(NetBoxModel, PathEndpoint, CabledObjectModel): blank=True ) - clone_fields = [ + clone_fields = ( 'power_panel', 'rack', 'status', 'type', 'mark_connected', 'supply', 'phase', 'voltage', 'amperage', - 'max_utilization', 'available_power', - ] + 'max_utilization', + ) class Meta: ordering = ['power_panel', 'name'] diff --git a/netbox/dcim/models/racks.py b/netbox/dcim/models/racks.py index 4dcfcde28..50c91b52e 100644 --- a/netbox/dcim/models/racks.py +++ b/netbox/dcim/models/racks.py @@ -183,10 +183,10 @@ class Rack(NetBoxModel): to='extras.ImageAttachment' ) - clone_fields = [ + clone_fields = ( 'site', 'location', 'tenant', 'status', 'role', 'type', 'width', 'u_height', 'desc_units', 'outer_width', 'outer_depth', 'outer_unit', - ] + ) class Meta: ordering = ('site', 'location', '_name', 'pk') # (site, location, name) may be non-unique diff --git a/netbox/dcim/models/sites.py b/netbox/dcim/models/sites.py index 9b7ffdcf4..67bcc6e4c 100644 --- a/netbox/dcim/models/sites.py +++ b/netbox/dcim/models/sites.py @@ -295,10 +295,10 @@ class Site(NetBoxModel): to='extras.ImageAttachment' ) - clone_fields = [ - 'status', 'region', 'group', 'tenant', 'facility', 'time_zone', 'description', 'physical_address', - 'shipping_address', 'latitude', 'longitude', - ] + clone_fields = ( + 'status', 'region', 'group', 'tenant', 'facility', 'time_zone', 'physical_address', 'shipping_address', + 'latitude', 'longitude', 'description', + ) class Meta: ordering = ('_name',) @@ -372,7 +372,7 @@ class Location(NestedGroupModel): to='extras.ImageAttachment' ) - clone_fields = ['site', 'parent', 'status', 'tenant', 'description'] + clone_fields = ('site', 'parent', 'status', 'tenant', 'description') class Meta: ordering = ['site', 'name'] diff --git a/netbox/ipam/models/fhrp.py b/netbox/ipam/models/fhrp.py index 2a8d1bdcd..286251444 100644 --- a/netbox/ipam/models/fhrp.py +++ b/netbox/ipam/models/fhrp.py @@ -48,7 +48,7 @@ class FHRPGroup(NetBoxModel): related_query_name='fhrpgroup' ) - clone_fields = ('protocol', 'auth_type', 'auth_key') + clone_fields = ('protocol', 'auth_type', 'auth_key', 'description') class Meta: ordering = ['protocol', 'group_id', 'pk'] diff --git a/netbox/ipam/models/ip.py b/netbox/ipam/models/ip.py index 9ad763920..26cee8100 100644 --- a/netbox/ipam/models/ip.py +++ b/netbox/ipam/models/ip.py @@ -175,9 +175,9 @@ class Aggregate(GetAvailablePrefixesMixin, NetBoxModel): blank=True ) - clone_fields = [ + clone_fields = ( 'rir', 'tenant', 'date_added', 'description', - ] + ) class Meta: ordering = ('prefix', 'pk') # prefix may be non-unique @@ -360,9 +360,9 @@ class Prefix(GetAvailablePrefixesMixin, NetBoxModel): objects = PrefixQuerySet.as_manager() - clone_fields = [ + clone_fields = ( 'site', 'vrf', 'tenant', 'vlan', 'status', 'role', 'is_pool', 'mark_utilized', 'description', - ] + ) class Meta: ordering = (F('vrf').asc(nulls_first=True), 'prefix', 'pk') # (vrf, prefix) may be non-unique @@ -608,9 +608,9 @@ class IPRange(NetBoxModel): blank=True ) - clone_fields = [ + clone_fields = ( 'vrf', 'tenant', 'status', 'role', 'description', - ] + ) class Meta: ordering = (F('vrf').asc(nulls_first=True), 'start_address', 'pk') # (vrf, start_address) may be non-unique @@ -836,9 +836,9 @@ class IPAddress(NetBoxModel): objects = IPAddressManager() - clone_fields = [ - 'vrf', 'tenant', 'status', 'role', 'description', - ] + clone_fields = ( + 'vrf', 'tenant', 'status', 'role', 'dns_name', 'description', + ) class Meta: ordering = ('address', 'pk') # address may be non-unique diff --git a/netbox/ipam/models/vrfs.py b/netbox/ipam/models/vrfs.py index fc34b5488..a926bec3e 100644 --- a/netbox/ipam/models/vrfs.py +++ b/netbox/ipam/models/vrfs.py @@ -55,9 +55,9 @@ class VRF(NetBoxModel): blank=True ) - clone_fields = [ + clone_fields = ( 'tenant', 'enforce_unique', 'description', - ] + ) class Meta: ordering = ('name', 'rd', 'pk') # (name, rd) may be non-unique diff --git a/netbox/tenancy/models/contacts.py b/netbox/tenancy/models/contacts.py index 75ec9f69c..41881f853 100644 --- a/netbox/tenancy/models/contacts.py +++ b/netbox/tenancy/models/contacts.py @@ -112,9 +112,9 @@ class Contact(NetBoxModel): blank=True ) - clone_fields = [ - 'group', - ] + clone_fields = ( + 'group', 'name', 'title', 'phone', 'email', 'address', 'link', + ) class Meta: ordering = ['name'] @@ -155,7 +155,7 @@ class ContactAssignment(WebhooksMixin, ChangeLoggedModel): blank=True ) - clone_fields = ('content_type', 'object_id') + clone_fields = ('content_type', 'object_id', 'role', 'priority') class Meta: ordering = ('priority', 'contact') diff --git a/netbox/tenancy/models/tenants.py b/netbox/tenancy/models/tenants.py index 88d8d52f1..b0ccd1cb2 100644 --- a/netbox/tenancy/models/tenants.py +++ b/netbox/tenancy/models/tenants.py @@ -76,9 +76,9 @@ class Tenant(NetBoxModel): to='tenancy.ContactAssignment' ) - clone_fields = [ + clone_fields = ( 'group', 'description', - ] + ) class Meta: ordering = ['name'] diff --git a/netbox/virtualization/models.py b/netbox/virtualization/models.py index f07b176e7..21bc799be 100644 --- a/netbox/virtualization/models.py +++ b/netbox/virtualization/models.py @@ -153,9 +153,9 @@ class Cluster(NetBoxModel): to='tenancy.ContactAssignment' ) - clone_fields = [ - 'type', 'group', 'tenant', 'site', - ] + clone_fields = ( + 'type', 'group', 'status', 'tenant', 'site', + ) class Meta: ordering = ['name'] @@ -299,9 +299,9 @@ class VirtualMachine(NetBoxModel, ConfigContextModel): objects = ConfigContextModelQuerySet.as_manager() - clone_fields = [ + clone_fields = ( 'site', 'cluster', 'device', 'tenant', 'platform', 'status', 'role', 'vcpus', 'memory', 'disk', - ] + ) class Meta: ordering = ('_name', 'pk') # Name may be non-unique diff --git a/netbox/wireless/models.py b/netbox/wireless/models.py index dd3945d50..0540e9c45 100644 --- a/netbox/wireless/models.py +++ b/netbox/wireless/models.py @@ -113,6 +113,8 @@ class WirelessLAN(WirelessAuthenticationBase, NetBoxModel): blank=True ) + clone_fields = ('ssid', 'group', 'tenant', 'description') + class Meta: ordering = ('ssid', 'pk') verbose_name = 'Wireless LAN' From 5f15f550c9fdf3603b5fd17816c929434f42b78e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 11:37:07 -0400 Subject: [PATCH 215/245] Restore model documentation for all models under extras --- docs/customization/custom-fields.md | 109 ------------------- docs/customization/custom-links.md | 66 ------------ docs/customization/export-templates.md | 81 -------------- docs/integrations/webhooks.md | 139 ------------------------- docs/models/extras/customfield.md | 109 +++++++++++++++++++ docs/models/extras/customlink.md | 66 ++++++++++++ docs/models/extras/exporttemplate.md | 81 ++++++++++++++ docs/models/extras/imageattachment.md | 3 + docs/models/extras/webhook.md | 139 +++++++++++++++++++++++++ mkdocs.yml | 5 + 10 files changed, 403 insertions(+), 395 deletions(-) create mode 100644 docs/models/extras/customfield.md create mode 100644 docs/models/extras/customlink.md create mode 100644 docs/models/extras/exporttemplate.md create mode 100644 docs/models/extras/imageattachment.md create mode 100644 docs/models/extras/webhook.md diff --git a/docs/customization/custom-fields.md b/docs/customization/custom-fields.md index bfe412edc..e69de29bb 100644 --- a/docs/customization/custom-fields.md +++ b/docs/customization/custom-fields.md @@ -1,109 +0,0 @@ -# Custom Fields - -Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. - -However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. - -Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. - -## Creating Custom Fields - -Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: - -* Text: Free-form text (intended for single-line use) -* Long text: Free-form of any length; supports Markdown rendering -* Integer: A whole number (positive or negative) -* Boolean: True or false -* Date: A date in ISO 8601 format (YYYY-MM-DD) -* URL: This will be presented as a link in the web UI -* JSON: Arbitrary data stored in JSON format -* Selection: A selection of one of several pre-defined custom choices -* Multiple selection: A selection field which supports the assignment of multiple values -* Object: A single NetBox object of the type defined by `object_type` -* Multiple object: One or more NetBox objects of the type defined by `object_type` - -Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. - -Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. - -A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. - -### Filtering - -The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. - -### Grouping - -!!! note - This feature was introduced in NetBox v3.3. - -Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) - -This parameter has no effect on the API representation of custom field data. - -### Visibility - -!!! note - This feature was introduced in NetBox v3.3. - -When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. - -* **Read/write** (default): The custom field is included when viewing and editing objects. -* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) -* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. - -Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. - -### Validation - -NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: - -* Text: Regular expression (optional) -* Integer: Minimum and/or maximum value (optional) -* Selection: Must exactly match one of the prescribed choices - -### Custom Selection Fields - -Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. - -If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. - -### Custom Object Fields - -An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. - - -## Custom Fields in Templates - -Several features within NetBox, such as export templates and webhooks, utilize Jinja2 templating. For convenience, objects which support custom field assignment expose custom field data through the `cf` property. This is a bit cleaner than accessing custom field data through the actual field (`custom_field_data`). - -For example, a custom field named `foo123` on the Site model is accessible on an instance as `{{ site.cf.foo123 }}`. - -## Custom Fields and the REST API - -When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined: - -```json -{ - "id": 123, - "url": "http://localhost:8000/api/dcim/sites/123/", - "name": "Raleigh 42", - ... - "custom_fields": { - "deployed": "2018-06-19", - "site_code": "US-NC-RAL42" - }, - ... -``` - -To set or change these values, simply include nested JSON data. For example: - -```json -{ - "name": "New Site", - "slug": "new-site", - "custom_fields": { - "deployed": "2019-03-24" - } -} -``` diff --git a/docs/customization/custom-links.md b/docs/customization/custom-links.md index 16ba9d2af..e69de29bb 100644 --- a/docs/customization/custom-links.md +++ b/docs/customization/custom-links.md @@ -1,66 +0,0 @@ -# Custom Links - -Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS). - -Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the NetBox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`. - -For example, you might define a link like this: - -* Text: `View NMS` -* URL: `https://nms.example.com/nodes/?name={{ obj.name }}` - -When viewing a device named Router4, this link would render as: - -```no-highlight -View NMS -``` - -Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually. - -!!! warning - Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users. - -## Context Data - -The following context data is available within the template when rendering a custom link's text or URL. - -| Variable | Description | -|-----------|-------------------------------------------------------------------------------------------------------------------| -| `object` | The NetBox object being displayed | -| `obj` | Same as `object`; maintained for backward compatability until NetBox v3.5 | -| `debug` | A boolean indicating whether debugging is enabled | -| `request` | The current WSGI request | -| `user` | The current user (if authenticated) | -| `perms` | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user | - -While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type. - -Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list. - -## Conditional Rendering - -Only links which render with non-empty text are included on the page. You can employ conditional Jinja2 logic to control the conditions under which a link gets rendered. - -For example, if you only want to display a link for active devices, you could set the link text to - -```jinja2 -{% if obj.status == 'active' %}View NMS{% endif %} -``` - -The link will not appear when viewing a device with any status other than "active." - -As another example, if you wanted to show only devices belonging to a certain manufacturer, you could do something like this: - -```jinja2 -{% if obj.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %} -``` - -The link will only appear when viewing a device with a manufacturer name of "Cisco." - -## Link Groups - -Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group. - -## Table Columns - -Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL. diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index 640a97531..e69de29bb 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -1,81 +0,0 @@ -# Export Templates - -NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. - -Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. - -Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). - -!!! note - The name `table` is reserved for internal use. - -!!! warning - Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. - -The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: - -```jinja2 -{% for rack in queryset %} -Rack: {{ rack.name }} -Site: {{ rack.site.name }} -Height: {{ rack.u_height }}U -{% endfor %} -``` - -To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. - -If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: -``` -{% for server in queryset %} -{% set data = server.get_config_context() %} -{{ data.syslog }} -{% endfor %} -``` - -The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) - -A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. - - -## REST API Integration - -When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: - -``` -GET /api/dcim/sites/?export=MyTemplateName -``` - -Note that the body of the response will contain only the rendered export template content, as opposed to a JSON object or list. - -## Example - -Here's an example device export template that will generate a simple Nagios configuration from a list of devices. - -``` -{% for device in queryset %}{% if device.status and device.primary_ip %}define host{ - use generic-switch - host_name {{ device.name }} - address {{ device.primary_ip.address.ip }} -} -{% endif %}{% endfor %} -``` - -The generated output will look something like this: - -``` -define host{ - use generic-switch - host_name switch1 - address 192.0.2.1 -} -define host{ - use generic-switch - host_name switch2 - address 192.0.2.2 -} -define host{ - use generic-switch - host_name switch3 - address 192.0.2.3 -} -``` diff --git a/docs/integrations/webhooks.md b/docs/integrations/webhooks.md index 4705243d1..e69de29bb 100644 --- a/docs/integrations/webhooks.md +++ b/docs/integrations/webhooks.md @@ -1,139 +0,0 @@ -# Webhooks - -A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks. - -!!! warning - Webhooks support the inclusion of user-submitted code to generate URL, custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users. - -## Configuration - -* **Name** - A unique name for the webhook. The name is not included with outbound messages. -* **Object type(s)** - The type or types of NetBox object that will trigger the webhook. -* **Enabled** - If unchecked, the webhook will be inactive. -* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected. -* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. -* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field. -* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`) -* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below). -* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.) -* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key. -* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object. -* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!) -* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional). - -## Jinja2 Template Support - -[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands. - -For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration: - -* Object type: IPAM > IP address -* HTTP method: `POST` -* URL: Slack incoming webhook URL -* HTTP content type: `application/json` -* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}` - -### Available Context - -The following data is available as context for Jinja2 templates: - -* `event` - The type of event which triggered the webhook: created, updated, or deleted. -* `model` - The NetBox model which triggered the change. -* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). -* `username` - The name of the user account associated with the change. -* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request. -* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API. -* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed. - -### Default Request Body - -If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows: - -```json -{ - "event": "created", - "timestamp": "2021-03-09 17:55:33.968016+00:00", - "model": "site", - "username": "jstretch", - "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a", - "data": { - "id": 19, - "name": "Site 1", - "slug": "site-1", - "status": - "value": "active", - "label": "Active", - "id": 1 - }, - "region": null, - ... - }, - "snapshots": { - "prechange": null, - "postchange": { - "created": "2021-03-09", - "last_updated": "2021-03-09T17:55:33.851Z", - "name": "Site 1", - "slug": "site-1", - "status": "active", - ... - } - } -} -``` - -## Conditional Webhooks - -A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": - -```json -{ - "and": [ - { - "attr": "status.value", - "value": "active" - } - ] -} -``` - -For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md). - -## Webhook Processing - -When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. - -A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. - -## Troubleshooting - -To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: - -```no-highlight -$ python netbox/manage.py webhook_receiver -Listening on port http://localhost:9000. Stop with CONTROL-C. -``` - -You can test the receiver itself by sending any HTTP request to it. For example: - -```no-highlight -$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' -``` - -The server will print output similar to the following: - -```no-highlight -[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - -Host: localhost:9000 -User-Agent: curl/7.58.0 -Accept: */* -Content-Length: 14 -Content-Type: application/x-www-form-urlencoded - -{"foo": "bar"} ------------- -``` - -Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. - -Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md new file mode 100644 index 000000000..bfe412edc --- /dev/null +++ b/docs/models/extras/customfield.md @@ -0,0 +1,109 @@ +# Custom Fields + +Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. + +However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. + +Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. + +## Creating Custom Fields + +Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: + +* Text: Free-form text (intended for single-line use) +* Long text: Free-form of any length; supports Markdown rendering +* Integer: A whole number (positive or negative) +* Boolean: True or false +* Date: A date in ISO 8601 format (YYYY-MM-DD) +* URL: This will be presented as a link in the web UI +* JSON: Arbitrary data stored in JSON format +* Selection: A selection of one of several pre-defined custom choices +* Multiple selection: A selection field which supports the assignment of multiple values +* Object: A single NetBox object of the type defined by `object_type` +* Multiple object: One or more NetBox objects of the type defined by `object_type` + +Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. + +Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. + +A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. + +### Filtering + +The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. + +### Grouping + +!!! note + This feature was introduced in NetBox v3.3. + +Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) + +This parameter has no effect on the API representation of custom field data. + +### Visibility + +!!! note + This feature was introduced in NetBox v3.3. + +When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. + +* **Read/write** (default): The custom field is included when viewing and editing objects. +* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. + +Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. + +### Validation + +NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: + +* Text: Regular expression (optional) +* Integer: Minimum and/or maximum value (optional) +* Selection: Must exactly match one of the prescribed choices + +### Custom Selection Fields + +Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. + +If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. + +### Custom Object Fields + +An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. + + +## Custom Fields in Templates + +Several features within NetBox, such as export templates and webhooks, utilize Jinja2 templating. For convenience, objects which support custom field assignment expose custom field data through the `cf` property. This is a bit cleaner than accessing custom field data through the actual field (`custom_field_data`). + +For example, a custom field named `foo123` on the Site model is accessible on an instance as `{{ site.cf.foo123 }}`. + +## Custom Fields and the REST API + +When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined: + +```json +{ + "id": 123, + "url": "http://localhost:8000/api/dcim/sites/123/", + "name": "Raleigh 42", + ... + "custom_fields": { + "deployed": "2018-06-19", + "site_code": "US-NC-RAL42" + }, + ... +``` + +To set or change these values, simply include nested JSON data. For example: + +```json +{ + "name": "New Site", + "slug": "new-site", + "custom_fields": { + "deployed": "2019-03-24" + } +} +``` diff --git a/docs/models/extras/customlink.md b/docs/models/extras/customlink.md new file mode 100644 index 000000000..16ba9d2af --- /dev/null +++ b/docs/models/extras/customlink.md @@ -0,0 +1,66 @@ +# Custom Links + +Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS). + +Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the NetBox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`. + +For example, you might define a link like this: + +* Text: `View NMS` +* URL: `https://nms.example.com/nodes/?name={{ obj.name }}` + +When viewing a device named Router4, this link would render as: + +```no-highlight +View NMS +``` + +Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually. + +!!! warning + Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users. + +## Context Data + +The following context data is available within the template when rendering a custom link's text or URL. + +| Variable | Description | +|-----------|-------------------------------------------------------------------------------------------------------------------| +| `object` | The NetBox object being displayed | +| `obj` | Same as `object`; maintained for backward compatability until NetBox v3.5 | +| `debug` | A boolean indicating whether debugging is enabled | +| `request` | The current WSGI request | +| `user` | The current user (if authenticated) | +| `perms` | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user | + +While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type. + +Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list. + +## Conditional Rendering + +Only links which render with non-empty text are included on the page. You can employ conditional Jinja2 logic to control the conditions under which a link gets rendered. + +For example, if you only want to display a link for active devices, you could set the link text to + +```jinja2 +{% if obj.status == 'active' %}View NMS{% endif %} +``` + +The link will not appear when viewing a device with any status other than "active." + +As another example, if you wanted to show only devices belonging to a certain manufacturer, you could do something like this: + +```jinja2 +{% if obj.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %} +``` + +The link will only appear when viewing a device with a manufacturer name of "Cisco." + +## Link Groups + +Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group. + +## Table Columns + +Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL. diff --git a/docs/models/extras/exporttemplate.md b/docs/models/extras/exporttemplate.md new file mode 100644 index 000000000..b4b69108a --- /dev/null +++ b/docs/models/extras/exporttemplate.md @@ -0,0 +1,81 @@ +# Export Templates + +NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. + +Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. + +Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). + +!!! note + The name `table` is reserved for internal use. + +!!! warning + Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. + +The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: + +```jinja2 +{% for rack in queryset %} +Rack: {{ rack.name }} +Site: {{ rack.site.name }} +Height: {{ rack.u_height }}U +{% endfor %} +``` + +To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. + +If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: +``` +{% for server in queryset %} +{% set data = server.get_config_context() %} +{{ data.syslog }} +{% endfor %} +``` + +The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) + +A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. + + +## REST API Integration + +When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: + +``` +GET /api/dcim/sites/?export=MyTemplateName +``` + +Note that the body of the response will contain only the rendered export template content, as opposed to a JSON object or list. + +## Example + +Here's an example device export template that will generate a simple Nagios configuration from a list of devices. + +``` +{% for device in queryset %}{% if device.status and device.primary_ip %}define host{ + use generic-switch + host_name {{ device.name }} + address {{ device.primary_ip.address.ip }} +} +{% endif %}{% endfor %} +``` + +The generated output will look something like this: + +``` +define host{ + use generic-switch + host_name switch1 + address 192.0.2.1 +} +define host{ + use generic-switch + host_name switch2 + address 192.0.2.2 +} +define host{ + use generic-switch + host_name switch3 + address 192.0.2.3 +} +``` diff --git a/docs/models/extras/imageattachment.md b/docs/models/extras/imageattachment.md new file mode 100644 index 000000000..da15462ab --- /dev/null +++ b/docs/models/extras/imageattachment.md @@ -0,0 +1,3 @@ +# Image Attachments + +Certain objects in NetBox support the attachment of uploaded images. These will be saved to the NetBox server and made available whenever the object is viewed. diff --git a/docs/models/extras/webhook.md b/docs/models/extras/webhook.md new file mode 100644 index 000000000..427ae3dd1 --- /dev/null +++ b/docs/models/extras/webhook.md @@ -0,0 +1,139 @@ +# Webhooks + +A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks. + +!!! warning + Webhooks support the inclusion of user-submitted code to generate URL, custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users. + +## Configuration + +* **Name** - A unique name for the webhook. The name is not included with outbound messages. +* **Object type(s)** - The type or types of NetBox object that will trigger the webhook. +* **Enabled** - If unchecked, the webhook will be inactive. +* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected. +* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. +* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field. +* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`) +* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below). +* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.) +* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key. +* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object. +* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!) +* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional). + +## Jinja2 Template Support + +[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands. + +For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration: + +* Object type: IPAM > IP address +* HTTP method: `POST` +* URL: Slack incoming webhook URL +* HTTP content type: `application/json` +* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}` + +### Available Context + +The following data is available as context for Jinja2 templates: + +* `event` - The type of event which triggered the webhook: created, updated, or deleted. +* `model` - The NetBox model which triggered the change. +* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). +* `username` - The name of the user account associated with the change. +* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request. +* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API. +* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed. + +### Default Request Body + +If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows: + +```json +{ + "event": "created", + "timestamp": "2021-03-09 17:55:33.968016+00:00", + "model": "site", + "username": "jstretch", + "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a", + "data": { + "id": 19, + "name": "Site 1", + "slug": "site-1", + "status": + "value": "active", + "label": "Active", + "id": 1 + }, + "region": null, + ... + }, + "snapshots": { + "prechange": null, + "postchange": { + "created": "2021-03-09", + "last_updated": "2021-03-09T17:55:33.851Z", + "name": "Site 1", + "slug": "site-1", + "status": "active", + ... + } + } +} +``` + +## Conditional Webhooks + +A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": + +```json +{ + "and": [ + { + "attr": "status.value", + "value": "active" + } + ] +} +``` + +For more detail, see the reference documentation for NetBox's [conditional logic](../../reference/conditions.md). + +## Webhook Processing + +When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. + +A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. + +## Troubleshooting + +To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: + +```no-highlight +$ python netbox/manage.py webhook_receiver +Listening on port http://localhost:9000. Stop with CONTROL-C. +``` + +You can test the receiver itself by sending any HTTP request to it. For example: + +```no-highlight +$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' +``` + +The server will print output similar to the following: + +```no-highlight +[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - +Host: localhost:9000 +User-Agent: curl/7.58.0 +Accept: */* +Content-Length: 14 +Content-Type: application/x-www-form-urlencoded + +{"foo": "bar"} +------------ +``` + +Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. + +Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/mkdocs.yml b/mkdocs.yml index 95672cede..a5eb36d81 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -191,7 +191,12 @@ nav: - VirtualChassis: 'models/dcim/virtualchassis.md' - Extras: - ConfigContext: 'models/extras/configcontext.md' + - CustomField: 'models/extras/customfield.md' + - CustomLink: 'models/extras/customlink.md' + - ExportTemplate: 'models/extras/exporttemplate.md' + - ImageAttachment: 'models/extras/imageattachment.md' - Tag: 'models/extras/tag.md' + - Webhook: 'models/extras/webhook.md' - IPAM: - ASN: 'models/ipam/asn.md' - Aggregate: 'models/ipam/aggregate.md' From a7b78565a199c6c5d1459decdd0d0019a743e974 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 11:55:45 -0400 Subject: [PATCH 216/245] Split webhooks documentation --- docs/integrations/webhooks.md | 127 ++++++++++++++++++++++++++++++++++ docs/models/extras/webhook.md | 122 +------------------------------- 2 files changed, 128 insertions(+), 121 deletions(-) diff --git a/docs/integrations/webhooks.md b/docs/integrations/webhooks.md index e69de29bb..3ef28fb11 100644 --- a/docs/integrations/webhooks.md +++ b/docs/integrations/webhooks.md @@ -0,0 +1,127 @@ +# Webhooks + +NetBox can be configured to transmit outgoing webhooks to remote systems in response to internal object changes. The receiver can act on the data in these webhook messages to perform related tasks. + +For example, suppose you want to automatically configure a monitoring system to start monitoring a device when its operational status is changed to active, and remove it from monitoring for any other status. You can create a webhook in NetBox for the device model and craft its content and destination URL to effect the desired change on the receiving system. Webhooks will be sent automatically by NetBox whenever the configured constraints are met. + +Each webhook must be associated with at least one NetBox object type and at least one event (create, update, or delete). Users can specify the receiver URL, HTTP request type (`GET`, `POST`, etc.), content type, and headers. A request body can also be specified; if left blank, this will default to a serialized representation of the affected object. + +!!! warning "Security Notice" + Webhooks support the inclusion of user-submitted code to generate the URL, custom headers, and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users. + +## Jinja2 Template Support + +[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands. + +For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration: + +* Object type: IPAM > IP address +* HTTP method: `POST` +* URL: Slack incoming webhook URL +* HTTP content type: `application/json` +* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}` + +### Available Context + +The following data is available as context for Jinja2 templates: + +* `event` - The type of event which triggered the webhook: created, updated, or deleted. +* `model` - The NetBox model which triggered the change. +* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). +* `username` - The name of the user account associated with the change. +* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request. +* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API. +* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed. + +### Default Request Body + +If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows: + +```json +{ + "event": "created", + "timestamp": "2021-03-09 17:55:33.968016+00:00", + "model": "site", + "username": "jstretch", + "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a", + "data": { + "id": 19, + "name": "Site 1", + "slug": "site-1", + "status": + "value": "active", + "label": "Active", + "id": 1 + }, + "region": null, + ... + }, + "snapshots": { + "prechange": null, + "postchange": { + "created": "2021-03-09", + "last_updated": "2021-03-09T17:55:33.851Z", + "name": "Site 1", + "slug": "site-1", + "status": "active", + ... + } + } +} +``` + +## Conditional Webhooks + +A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": + +```json +{ + "and": [ + { + "attr": "status.value", + "value": "active" + } + ] +} +``` + +For more detail, see the reference documentation for NetBox's [conditional logic](../../reference/conditions.md). + +## Webhook Processing + +When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. + +A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. + +## Troubleshooting + +To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: + +```no-highlight +$ python netbox/manage.py webhook_receiver +Listening on port http://localhost:9000. Stop with CONTROL-C. +``` + +You can test the receiver itself by sending any HTTP request to it. For example: + +```no-highlight +$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' +``` + +The server will print output similar to the following: + +```no-highlight +[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - +Host: localhost:9000 +User-Agent: curl/7.58.0 +Accept: */* +Content-Length: 14 +Content-Type: application/x-www-form-urlencoded + +{"foo": "bar"} +------------ +``` + +Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. + +Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). diff --git a/docs/models/extras/webhook.md b/docs/models/extras/webhook.md index 427ae3dd1..2d598f8ae 100644 --- a/docs/models/extras/webhook.md +++ b/docs/models/extras/webhook.md @@ -2,10 +2,7 @@ A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks. -!!! warning - Webhooks support the inclusion of user-submitted code to generate URL, custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users. - -## Configuration +## Model Fields * **Name** - A unique name for the webhook. The name is not included with outbound messages. * **Object type(s)** - The type or types of NetBox object that will trigger the webhook. @@ -20,120 +17,3 @@ A webhook is a mechanism for conveying to some external system a change that too * **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object. * **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!) * **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional). - -## Jinja2 Template Support - -[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands. - -For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration: - -* Object type: IPAM > IP address -* HTTP method: `POST` -* URL: Slack incoming webhook URL -* HTTP content type: `application/json` -* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}` - -### Available Context - -The following data is available as context for Jinja2 templates: - -* `event` - The type of event which triggered the webhook: created, updated, or deleted. -* `model` - The NetBox model which triggered the change. -* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). -* `username` - The name of the user account associated with the change. -* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request. -* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API. -* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed. - -### Default Request Body - -If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows: - -```json -{ - "event": "created", - "timestamp": "2021-03-09 17:55:33.968016+00:00", - "model": "site", - "username": "jstretch", - "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a", - "data": { - "id": 19, - "name": "Site 1", - "slug": "site-1", - "status": - "value": "active", - "label": "Active", - "id": 1 - }, - "region": null, - ... - }, - "snapshots": { - "prechange": null, - "postchange": { - "created": "2021-03-09", - "last_updated": "2021-03-09T17:55:33.851Z", - "name": "Site 1", - "slug": "site-1", - "status": "active", - ... - } - } -} -``` - -## Conditional Webhooks - -A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active": - -```json -{ - "and": [ - { - "attr": "status.value", - "value": "active" - } - ] -} -``` - -For more detail, see the reference documentation for NetBox's [conditional logic](../../reference/conditions.md). - -## Webhook Processing - -When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks. - -A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI. - -## Troubleshooting - -To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory: - -```no-highlight -$ python netbox/manage.py webhook_receiver -Listening on port http://localhost:9000. Stop with CONTROL-C. -``` - -You can test the receiver itself by sending any HTTP request to it. For example: - -```no-highlight -$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}' -``` - -The server will print output similar to the following: - -```no-highlight -[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 - -Host: localhost:9000 -User-Agent: curl/7.58.0 -Accept: */* -Content-Length: 14 -Content-Type: application/x-www-form-urlencoded - -{"foo": "bar"} ------------- -``` - -Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. - -Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI). From f9fb2cc69827559d7934718b3eb84806c278510b Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 15:29:26 -0400 Subject: [PATCH 217/245] Finish features documentation --- docs/development/models.md | 2 +- .../{integrations.md => api-integration.md} | 2 +- docs/features/authentication-permissions.md | 49 +++++++++++++++++++ docs/features/customization.md | 41 ++++++++++++++-- docs/features/permissions.md | 3 -- docs/features/sso.md | 3 -- docs/features/tags.md | 0 docs/integrations/webhooks.md | 2 +- mkdocs.yml | 10 ++-- 9 files changed, 92 insertions(+), 20 deletions(-) rename docs/features/{integrations.md => api-integration.md} (99%) create mode 100644 docs/features/authentication-permissions.md delete mode 100644 docs/features/permissions.md delete mode 100644 docs/features/sso.md delete mode 100644 docs/features/tags.md diff --git a/docs/development/models.md b/docs/development/models.md index 3c7aaaa78..3b03c8935 100644 --- a/docs/development/models.md +++ b/docs/development/models.md @@ -12,7 +12,7 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/ * [Webhooks](../integrations/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects * [Custom fields](../customization/custom-fields.md) - These models support the addition of user-defined fields * [Export templates](../customization/export-templates.md) - Users can create custom export templates for these models -* [Tagging](../features/tags.md) - The models can be tagged with user-defined tags +* [Tagging](../models/extras/tag.md) - The models can be tagged with user-defined tags * [Journaling](../features/journaling.md) - These models support persistent historical commentary * Nesting - These models can be nested recursively to create a hierarchy diff --git a/docs/features/integrations.md b/docs/features/api-integration.md similarity index 99% rename from docs/features/integrations.md rename to docs/features/api-integration.md index c2f68c5c8..50c31ec4f 100644 --- a/docs/features/integrations.md +++ b/docs/features/api-integration.md @@ -1,4 +1,4 @@ -# Integrations +# API & Integration NetBox includes a slew of features which enable integration with other tools and resources powering your network. diff --git a/docs/features/authentication-permissions.md b/docs/features/authentication-permissions.md new file mode 100644 index 000000000..14e13d5cd --- /dev/null +++ b/docs/features/authentication-permissions.md @@ -0,0 +1,49 @@ +# Authentication & Permissions + +## Object-Based Permissions + +NetBox boasts a very robust permissions system which extends well beyond the model-based permissions of the underlying Django framework. Assigning permissions in NetBox involves several dimensions: + +* The type(s) of object to which the permission applies +* The users and/or groups being granted the permissions +* The action(s) permitted by the permission (e.g. view, add, change, etc.) +* Any constraints limiting application of the permission to a particular subset of objects + +The implementation of constrains is what enables NetBox administrators to assign per-object permissions: Users can be limited to viewing or interacting with arbitrary subsets of objects based on the objects' attributes. For example, you might restrict a particular user to viewing only those prefixes or IP addresses within a particular VRF. Or you might restrict a group to modifying devices within a particular region. + +Permission constraints are declared in JSON format when creating a permission, and operate very similarly to Django ORM queries. For instance, here's a constraint that matches reserved VLANs with a VLAN ID between 100 and 199: + +```json +[ + { + "vid__gte": 100, + "vid__lt": 200 + }, + { + "status": "reserved" + } +] +``` + +Check out the [permissions documentation](../administration/permissions.md) for more information about permission constraints. + +## LDAP Authentication + +NetBox includes a built-in authentication backend for authenticating users against a remote LDAP server. The [installation documentation](../installation/6-ldap.md) provides more detail on this capability. + +## Single Sign-On (SSO) + +NetBox integrates with the open source [python-social-auth](https://github.com/python-social-auth) library to provide [myriad options](https://python-social-auth.readthedocs.io/en/latest/backends/index.html#supported-backends) for single sign-on (SSO) authentication. These include: + +* Cognito +* GitHub & GitHub Enterprise +* GitLab +* Google +* Hashicorp Vault +* Keycloak +* Microsoft Azure AD +* Microsoft Graph +* Okta +* OIDC + +...and many others. It's also possible to build your own custom backends as needed using python-social-auth's base OAuth, OpenID, and SAML classes. You can find some examples of configuring SSO in NetBox' [authentication documentation](../administration/authentication/overview.md). diff --git a/docs/features/customization.md b/docs/features/customization.md index 5b42d5e43..d7f2cf40a 100644 --- a/docs/features/customization.md +++ b/docs/features/customization.md @@ -2,6 +2,10 @@ While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs. +## Tags + +Most objects in NetBox can be assigned user-created tags to aid with organization and filtering. Tag values are completely arbitrary: They may be used to store data in key-value pairs, or they may be employed simply as labels against which objects can be filtered. Each tag can also be assigned a color for quicker differentiation in the user interface. + ## Custom Fields While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs. @@ -12,30 +16,57 @@ To learn more about this feature, check out the [custom field documentation](../ ## Custom Links -TODO +Custom links allow you to conveniently reference external resources related to NetBox objects from within the NetBox UI. For example, you might wish to link each virtual machine modeled in NetBox to its corresponding view in some orchestration application. You can do this by creating a templatized custom link for the virtual machine model, specifying something like the following for the link URL: + +```no-highlight +http://server.local/vms/?name={{ object.name }} +``` + +Now, when viewing a virtual machine in NetBox, a user will see a handy button with the chosen title and link (complete with the name of the VM being viewed). Both the text and URL of custom links can be templatized in this manner, and custom links can be grouped together into dropdowns for more efficient display. To learn more about this feature, check out the [custom link documentation](../customization/custom-links.md). ## Custom Validation -TODO +While NetBox employs robust built-in object validation to ensure the integrity of its database, you might wish to enforce additional rules governing the creation and modification of certain objects. For example, perhaps you require that every device defined in NetBox adheres to a particular naming scheme and includes an asset tag. You can configure a custom validation rule in NetBox to enforce these requirements for the device model: + +```python +CUSTOM_VALIDATORS = { + "dcim.device": [ + { + "name": { + "regex": "[a-z]+\d{3}" + }, + "asset_tag": { + "required": True + } + } + ] +} +``` To learn more about this feature, check out the [custom validation documentation](../customization/custom-validation.md). ## Export Templates -TODO +Most NetBox objects can be exported in bulk in two built-in CSV formats: The current view (what the user currently sees in the objects list), or all available data. NetBox also provides the capability to define your own custom data export formats via export templates. An export template is essentially [Jinja2](https://jinja.palletsprojects.com/) template code associated with a particular object type. From the objects list in the NetBox UI, a user can select any of the created export templates to export the objects according to the template logic. + +An export template doesn't have to render CSV data: Its output can be in any character-based format. For example, you might want to render data using tabs as delimiters, or even create DNS address records directly from the IP addresses list. Export templates are a great way to get the data you need in the format you need quickly. To learn more about this feature, check out the [export template documentation](../customization/export-templates.md). ## Reports -TODO +NetBox administrators can install custom Python scripts, known as _reports_, which run within NetBox and can be executed and analyzed within the NetBox UI. Reports are a great way to evaluate NetBox objects against a set of arbitrary rules. For example, you could write a report to check that every router has a loopback interface with an IP address assigned, or that every site has a minimum set of VLANs defined. + +When a report runs, its logs messages pertaining to the operations being performed, and will ultimately result in either a pass or fail. Reports can be executed via the UI, REST API, or CLI (as a management command). To learn more about this feature, check out the [documentation for reports](../customization/reports.md). ## Custom Scripts -TODO +Custom scripts are similar to reports, but more powerful. A custom script can prompt the user for input via a form (or API data), and is built to do much more than just reporting. Custom scripts are generally used to automate tasks, such as the population of new objects in NetBox, or exchanging data with external systems. + +The complete Python environment is available to a custom script, including all of NetBox's internal mechanisms: There are no artificial restrictions on what a script can do. As such, custom scripting is considered an advanced feature and requires sufficient familiarity with Python and NetBox's data model. To learn more about this feature, check out the [documentation for custom scripts](../customization/custom-scripts.md). diff --git a/docs/features/permissions.md b/docs/features/permissions.md deleted file mode 100644 index a422ca7b3..000000000 --- a/docs/features/permissions.md +++ /dev/null @@ -1,3 +0,0 @@ -# Object-Based Permissions - -TODO diff --git a/docs/features/sso.md b/docs/features/sso.md deleted file mode 100644 index b4f9782c2..000000000 --- a/docs/features/sso.md +++ /dev/null @@ -1,3 +0,0 @@ -# Single Sign-On (SSO) - -TODO diff --git a/docs/features/tags.md b/docs/features/tags.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/integrations/webhooks.md b/docs/integrations/webhooks.md index 3ef28fb11..9a1094988 100644 --- a/docs/integrations/webhooks.md +++ b/docs/integrations/webhooks.md @@ -85,7 +85,7 @@ A webhook may include a set of conditional logic expressed in JSON used to contr } ``` -For more detail, see the reference documentation for NetBox's [conditional logic](../../reference/conditions.md). +For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md). ## Webhook Processing diff --git a/mkdocs.yml b/mkdocs.yml index a5eb36d81..8bcf6cebf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,8 +61,6 @@ nav: - Introduction: 'introduction.md' - Features: - Facilities: 'features/facilities.md' - - Tenancy: 'features/tenancy.md' - - Contacts: 'features/contacts.md' - Devices & Cabling: 'features/devices-cabling.md' - Power Tracking: 'features/power-tracking.md' - IPAM: 'features/ipam.md' @@ -70,14 +68,14 @@ nav: - L2VPN & Overlay: 'features/l2vpn-overlay.md' - Circuits: 'features/circuits.md' - Wireless: 'features/wireless.md' + - Tenancy: 'features/tenancy.md' + - Contacts: 'features/contacts.md' - Context Data: 'features/context-data.md' - Change Logging: 'features/change-logging.md' - Journaling: 'features/journaling.md' - - Tags: 'features/tags.md' - - Integrations: 'features/integrations.md' + - Auth & Permissions: 'features/authentication-permissions.md' + - API & Integration: 'features/api-integration.md' - Customization: 'features/customization.md' - - Object-Based Permissions: 'features/permissions.md' - - Single Sign-On (SSO): 'features/sso.md' - Installation & Upgrade: - Installing NetBox: 'installation/index.md' - 1. PostgreSQL: 'installation/1-postgresql.md' From 0750e27351db01161b74fa7417410ae9bdead423 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 16:14:06 -0400 Subject: [PATCH 218/245] Finish customization docs --- docs/customization/custom-fields.md | 108 +++++++++++++++++++++ docs/customization/custom-links.md | 66 +++++++++++++ docs/customization/export-templates.md | 81 ++++++++++++++++ docs/models/extras/customfield.md | 128 +++++++++++-------------- docs/models/extras/customlink.md | 94 ++++++++---------- docs/models/extras/exporttemplate.md | 80 +++------------- 6 files changed, 365 insertions(+), 192 deletions(-) diff --git a/docs/customization/custom-fields.md b/docs/customization/custom-fields.md index e69de29bb..c443fa9f6 100644 --- a/docs/customization/custom-fields.md +++ b/docs/customization/custom-fields.md @@ -0,0 +1,108 @@ +# Custom Fields + +Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. + +However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. + +Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. + +## Creating Custom Fields + +Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports many types of custom field: + +* Text: Free-form text (intended for single-line use) +* Long text: Free-form of any length; supports Markdown rendering +* Integer: A whole number (positive or negative) +* Boolean: True or false +* Date: A date in ISO 8601 format (YYYY-MM-DD) +* URL: This will be presented as a link in the web UI +* JSON: Arbitrary data stored in JSON format +* Selection: A selection of one of several pre-defined custom choices +* Multiple selection: A selection field which supports the assignment of multiple values +* Object: A single NetBox object of the type defined by `object_type` +* Multiple object: One or more NetBox objects of the type defined by `object_type` + +Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. + +Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. + +A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. + +### Filtering + +The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. + +### Grouping + +!!! note + This feature was introduced in NetBox v3.3. + +Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) + +This parameter has no effect on the API representation of custom field data. + +### Visibility + +!!! note + This feature was introduced in NetBox v3.3. + +When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. + +* **Read/write** (default): The custom field is included when viewing and editing objects. +* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. + +Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. + +### Validation + +NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: + +* Text: Regular expression (optional) +* Integer: Minimum and/or maximum value (optional) +* Selection: Must exactly match one of the prescribed choices + +### Custom Selection Fields + +Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. + +If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. + +### Custom Object Fields + +An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. + +## Custom Fields in Templates + +Several features within NetBox, such as export templates and webhooks, utilize Jinja2 templating. For convenience, objects which support custom field assignment expose custom field data through the `cf` property. This is a bit cleaner than accessing custom field data through the actual field (`custom_field_data`). + +For example, a custom field named `foo123` on the Site model is accessible on an instance as `{{ site.cf.foo123 }}`. + +## Custom Fields and the REST API + +When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined: + +```json +{ + "id": 123, + "url": "http://localhost:8000/api/dcim/sites/123/", + "name": "Raleigh 42", + ... + "custom_fields": { + "deployed": "2018-06-19", + "site_code": "US-NC-RAL42" + }, + ... +``` + +To set or change these values, simply include nested JSON data. For example: + +```json +{ + "name": "New Site", + "slug": "new-site", + "custom_fields": { + "deployed": "2019-03-24" + } +} +``` diff --git a/docs/customization/custom-links.md b/docs/customization/custom-links.md index e69de29bb..16ba9d2af 100644 --- a/docs/customization/custom-links.md +++ b/docs/customization/custom-links.md @@ -0,0 +1,66 @@ +# Custom Links + +Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS). + +Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the NetBox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`. + +For example, you might define a link like this: + +* Text: `View NMS` +* URL: `https://nms.example.com/nodes/?name={{ obj.name }}` + +When viewing a device named Router4, this link would render as: + +```no-highlight +View NMS +``` + +Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually. + +!!! warning + Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users. + +## Context Data + +The following context data is available within the template when rendering a custom link's text or URL. + +| Variable | Description | +|-----------|-------------------------------------------------------------------------------------------------------------------| +| `object` | The NetBox object being displayed | +| `obj` | Same as `object`; maintained for backward compatability until NetBox v3.5 | +| `debug` | A boolean indicating whether debugging is enabled | +| `request` | The current WSGI request | +| `user` | The current user (if authenticated) | +| `perms` | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user | + +While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type. + +Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list. + +## Conditional Rendering + +Only links which render with non-empty text are included on the page. You can employ conditional Jinja2 logic to control the conditions under which a link gets rendered. + +For example, if you only want to display a link for active devices, you could set the link text to + +```jinja2 +{% if obj.status == 'active' %}View NMS{% endif %} +``` + +The link will not appear when viewing a device with any status other than "active." + +As another example, if you wanted to show only devices belonging to a certain manufacturer, you could do something like this: + +```jinja2 +{% if obj.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %} +``` + +The link will only appear when viewing a device with a manufacturer name of "Cisco." + +## Link Groups + +Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group. + +## Table Columns + +Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL. diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index e69de29bb..640a97531 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -0,0 +1,81 @@ +# Export Templates + +NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. + +Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. + +Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). + +!!! note + The name `table` is reserved for internal use. + +!!! warning + Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. + +The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: + +```jinja2 +{% for rack in queryset %} +Rack: {{ rack.name }} +Site: {{ rack.site.name }} +Height: {{ rack.u_height }}U +{% endfor %} +``` + +To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. + +If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: +``` +{% for server in queryset %} +{% set data = server.get_config_context() %} +{{ data.syslog }} +{% endfor %} +``` + +The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) + +A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. + + +## REST API Integration + +When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: + +``` +GET /api/dcim/sites/?export=MyTemplateName +``` + +Note that the body of the response will contain only the rendered export template content, as opposed to a JSON object or list. + +## Example + +Here's an example device export template that will generate a simple Nagios configuration from a list of devices. + +``` +{% for device in queryset %}{% if device.status and device.primary_ip %}define host{ + use generic-switch + host_name {{ device.name }} + address {{ device.primary_ip.address.ip }} +} +{% endif %}{% endfor %} +``` + +The generated output will look something like this: + +``` +define host{ + use generic-switch + host_name switch1 + address 192.0.2.1 +} +define host{ + use generic-switch + host_name switch2 + address 192.0.2.2 +} +define host{ + use generic-switch + host_name switch3 + address 192.0.2.3 +} +``` diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md index bfe412edc..0b2bc29f9 100644 --- a/docs/models/extras/customfield.md +++ b/docs/models/extras/customfield.md @@ -1,109 +1,93 @@ # Custom Fields -Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows. +## Fields -However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data. +### Model(s) -Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects. +Select the NetBox object type or types to which this custom field applies. -## Creating Custom Fields +### Name -Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field: +The raw field name. This will be used in the database and API, and should consist only of alphanumeric characters and underscores. (Use the `label` field to designate a human-friendly name for the custom field.) -* Text: Free-form text (intended for single-line use) -* Long text: Free-form of any length; supports Markdown rendering -* Integer: A whole number (positive or negative) -* Boolean: True or false -* Date: A date in ISO 8601 format (YYYY-MM-DD) -* URL: This will be presented as a link in the web UI -* JSON: Arbitrary data stored in JSON format -* Selection: A selection of one of several pre-defined custom choices -* Multiple selection: A selection field which supports the assignment of multiple values -* Object: A single NetBox object of the type defined by `object_type` -* Multiple object: One or more NetBox objects of the type defined by `object_type` +### Label -Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form. +An optional human-friendly name for the custom field. If not defined, the field's `name` attribute will be used. -Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields. +### Group Name -A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields. +If this custom field should be grouped with others, specify the name of the group here. Custom fields with no group defined will be ordered only by weight and name. -### Filtering +### Type -The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely. +The type of data this field holds. This must be one of the following: -### Grouping +| Type | Description | +|--------------------|--------------------------------------------------------------------| +| Text | Free-form text (intended for single-line use) | +| Long text | Free-form of any length; supports Markdown rendering | +| Integer | A whole number (positive or negative) | +| Boolean | True or false | +| Date | A date in ISO 8601 format (YYYY-MM-DD) | +| URL | This will be presented as a link in the web UI | +| JSON | Arbitrary data stored in JSON format | +| Selection | A selection of one of several pre-defined custom choices | +| Multiple selection | A selection field which supports the assignment of multiple values | +| Object | A single NetBox object of the type defined by `object_type` | +| Multiple object | One or more NetBox objects of the type defined by `object_type` | -!!! note - This feature was introduced in NetBox v3.3. +### Object Type -Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.) +For object and multiple-object fields only. Designates the type of NetBox object being referenced. -This parameter has no effect on the API representation of custom field data. +### Weight -### Visibility +A numeric weight used to override alphabetic ordering of fields by name. Custom fields with a lower weight will be listed before those with a higher weight. (Note that weight applies within the context of a custom field group, if defined.) -!!! note - This feature was introduced in NetBox v3.3. +### Required -When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. +If checked, this custom field must be populated with a valid value for the object to pass validation. -* **Read/write** (default): The custom field is included when viewing and editing objects. -* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) -* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. +### Description -Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. +A brief description of the field's purpose (optional). -### Validation +### Filter Logic -NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type: +Defines how filters are evaluated against custom field values. -* Text: Regular expression (optional) -* Integer: Minimum and/or maximum value (optional) -* Selection: Must exactly match one of the prescribed choices +| Option | Description | +|----------|-------------------------------------| +| Disabled | Filtering disabled | +| Loose | Match any occurrence of the value | +| Exact | Match only the complete field value | -### Custom Selection Fields +### UI Visibility -Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. +Controls how and whether the custom field is displayed within the NetBox user interface. -If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. +| Option | Description | +|------------|--------------------------------------| +| Read/write | Display and permit editing (default) | +| Read-only | Display field but disallow editing | +| Hidden | Do not display field in the UI | -### Custom Object Fields +### Default -An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point. +The default value to populate for the custom field when creating new objects (optional). This value must be expressed as JSON. If this is a choice or multi-choice field, this must be one of the available choices. +### Choices -## Custom Fields in Templates +For choice and multi-choice custom fields only. A comma-delimited list of the available choices. -Several features within NetBox, such as export templates and webhooks, utilize Jinja2 templating. For convenience, objects which support custom field assignment expose custom field data through the `cf` property. This is a bit cleaner than accessing custom field data through the actual field (`custom_field_data`). +### Minimum Value -For example, a custom field named `foo123` on the Site model is accessible on an instance as `{{ site.cf.foo123 }}`. +For numeric custom fields only. The minimum valid value (optional). -## Custom Fields and the REST API +### Maximum Value -When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined: +For numeric custom fields only. The maximum valid value (optional). -```json -{ - "id": 123, - "url": "http://localhost:8000/api/dcim/sites/123/", - "name": "Raleigh 42", - ... - "custom_fields": { - "deployed": "2018-06-19", - "site_code": "US-NC-RAL42" - }, - ... -``` +### Validation Regex -To set or change these values, simply include nested JSON data. For example: - -```json -{ - "name": "New Site", - "slug": "new-site", - "custom_fields": { - "deployed": "2019-03-24" - } -} -``` +For string-based custom fields only. A regular expression used to validate the field's value (optional). diff --git a/docs/models/extras/customlink.md b/docs/models/extras/customlink.md index 16ba9d2af..458007ab1 100644 --- a/docs/models/extras/customlink.md +++ b/docs/models/extras/customlink.md @@ -1,66 +1,54 @@ # Custom Links -Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS). +## Fields -Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the NetBox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`. +### Name -For example, you might define a link like this: +The name of the custom link. This is used primarily for administrative purposes only, although custom links of the same weight are ordered alphabetically by name when being rendered in the UI. -* Text: `View NMS` -* URL: `https://nms.example.com/nodes/?name={{ obj.name }}` +### Content Type -When viewing a device named Router4, this link would render as: +The type of NetBox object to which this custom link applies. -```no-highlight -View NMS -``` +### Weight -Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually. +A numeric weight used to override alphabetic ordering of links by name. Custom fields with a lower weight will be listed before those with a higher weight. (Note that weight applies within the context of a custom link group, if defined.) -!!! warning - Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users. +### Group Name + +If this custom link should be grouped with others, specify the name of the group here. Grouped custom links will be listed in a dropdown menu attached to a single button bearing the group name. + +### Button Class + +The color of the UI button. + +### Enabled + +If not selected, the custom link will not be rendered. This can be useful for temporarily disabling a custom link. + +### New Window + +If selected, this will force the link to open in a new browser tab or window. + +### Link Text + +Jinja2 template code for rendering the button text. (Note that this does not _need_ to contain any template variables.) See below for available context data. + +!!! note + Custom links which render an empty text value will not be displayed in the UI. This can be used to toggle the inclusion of a link based on object attributes. + +### Link URL + +Jinja2 template code for rendering the hyperlink. See below for available context data. ## Context Data -The following context data is available within the template when rendering a custom link's text or URL. +The following context variables are available in to the text and link templates. -| Variable | Description | -|-----------|-------------------------------------------------------------------------------------------------------------------| -| `object` | The NetBox object being displayed | -| `obj` | Same as `object`; maintained for backward compatability until NetBox v3.5 | -| `debug` | A boolean indicating whether debugging is enabled | -| `request` | The current WSGI request | -| `user` | The current user (if authenticated) | -| `perms` | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user | - -While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type. - -Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list. - -## Conditional Rendering - -Only links which render with non-empty text are included on the page. You can employ conditional Jinja2 logic to control the conditions under which a link gets rendered. - -For example, if you only want to display a link for active devices, you could set the link text to - -```jinja2 -{% if obj.status == 'active' %}View NMS{% endif %} -``` - -The link will not appear when viewing a device with any status other than "active." - -As another example, if you wanted to show only devices belonging to a certain manufacturer, you could do something like this: - -```jinja2 -{% if obj.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %} -``` - -The link will only appear when viewing a device with a manufacturer name of "Cisco." - -## Link Groups - -Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group. - -## Table Columns - -Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL. +| Variable | Description | +|-----------|-----------------------------------------------------------------------------| +| `object` | The NetBox object being displayed | +| `debug` | A boolean indicating whether debugging is enabled | +| `request` | The current WSGI request | +| `user` | The current user (if authenticated) | +| `perms` | The [permissions](../../administration/permissions.md) assigned to the user | diff --git a/docs/models/extras/exporttemplate.md b/docs/models/extras/exporttemplate.md index b4b69108a..347184324 100644 --- a/docs/models/extras/exporttemplate.md +++ b/docs/models/extras/exporttemplate.md @@ -1,81 +1,27 @@ # Export Templates -NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates. +## Fields -Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension. +### Name -Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/). +The name of the export template. This will appear in the "export" dropdown list in the NetBox UI. -!!! note - The name `table` is reserved for internal use. +### Content Type -!!! warning - Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users. +The type of NetBox object to which the export template applies. -The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example: +### Template Code -```jinja2 -{% for rack in queryset %} -Rack: {{ rack.name }} -Site: {{ rack.site.name }} -Height: {{ rack.u_height }}U -{% endfor %} -``` +Jinja2 template code for rendering the exported data. -To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`. +### MIME Type -If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example: -``` -{% for server in queryset %} -{% set data = server.get_config_context() %} -{{ data.syslog }} -{% endfor %} -``` +The MIME type to indicate in the response when rendering the export template (optional). Defaults to `text/plain`. -The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) +### File Extension -A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. +The file extension to append to the file name in the response (optional). +### As Attachment -## REST API Integration - -When it is necessary to provide authentication credentials (such as when [`LOGIN_REQUIRED`](../../configuration/security.md#login_required) has been enabled), it is recommended to render export templates via the REST API. This allows the client to specify an authentication token. To render an export template via the REST API, make a `GET` request to the model's list endpoint and append the `export` parameter specifying the export template name. For example: - -``` -GET /api/dcim/sites/?export=MyTemplateName -``` - -Note that the body of the response will contain only the rendered export template content, as opposed to a JSON object or list. - -## Example - -Here's an example device export template that will generate a simple Nagios configuration from a list of devices. - -``` -{% for device in queryset %}{% if device.status and device.primary_ip %}define host{ - use generic-switch - host_name {{ device.name }} - address {{ device.primary_ip.address.ip }} -} -{% endif %}{% endfor %} -``` - -The generated output will look something like this: - -``` -define host{ - use generic-switch - host_name switch1 - address 192.0.2.1 -} -define host{ - use generic-switch - host_name switch2 - address 192.0.2.2 -} -define host{ - use generic-switch - host_name switch3 - address 192.0.2.3 -} -``` +If selected, the rendered content will be returned as a file attachment, rather than displayed directly in-browser (where supported). From 7e3050cf83e729ed43a9e591e7dd937c7a98febb Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 11 Aug 2022 16:34:29 -0400 Subject: [PATCH 219/245] Add "getting started" links --- docs/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index a6bbcecff..d412d1a49 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,7 +24,7 @@ Unlike general-purpose CMDBs, NetBox has curated a data model which caters speci ## Customizable & Extensible -In addition to its expansive and robust data model, NetBox offers myriad mechanisms through it can be customized and extended. +In addition to its expansive and robust data model, NetBox offers myriad mechanisms through which it can be customized and extended. * Custom fields * Custom model validation @@ -39,10 +39,10 @@ Because NetBox is an open source application licensed under [Apache 2](https://w ## Getting Started -* Public Demo -* Installation Guide -* Docker install -* NetBox Cloud +* Try out our [public demo](https://demo.netbox.dev/) if you want to jump right in +* The [installation guide](./installation/index.md) will help you get your own deployment up and running +* Or try the community [Docker image](https://github.com/netbox-community/netbox-docker) for a low-touch approach +* [NetBox Cloud](https://www.getnetbox.io/) is a hosted solution offered by NS1 !!! tip "NetBox Development" Interested in contributing to NetBox? Check out our [GitHub repository](https://github.com/netbox-community/netbox) to get started! From c635f09e058877a462c7f8e8a44aa1fad1f0997e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 09:21:28 -0400 Subject: [PATCH 220/245] Closes #9994: Disable search indexing for local documentation builds --- docs/_theme/main.html | 9 +++++++++ mkdocs.yml | 2 ++ 2 files changed, 11 insertions(+) create mode 100644 docs/_theme/main.html diff --git a/docs/_theme/main.html b/docs/_theme/main.html new file mode 100644 index 000000000..4dfc4e14e --- /dev/null +++ b/docs/_theme/main.html @@ -0,0 +1,9 @@ +{% extends "base.html" %} + +{% block site_meta %} + {{ super() }} + {# Disable search indexing unless we're building for ReadTheDocs #} + {% if not config.extra.readthedocs %} + + {% endif %} +{% endblock %} diff --git a/mkdocs.yml b/mkdocs.yml index 34c65ed01..b13ab6c49 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,7 @@ repo_name: netbox-community/netbox repo_url: https://github.com/netbox-community/netbox theme: name: material + custom_dir: docs/_theme/ icon: repo: fontawesome/brands/github palette: @@ -37,6 +38,7 @@ plugins: show_root_toc_entry: false show_source: false extra: + readthedocs: !ENV READTHEDOCS social: - icon: fontawesome/brands/github link: https://github.com/netbox-community/netbox From 642fe422c458d4e5f3409c827100c2f2ac60c920 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 13:39:07 -0400 Subject: [PATCH 221/245] Touch up intro page --- docs/index.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/index.md b/docs/index.md index d412d1a49..c233dedb7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,16 +2,16 @@ # The Premiere Network Source of Truth -NetBox is the leading solution for modeling modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. +NetBox is the leading solution for modeling and documenting modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. Read on to discover why thousands of organizations worldwide put NetBox at the heart of their infrastructure. -## Built for Networks +## :material-server-network: Built for Networks -Unlike general-purpose CMDBs, NetBox has curated a data model which caters specifically to the needs of network engineers and operators. It delivers a wide assortment of object types carefully crafted to best serve the needs of network engineers and operators. These cover all facets of network design, from IP address managements to cabling to overlays and more: +Unlike general-purpose CMDBs, NetBox has curated a data model which caters specifically to the needs of network engineers and operators. It delivers a wide assortment of object types carefully crafted to best serve the needs of infrastructure design and documentation. These cover all facets of network technology, from IP address managements to cabling to overlays and more: -* Hierarchical regions, site groups, sites, and locations +* Hierarchical regions, sites, and locations * Racks, devices, and device components * Cables and wireless connections -* Power distribution +* Power distribution tracking * Data circuits and providers * Virtual machines and clusters * IP prefixes, ranges, and addresses @@ -20,11 +20,12 @@ Unlike general-purpose CMDBs, NetBox has curated a data model which caters speci * AS numbers * VLANs and scoped VLAN groups * L2VPN overlays -* Organizational tenants and contacts +* Tenancy assignments +* Contact management -## Customizable & Extensible +## :material-hammer-wrench: Customizable & Extensible -In addition to its expansive and robust data model, NetBox offers myriad mechanisms through which it can be customized and extended. +In addition to its expansive and robust data model, NetBox offers myriad mechanisms through which it can be customized and extended. Its powerful plugins architecture enables users to extend the application to meet their needs with minimal development effort. * Custom fields * Custom model validation @@ -33,16 +34,20 @@ In addition to its expansive and robust data model, NetBox offers myriad mechani * Plugins * REST & GraphQL APIs -## Always Open +## :material-lock-open: Always Open -Because NetBox is an open source application licensed under [Apache 2](https://www.apache.org/licenses/LICENSE-2.0.html), its entire code base is completely accessible to the end user, and there's never a risk of vendor lock-out. Additionally, NetBox development is an entirely public, community-driven process to which everyone can provide input. +Because NetBox is an open source application licensed under [Apache 2](https://www.apache.org/licenses/LICENSE-2.0.html), its entire code base is completely accessible to the end user, and there's never a risk of vendor lock-in. Additionally, NetBox development is an entirely public, community-driven process to which everyone can provide input. -## Getting Started +!!! tip "NetBox Development" + Interested in contributing to NetBox? Check out our [GitHub repository](https://github.com/netbox-community/netbox) to get started! + +## :material-language-python: Powered by Python + +NetBox is built on the enormously popular [Django](http://www.djangoproject.com/) framework for the Python programming language, already a favorite among network engineers. Users can leverage their existing skills coding Python tools to extend NetBox's already vast functionality via custom scripts and plugins. + +## :material-flag: Getting Started * Try out our [public demo](https://demo.netbox.dev/) if you want to jump right in * The [installation guide](./installation/index.md) will help you get your own deployment up and running * Or try the community [Docker image](https://github.com/netbox-community/netbox-docker) for a low-touch approach * [NetBox Cloud](https://www.getnetbox.io/) is a hosted solution offered by NS1 - -!!! tip "NetBox Development" - Interested in contributing to NetBox? Check out our [GitHub repository](https://github.com/netbox-community/netbox) to get started! From 8c5779c8642f5984fd101508d11b4d4e80a7d9f9 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 14:11:58 -0400 Subject: [PATCH 222/245] Add feature docs for virtualization --- docs/features/virtualization.md | 26 ++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 27 insertions(+) create mode 100644 docs/features/virtualization.md diff --git a/docs/features/virtualization.md b/docs/features/virtualization.md new file mode 100644 index 000000000..8e1bf35ef --- /dev/null +++ b/docs/features/virtualization.md @@ -0,0 +1,26 @@ +# Virtualization + +Virtual machines and clusters can be modeled in NetBox alongside physical infrastructure. IP addresses and other resources are assigned to these objects just like physical objects, providing a seamless integration between physical and virtual networks. + +```mermaid +flowchart TD + ClusterGroup & ClusterType --> Cluster + Cluster --> VirtualMachine + Platform --> VirtualMachine + VirtualMachine --> VMInterface + +click Cluster "../../models/virtualization/cluster/" +click ClusterGroup "../../models/virtualization/clustergroup/" +click ClusterType "../../models/virtualization/clustertype/" +click Platform "../../models/dcim/platform/" +click VirtualMachine "../../models/virtualization/virtualmachine/" +click VMInterface "../../models/virtualization/vminterface/" +``` + +## Clusters + +A cluster is one or more physical host devices on which virtual machines can run. Each cluster must have a type and operational status, and may be assigned to a group. (Both types and groups are user-defined.) Each cluster may designate one or more devices as hosts, however this is optional. + +## Virtual Machines + +A virtual machine is a virtualized compute instance. These behave in NetBox very similarly to device objects, but without any physical attributes. For example, a VM may have interfaces assigned to it with IP addresses and VLANs, however its interfaces cannot be connected via cables (because they are virtual). Each VM may also define its compute, memory, and storage resources as well. diff --git a/mkdocs.yml b/mkdocs.yml index 9eea20397..be9c31651 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,7 @@ nav: - L2VPN & Overlay: 'features/l2vpn-overlay.md' - Circuits: 'features/circuits.md' - Wireless: 'features/wireless.md' + - Virtualization: 'features/virtualization.md' - Tenancy: 'features/tenancy.md' - Contacts: 'features/contacts.md' - Context Data: 'features/context-data.md' From 9c667bb3af7fb8339acfd04ee586f98526ccf71e Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 14:14:56 -0400 Subject: [PATCH 223/245] Add hyperlinks to Mermaid graphs --- docs/features/circuits.md | 6 ++++ docs/features/contacts.md | 4 +++ docs/features/devices-cabling.md | 8 ++++++ docs/features/facilities.md | 8 ++++++ docs/features/ipam.md | 9 +++++- docs/features/tenancy.md | 3 ++ docs/features/vlan-management.md | 4 +++ docs/features/wireless.md | 3 ++ docs/getting-started/planning.md | 49 ++++++++++++++++++++++++++++++-- 9 files changed, 91 insertions(+), 3 deletions(-) diff --git a/docs/features/circuits.md b/docs/features/circuits.md index f0c5832c4..7739efb4c 100644 --- a/docs/features/circuits.md +++ b/docs/features/circuits.md @@ -7,6 +7,12 @@ flowchart TD ASN --> Provider Provider --> ProviderNetwork & Circuit CircuitType --> Circuit + +click ASN "../../models/circuits/asn/" +click Circuit "../../models/circuits/circuit/" +click CircuitType "../../models/circuits/circuittype/" +click Provider "../../models/circuits/provider/" +click ProviderNetwork "../../models/circuits/providernetwork/" ``` ## Providers diff --git a/docs/features/contacts.md b/docs/features/contacts.md index 7d717b2de..6bbd217fc 100644 --- a/docs/features/contacts.md +++ b/docs/features/contacts.md @@ -7,6 +7,10 @@ flowchart TD ContactGroup --> ContactGroup & Contact ContactRole & Contact --> assignment([Assignment]) assignment --> Object + +click Contact "../../models/tenancy/contact/" +click ContactGroup "../../models/tenancy/contactgroup/" +click ContactRole "../../models/tenancy/contactrole/" ``` ## Contact Groups diff --git a/docs/features/devices-cabling.md b/docs/features/devices-cabling.md index 7297f79ac..bec3e56de 100644 --- a/docs/features/devices-cabling.md +++ b/docs/features/devices-cabling.md @@ -11,6 +11,14 @@ flowchart TD DeviceRole & Platform & DeviceType --> Device Device & ModuleType ---> Module Device & Module --> Interface & ConsolePort & PowerPort & ... + +click Device "../../models/dcim/device/" +click DeviceRole "../../models/dcim/devicerole/" +click DeviceType "../../models/dcim/devicetype/" +click Manufacturer "../../models/dcim/manufacturer/" +click Module "../../models/dcim/module/" +click ModuleType "../../models/dcim/moduletype/" +click Platform "../../models/dcim/platform/" ``` ## Manufacturers diff --git a/docs/features/facilities.md b/docs/features/facilities.md index f105bd4c5..84c7c5733 100644 --- a/docs/features/facilities.md +++ b/docs/features/facilities.md @@ -13,6 +13,14 @@ flowchart TD Rack --> Device Site --> Rack RackRole --> Rack + +click Device "../../models/dcim/device/" +click Location "../../models/dcim/location/" +click Rack "../../models/dcim/rack/" +click RackRole "../../models/dcim/rackrole/" +click Region "../../models/dcim/region/" +click Site "../../models/dcim/site/" +click SiteGroup "../../models/dcim/sitegroup/" ``` ## Regions diff --git a/docs/features/ipam.md b/docs/features/ipam.md index 45a6a0221..d67645b17 100644 --- a/docs/features/ipam.md +++ b/docs/features/ipam.md @@ -17,8 +17,15 @@ flowchart TD Aggregate & Role --> Prefix Prefix --> Prefix Prefix --> IPRange & IPAddress + +click Aggregate "../../models/ipam/aggregate/" +click IPAddress "../../models/ipam/ipaddress/" +click IPRange "../../models/ipam/iprange/" +click Prefix "../../models/ipam/prefix/" +click RIR "../../models/ipam/rir/" +click Role "../../models/ipam/role/" ``` - + !!! tip "Automatic Hierarchies" IP objects in NetBox never need to be manually assigned to the parent objects. The construction of hierarchies is handled automatically by the application according to the inherent rules of IP addressing. diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md index fe6d8e5a8..a278dc4c2 100644 --- a/docs/features/tenancy.md +++ b/docs/features/tenancy.md @@ -6,6 +6,9 @@ Most core objects within NetBox's data model support _tenancy_. This is the asso flowchart TD TenantGroup --> TenantGroup & Tenant Tenant --> Site & Device & Prefix & Circuit & ... + +click Tenant "../../models/tenancy/tenant/" +click TenantGroup "../../models/tenancy/tenantgroup/" ``` ## Tenant Groups diff --git a/docs/features/vlan-management.md b/docs/features/vlan-management.md index 4af05dea3..c74c9015c 100644 --- a/docs/features/vlan-management.md +++ b/docs/features/vlan-management.md @@ -5,6 +5,10 @@ Complementing its IPAM capabilities, NetBox also tracks VLAN information to assi ```mermaid flowchart TD VLANGroup & Role --> VLAN + +click Role "../../models/ipam/role/" +click VLAN "../../models/ipam/vlan/" +click VLANGroup "../../models/ipam/vlangroup/" ``` ## VLAN Groups diff --git a/docs/features/wireless.md b/docs/features/wireless.md index 215d1a682..c78387efb 100644 --- a/docs/features/wireless.md +++ b/docs/features/wireless.md @@ -7,6 +7,9 @@ Just as NetBox provides robust modeling for physical cable plants, it also suppo ```mermaid flowchart TD WirelessLANGroup --> WirelessLANGroup & WirelessLAN + +click WirelessLAN "../../models/wireless/wirelesslan/" +click WirelessLANGroup "../../models/wireless/wirelesslangroup/" ``` A wireless LAN is a multi-access network shared by multiple wireless clients, identified by a common service set identifier (SSID) and authentication parameters. Wireless LANs can be organized into self-nesting groups, and each wireless LAN may optionally be bound to a particular VLAN. This allows easily mapping wireless networks to their wired counterparts. diff --git a/docs/getting-started/planning.md b/docs/getting-started/planning.md index 5c431a4d2..5dbe6e54e 100644 --- a/docs/getting-started/planning.md +++ b/docs/getting-started/planning.md @@ -78,9 +78,15 @@ The graphs below illustrate some of the core dependencies among different models ```mermaid flowchart TD - TenantGroup --> TenantGroup - TenantGroup --> Tenant + TenantGroup --> TenantGroup & Tenant Tenant --> Site & Device & Prefix & VLAN & ... + +click Device "../../models/dcim/device/" +click Prefix "../../models/ipam/prefix/" +click Site "../../models/dcim/site/" +click Tenant "../../models/tenancy/tenant/" +click TenantGroup "../../models/tenancy/tenantgroup/" +click VLAN "../../models/ipam/vlan/" ``` ### Sites, Racks, and Devices @@ -99,6 +105,21 @@ flowchart TD DeviceType --> Device Device & ModuleType ---> Module Device & Module --> Interface + +click Device "../../models/dcim/device/" +click DeviceRole "../../models/dcim/devicerole/" +click DeviceType "../../models/dcim/devicetype/" +click Interface "../../models/dcim/interface/" +click Location "../../models/dcim/location/" +click Manufacturer "../../models/dcim/manufacturer/" +click Module "../../models/dcim/module/" +click ModuleType "../../models/dcim/moduletype/" +click Platform "../../models/dcim/platform/" +click Rack "../../models/dcim/rack/" +click RackRole "../../models/dcim/rackrole/" +click Region "../../models/dcim/region/" +click Site "../../models/dcim/site/" +click SiteGroup "../../models/dcim/sitegroup/" ``` ### VRFs, Prefixes, IP Addresses, and VLANs @@ -112,6 +133,16 @@ flowchart TD Aggregate & VRF --> Prefix VRF --> IPRange & IPAddress Prefix --> VLAN & IPRange & IPAddress + +click Aggregate "../../models/ipam/aggregate/" +click IPAddress "../../models/ipam/ipaddress/" +click IPRange "../../models/ipam/iprange/" +click Prefix "../../models/ipam/prefix/" +click RIR "../../models/ipam/rir/" +click Role "../../models/ipam/role/" +click VLAN "../../models/ipam/vlan/" +click VLANGroup "../../models/ipam/vlangroup/" +click VRF "../../models/ipam/vrf/" ``` ### Circuits @@ -121,6 +152,12 @@ flowchart TD Provider & CircuitType --> Circuit Provider --> ProviderNetwork Circuit --> CircuitTermination + +click Circuit "../../models/circuits/circuit/" +click CircuitTermination "../../models/circuits/circuittermination/" +click CircuitType "../../models/circuits/circuittype/" +click Provider "../../models/circuits/provider/" +click ProviderNetwork "../../models/circuits/providernetwork/" ``` ### Clusters and Virtual Machines @@ -132,4 +169,12 @@ flowchart TD Site --> Cluster & VirtualMachine Device & Platform --> VirtualMachine VirtualMachine --> VMInterface + +click Cluster "../../models/virtualization/cluster/" +click ClusterGroup "../../models/virtualization/clustergroup/" +click ClusterType "../../models/virtualization/clustertype/" +click Device "../../models/dcim/device/" +click Platform "../../models/dcim/platform/" +click VirtualMachine "../../models/virtualization/virtualmachine/" +click VMInterface "../../models/virtualization/vminterface/" ``` From fafc464d932bed1a03aaba959286f1fe66ada931 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 15:00:45 -0400 Subject: [PATCH 224/245] Refreshed circuits model documentation --- docs/models/circuits/circuit.md | 54 +++++++++++++++++----- docs/models/circuits/circuittermination.md | 42 +++++++++++++++-- docs/models/circuits/circuittype.md | 12 ++++- docs/models/circuits/provider.md | 39 +++++++++++++++- docs/models/circuits/providernetwork.md | 14 +++++- 5 files changed, 142 insertions(+), 19 deletions(-) diff --git a/docs/models/circuits/circuit.md b/docs/models/circuits/circuit.md index 3aaa4e99f..50637ab4e 100644 --- a/docs/models/circuits/circuit.md +++ b/docs/models/circuits/circuit.md @@ -1,19 +1,49 @@ # Circuits -A communications circuit represents a single _physical_ link connecting exactly two endpoints, commonly referred to as its A and Z terminations. A circuit in NetBox may have zero, one, or two terminations defined. It is common to have only one termination defined when you don't necessarily care about the details of the provider side of the circuit, e.g. for Internet access circuits. Both terminations would likely be modeled for circuits which connect one customer site to another. +A circuit represents a physical point-to-point data connection, typically used to interconnect sites across considerable distances (e.g. to deliver Internet connectivity). -Each circuit is associated with a provider and a user-defined type. For example, you might have Internet access circuits delivered to each site by one provider, and private MPLS circuits delivered by another. Each circuit must be assigned a circuit ID, each of which must be unique per provider. +## Fields -Each circuit is also assigned one of the following operational statuses: +### Provider -* Planned -* Provisioning -* Active -* Offline -* Deprovisioning -* Decommissioned +The [provider](./provider.md) to which this circuit belongs. -Circuits also have optional fields for annotating their installation and termination dates and commit rate, and may be assigned to NetBox tenants. +### Circuit ID -!!! note - NetBox currently models only physical circuits: those which have exactly two endpoints. It is common to layer virtualized constructs (_virtual circuits_) such as MPLS or EVPN tunnels on top of these, however NetBox does not yet support virtual circuit modeling. +An identifier for this circuit. This must be unique to the assigned provider. (Circuits assigned to different providers may have the same circuit ID.) + +### Circuit Type + +Each circuit is classified by a user-defined [circuit type](./circuittype.md). Generally this is something like "Internet access," "MPLS/VPN," etc. + +### Status + +The operational status of the circuit. By default, the following statuses are available: + +| Name | +|----------------| +| Planned | +| Provisioning | +| Active | +| Offline | +| Deprovisioning | +| Decommissioned | + +!!! tip "Custom circuit statuses" + Additional circuit statuses may be defined by setting `Circuit.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Description + +A brief description of the circuit. + +### Installation Date + +The date on which the circuit was installed. + +### Termination Date + +The date on which the circuit is scheduled to be disconnected. + +### Commit Rate + +The committed rate (throughput) of the circuit, in kilobits per second. diff --git a/docs/models/circuits/circuittermination.md b/docs/models/circuits/circuittermination.md index beea2f85a..c6aa966d0 100644 --- a/docs/models/circuits/circuittermination.md +++ b/docs/models/circuits/circuittermination.md @@ -1,10 +1,46 @@ # Circuit Terminations -The association of a circuit with a particular site and/or device is modeled separately as a circuit termination. A circuit may have up to two terminations, labeled A and Z. A single-termination circuit can be used when you don't know (or care) about the far end of a circuit (for example, an Internet access circuit which connects to a transit provider). A dual-termination circuit is useful for tracking circuits which connect two sites. - -Each circuit termination is attached to either a site or to a provider network. Site terminations may optionally be connected via a cable to a specific device interface or port within that site. Each termination must be assigned a port speed, and can optionally be assigned an upstream speed if it differs from the downstream speed (a common scenario with e.g. DOCSIS cable modems). Fields are also available to track cross-connect and patch panel details. +Each circuit may have up to two terminations, designated A and Z. At either termination, a circuit may connect to a site, device interface (via a cable), or to a provider network. In adherence with NetBox's philosophy of closely modeling the real world, a circuit may be connected only to a physical interface. For example, circuits may not terminate to LAG interfaces, which are virtual in nature. In such cases, a separate physical circuit is associated with each LAG member interface and each needs to be modeled discretely. !!! note A circuit in NetBox represents a physical link, and cannot have more than two endpoints. When modeling a multi-point topology, each leg of the topology must be defined as a discrete circuit, with one end terminating within the provider's infrastructure. The provider network model is ideal for representing these networks. + +## Fields + +### Circuit + +The [circuit](./circuit.md) to which this termination belongs. + +### Termination Side + +Designates the termination as forming either the A or Z end of the circuit. + +### Mark Connected + +If selected, the circuit termination will be considered "connected" even if no cable has been connected to it in NetBox. + +### Site + +The [site](../dcim/site.md) with which this circuit termination is associated. Once created, a cable can be connected between the circuit termination and a device interface (or similar component). + +### Provider Network + +Circuits which do not connect to a site modeled by NetBox can instead be terminated to a [provider network](./providernetwork.md) representing an unknown network operated by a [provider](./provider.md). + +### Port Speed + +The operating speed of the terminated interface, in kilobits per second. This is useful for documenting the speed of a circuit when the actual interface to which it terminates is not being modeled in NetBox. + +### Upstream Speed + +The upstream speed of the terminated interface (in kilobits per second), if different from the downstream speed (a common scenario with e.g. DOCSIS cable modems). + +### Cross-connect ID + +In a data center environment, circuits are often delivered via a local cross-connect. While it may not be appropriate to model the cross-connect itself in NetBox, it's a good idea to record its ID for reference where applicable. + +### Patch Panel & Port(s) + +Similar to the cross-connect ID, this field can be used to track physical connection details which may be outside the scope of what is being modeled in NetBox. diff --git a/docs/models/circuits/circuittype.md b/docs/models/circuits/circuittype.md index aa8258e04..d0baa0f89 100644 --- a/docs/models/circuits/circuittype.md +++ b/docs/models/circuits/circuittype.md @@ -1,8 +1,18 @@ # Circuit Types -Circuits are classified by functional type. These types are completely customizable, and are typically used to convey the type of service being delivered over a circuit. For example, you might define circuit types for: +[Circuits](./circuit.md) are classified by functional type. These types are completely customizable, and are typically used to convey the type of service being delivered over a circuit. For example, you might define circuit types for: * Internet transit * Out-of-band connectivity * Peering * Private backhaul + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/circuits/provider.md b/docs/models/circuits/provider.md index e0847b72f..a4835199e 100644 --- a/docs/models/circuits/provider.md +++ b/docs/models/circuits/provider.md @@ -1,5 +1,40 @@ # Providers -A circuit provider is any entity which provides some form of connectivity of among sites or organizations within a site. While this obviously includes carriers which offer Internet and private transit service, it might also include Internet exchange (IX) points and even organizations with whom you peer directly. Each circuit within NetBox must be assigned a provider and a circuit ID which is unique to that provider. +A provider is any entity which provides some form of connectivity of among sites or organizations within a site. While this obviously includes carriers which offer Internet and private transit service, it might also include Internet exchange (IX) points and even organizations with whom you peer directly. Each [circuit](./circuit.md) within NetBox must be assigned a provider and a circuit ID which is unique to that provider. -Each provider may be assigned an autonomous system number (ASN), an account number, and contact information. +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### ASN + +The AS number assigned to this provider. + +!!! warning "Legacy field" + This field is being removed in NetBox v3.4. Users are highly encouraged to use the [ASN model](../ipam/asn.md) to track AS number assignment for providers. + +### ASNs + +The [AS numbers](../ipam/asn.md) assigned to this provider (optional). + +### Account Number + +The administrative account identifier tied to this provider for your organization. + +### Portal URL + +The URL for the provider's customer service portal. + +### NOC Contact + +Contact details for the provider's network operations center (NOC). + +### Admin Contact + +Administrative contact details for the provider. diff --git a/docs/models/circuits/providernetwork.md b/docs/models/circuits/providernetwork.md index 42c46e13c..90db02573 100644 --- a/docs/models/circuits/providernetwork.md +++ b/docs/models/circuits/providernetwork.md @@ -2,4 +2,16 @@ This model can be used to represent the boundary of a provider network, the details of which are unknown or unimportant to the NetBox user. For example, it might represent a provider's regional MPLS network to which multiple circuits provide connectivity. -Each provider network must be assigned to a provider, and may optionally be assigned an arbitrary service ID. A circuit may terminate to either a provider network or to a site. +## Fields + +### Provider + +The [provider](./provider.md) responsible for the operation of this network. + +### Name + +A human-friendly name, unique to the provider. + +### Service ID + +An arbitrary identifier used as an alternate reference for the type of connectivity or service being delivered. From cff6b81f1fdfbc888e60e97be570262182d30fed Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 16:00:04 -0400 Subject: [PATCH 225/245] Refreshed extras model documentation --- docs/features/context-data.md | 58 ++++++++++++++-- docs/features/customization.md | 12 ++++ docs/models/extras/configcontext.md | 68 ++++--------------- docs/models/extras/customfield.md | 2 + docs/models/extras/customlink.md | 2 + docs/models/extras/exporttemplate.md | 2 + docs/models/extras/imageattachment.md | 10 +++ docs/models/extras/tag.md | 18 ++--- docs/models/extras/webhook.md | 95 ++++++++++++++++++++++----- 9 files changed, 184 insertions(+), 83 deletions(-) diff --git a/docs/features/context-data.md b/docs/features/context-data.md index d202482da..04e795fd5 100644 --- a/docs/features/context-data.md +++ b/docs/features/context-data.md @@ -11,10 +11,6 @@ Configuration context data (or "config contexts" for short) is a powerful featur } ``` -While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases. - -There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. Additionally, each device and VM may have local context data defined: This data is stored directly on the assigned object, and applies to it only. This is a convenient way for "attaching" miscellaneous data to a single device or VM as needed. - Config contexts can be computed for objects based on the following criteria: | Type | Devices | Virtual Machines | @@ -32,3 +28,57 @@ Config contexts can be computed for objects based on the following criteria: | Tenant group | :material-check: | :material-check: | | Tenant | :material-check: | :material-check: | | Tag | :material-check: | :material-check: | + +There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. + +## Hierarchical Rendering + +While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases. + +For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data: + +```json +{ + "ntp-servers": [ + "172.16.10.22", + "172.16.10.33" + ], + "syslog-servers": [ + "172.16.9.100", + "172.16.9.101" + ] +} +``` + +But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data: + +```json +{ + "syslog-servers": [ + "192.168.43.107" + ] +} +``` + +When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following: + +```json +{ + "ntp-servers": [ + "172.16.10.22", + "172.16.10.33" + ], + "syslog-servers": [ + "192.168.43.107" + ] +} +``` + +Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved. + +## Local Context Data + +Devices and virtual machines may also have a local context data defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object. + +!!! warning + If you find that you're routinely defining local context data for many individual devices or virtual machines, [custom fields](./customization.md#custom-fields) may offer a more effective solution. diff --git a/docs/features/customization.md b/docs/features/customization.md index d7f2cf40a..813914ae2 100644 --- a/docs/features/customization.md +++ b/docs/features/customization.md @@ -6,6 +6,18 @@ While NetBox strives to meet the needs of every network, the needs of users to c Most objects in NetBox can be assigned user-created tags to aid with organization and filtering. Tag values are completely arbitrary: They may be used to store data in key-value pairs, or they may be employed simply as labels against which objects can be filtered. Each tag can also be assigned a color for quicker differentiation in the user interface. +Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": + +```no-highlight +GET /api/dcim/devices/?tag=monitored +``` + +The `tag` filter can be specified multiple times to match only objects which have _all_ the specified tags assigned: + +```no-highlight +GET /api/dcim/devices/?tag=monitored&tag=deprecated +``` + ## Custom Fields While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs. diff --git a/docs/models/extras/configcontext.md b/docs/models/extras/configcontext.md index 08b5f4fd5..156b2d784 100644 --- a/docs/models/extras/configcontext.md +++ b/docs/models/extras/configcontext.md @@ -1,69 +1,27 @@ # Configuration Contexts -Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments: +Context data is made available to [devices](../dcim/device.md) and/or [virtual machines](../virtualization/virtualmachine.md) based on their relationships to other objects in NetBox. For example, context data can be associated only with devices assigned to a particular site, or only to virtual machines in a certain cluster. -* Region -* Site group -* Site -* Location (devices only) -* Device type (devices only) -* Role -* Platform -* Cluster type (VMs only) -* Cluster group (VMs only) -* Cluster (VMs only) -* Tenant group -* Tenant -* Tag +See the [context data documentation](../../features/context-data.md) for more information. -## Hierarchical Rendering +## Fields -Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object. +### Name -For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data: +A unique human-friendly name. -```json -{ - "ntp-servers": [ - "172.16.10.22", - "172.16.10.33" - ], - "syslog-servers": [ - "172.16.9.100", - "172.16.9.101" - ] -} -``` +### Weight -But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data: +A numeric value which influences the order in which context data is merged. Contexts with a lower weight are merged before those with a higher weight. -```json -{ - "syslog-servers": [ - "192.168.43.107" - ] -} -``` +### Data -When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following: +The context data expressed in JSON format. -```json -{ - "ntp-servers": [ - "172.16.10.22", - "172.16.10.33" - ], - "syslog-servers": [ - "192.168.43.107" - ] -} -``` +### Is Active -Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved. +If not selected, this config context will be excluded from rendering. This can be convenient to temporarily disable a config context. -## Local Context Data +### Object Assignment -Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object. - -!!! warning - If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution. +Each configuration context may be assigned with any number of objects of the supported types. If no related objects are selected, it will be considered a "global" config context and apply to all devices and virtual machines. diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md index 0b2bc29f9..ee1fde2b7 100644 --- a/docs/models/extras/customfield.md +++ b/docs/models/extras/customfield.md @@ -1,5 +1,7 @@ # Custom Fields +NetBox administrators can extend NetBox's built-in data model by adding custom fields to most object types. See the [custom fields documentation](../../customization/custom-fields.md) for more information. + ## Fields ### Model(s) diff --git a/docs/models/extras/customlink.md b/docs/models/extras/customlink.md index 458007ab1..dae9978aa 100644 --- a/docs/models/extras/customlink.md +++ b/docs/models/extras/customlink.md @@ -1,5 +1,7 @@ # Custom Links +Users can add custom links to object views in NetBox to reference external resources. For example, you might create a custom link for devices pointing to a monitoring system. See the [custom links documentation](../../customization/custom-links.md) for more information. + ## Fields ### Name diff --git a/docs/models/extras/exporttemplate.md b/docs/models/extras/exporttemplate.md index 347184324..3215201b3 100644 --- a/docs/models/extras/exporttemplate.md +++ b/docs/models/extras/exporttemplate.md @@ -1,5 +1,7 @@ # Export Templates +Export templates are used to render arbitrary data from a set of NetBox objects. For example, you might want to automatically generate a network monitoring service configuration from a list of device objects. See the [export templates documentation](../../customization/export-templates.md) for more information. + ## Fields ### Name diff --git a/docs/models/extras/imageattachment.md b/docs/models/extras/imageattachment.md index da15462ab..b8c48f055 100644 --- a/docs/models/extras/imageattachment.md +++ b/docs/models/extras/imageattachment.md @@ -1,3 +1,13 @@ # Image Attachments Certain objects in NetBox support the attachment of uploaded images. These will be saved to the NetBox server and made available whenever the object is viewed. + +## Fields + +### Name + +The name of the image being attached. If not defined, this will be inferred from the name of the uploaded file. + +### Image + +The image file to upload. Note that the uploaded file **must** be a supported image type, or validation will fail. diff --git a/docs/models/extras/tag.md b/docs/models/extras/tag.md index fe6a1ef36..97ebd9d72 100644 --- a/docs/models/extras/tag.md +++ b/docs/models/extras/tag.md @@ -2,16 +2,16 @@ Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects. -Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose. +## Fields -Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": +### Name -```no-highlight -GET /api/dcim/devices/?tag=monitored -``` +A unique human-friendly label for the tag. -The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned: +### Slug -```no-highlight -GET /api/dcim/devices/?tag=monitored&tag=deprecated -``` +A unique URL-friendly identifier. (This value will be used for filtering.) This is automatically generated from the tag's name, but can be altered as needed. + +### Color + +The color to use when displaying the tag in the NetBox UI. diff --git a/docs/models/extras/webhook.md b/docs/models/extras/webhook.md index 2d598f8ae..1ca6ec191 100644 --- a/docs/models/extras/webhook.md +++ b/docs/models/extras/webhook.md @@ -1,19 +1,84 @@ # Webhooks -A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks. +A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. -## Model Fields +See the [webhooks documentation](../../integrations/webhooks.md) for more information. -* **Name** - A unique name for the webhook. The name is not included with outbound messages. -* **Object type(s)** - The type or types of NetBox object that will trigger the webhook. -* **Enabled** - If unchecked, the webhook will be inactive. -* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected. -* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. -* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field. -* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`) -* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below). -* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.) -* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key. -* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object. -* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!) -* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional). +## Fields + +### Name + +A unique human-friendly name. + +### Content Types + +The type(s) of object in NetBox that will trigger the webhook. + +### Enabled + +If not selected, the webhook will be inactive. + +### Events + +The events which will trigger the webhook. At least one event type must be selected. + +| Name | Description | +|-----------|--------------------------------------| +| Creations | A new object has been created | +| Updates | An existing object has been modified | +| Deletions | An object has been deleted | + +### URL + +The URL to which the webhook HTTP request will be made. + +### HTTP Method + +The type of HTTP request to send. Options are: + +* `GET` +* `POST` +* `PUT` +* `PATCH` +* `DELETE` + +### HTTP Content Type + +The content type to indicate in the outgoing HTTP request header. See [this list](https://www.iana.org/assignments/media-types/media-types.xhtml) of known types for reference. + +### Additional Headers + +Any additional header to include with the outgoing HTTP request. These should be defined in the format `Name: Value`, with each header on a separate line. Jinja2 templating is supported for this field. + +### Body Template + +Jinja2 template for a custom request body, if desired. If not defined, NetBox will populate the request body with a raw dump of the webhook context. + +### Secret + +A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key. + +### SSL Verification + +Controls whether validation of the receiver's SSL certificate is enforced when HTTPS is used. + +!!! warning + Disabling this can expose your webhooks to man-in-the-middle attacks. + +### CA File Path + +The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (if not using the system defaults). + +## Context Data + +The following context variables are available in to the text and link templates. + +| Variable | Description | +|--------------|----------------------------------------------------| +| `event` | The event type (`create`, `update`, or `delete`) | +| `timestamp` | The time at which the event occured | +| `model` | The type of object impacted | +| `username` | The name of the user associated with the change | +| `request_id` | The unique request ID | +| `data` | A complete serialized representation of the object | +| `snapshots` | Pre- and post-change snapshots of the object | From 040feddcf1ee29c65c1a0515d23b3412cf89b217 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 16:19:34 -0400 Subject: [PATCH 226/245] Refreshed tenancy model documentation --- docs/features/contacts.md | 17 ++++++++++ docs/features/tenancy.md | 18 ++++++++++- docs/models/tenancy/contact.md | 48 +++++++++++++++-------------- docs/models/tenancy/contactgroup.md | 16 +++++++++- docs/models/tenancy/contactrole.md | 12 +++++++- docs/models/tenancy/tenant.md | 26 ++++++++-------- docs/models/tenancy/tenantgroup.md | 16 +++++++++- 7 files changed, 113 insertions(+), 40 deletions(-) diff --git a/docs/features/contacts.md b/docs/features/contacts.md index 6bbd217fc..40e8dd12c 100644 --- a/docs/features/contacts.md +++ b/docs/features/contacts.md @@ -26,3 +26,20 @@ A contact role defines the relationship of a contact to an assigned object. For A contact should represent an individual or permanent point of contact. Each contact must define a name, and may optionally include a title, phone number, email address, and related details. Contacts are reused for assignments, so each unique contact must be created only once and can be assigned to any number of NetBox objects, and there is no limit to the number of assigned contacts an object may have. Most core objects in NetBox can have contacts assigned to them. + +The following models support the assignment of contacts: + +* circuits.Circuit +* circuits.Provider +* dcim.Device +* dcim.Location +* dcim.Manufacturer +* dcim.PowerPanel +* dcim.Rack +* dcim.Region +* dcim.Site +* dcim.SiteGroup +* tenancy.Tenant +* virtualization.Cluster +* virtualization.ClusterGroup +* virtualization.VirtualMachine diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md index a278dc4c2..470905f20 100644 --- a/docs/features/tenancy.md +++ b/docs/features/tenancy.md @@ -13,10 +13,26 @@ click TenantGroup "../../models/tenancy/tenantgroup/" ## Tenant Groups -Tenants can be grouped by any logic that your use case demands, and groups can nested recursively for maximum flexibility. For example, You might define a parent "Customers" group with child groups "Current" and "Past" within it. A tenant can be assigned to a group at any level within the hierarchy. +Tenants can be grouped by any logic that your use case demands, and groups can be nested recursively for maximum flexibility. For example, You might define a parent "Customers" group with child groups "Current" and "Past" within it. A tenant can be assigned to a group at any level within the hierarchy. ## Tenants Typically, the tenant model is used to represent a customer or internal organization, however it can be used for whatever purpose meets your needs. Most core objects within NetBox can be assigned to particular tenant, so this model provides a very convenient way to correlate ownership across object types. For example, each of your customers might have its own racks, devices, IP addresses, circuits and so on: These can all be easily tracked via tenant assignment. + +The following objects can be assigned to tenants: + +* Sites +* Racks +* Rack reservations +* Devices +* VRFs +* Prefixes +* IP addresses +* VLANs +* Circuits +* Clusters +* Virtual machines + +Tenant assignment is used to signify the ownership of an object in NetBox. As such, each object may only be owned by a single tenant. For example, if you have a firewall dedicated to a particular customer, you would assign it to the tenant which represents that customer. However, if the firewall serves multiple customers, it doesn't *belong* to any particular customer, so tenant assignment would not be appropriate. diff --git a/docs/models/tenancy/contact.md b/docs/models/tenancy/contact.md index 9d81e2d85..eac630180 100644 --- a/docs/models/tenancy/contact.md +++ b/docs/models/tenancy/contact.md @@ -1,31 +1,33 @@ # Contacts -A contact represent an individual or group that has been associated with an object in NetBox for administrative reasons. For example, you might assign one or more operational contacts to each site. Contacts can be arranged within nested contact groups. +A contact represents an individual or group that has been associated with an object in NetBox for administrative reasons. For example, you might assign one or more operational contacts to each site. -Each contact must include a name, which is unique to its parent group (if any). The following optional descriptors are also available: +## Fields -* Title -* Phone -* Email -* Address +### Group -## Contact Assignment +The [contact group](./contactgroup.md) to which this contact is assigned (if any). -Each contact can be assigned to one or more objects, allowing for the efficient reuse of contact information. When assigning a contact to an object, the user may optionally specify a role and/or priority (primary, secondary, tertiary, or inactive) to better convey the nature of the contact's relationship to the assigned object. +### Name -The following models support the assignment of contacts: +The name of the contact. This may be an individual or a team/department. (This is the only required contact detail; all others are optional.) -* circuits.Circuit -* circuits.Provider -* dcim.Device -* dcim.Location -* dcim.Manufacturer -* dcim.PowerPanel -* dcim.Rack -* dcim.Region -* dcim.Site -* dcim.SiteGroup -* tenancy.Tenant -* virtualization.Cluster -* virtualization.ClusterGroup -* virtualization.VirtualMachine +### Title + +The contact's title or role. + +### Phone + +The contact's phone number. (Note that NetBox does _not_ enforce a particular numbering format.) + +### Email + +The contact's email address. + +### Address + +The contact's physical or mailing address. + +### Link + +A URL to reach the contact via some other means. diff --git a/docs/models/tenancy/contactgroup.md b/docs/models/tenancy/contactgroup.md index ea566c58a..49efb7c18 100644 --- a/docs/models/tenancy/contactgroup.md +++ b/docs/models/tenancy/contactgroup.md @@ -1,3 +1,17 @@ # Contact Groups -Contacts can be organized into arbitrary groups. These groups can be recursively nested for convenience. Each contact within a group must have a unique name, but other attributes can be repeated. +[Contacts](./contact.md) can be organized into arbitrary groups. These groups can be recursively nested for convenience. Each contact within a group must have a unique name, but other attributes can be repeated. + +## Fields + +### Parent + +The parent contact group (if any). + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/tenancy/contactrole.md b/docs/models/tenancy/contactrole.md index 23642ca03..bc8e1c802 100644 --- a/docs/models/tenancy/contactrole.md +++ b/docs/models/tenancy/contactrole.md @@ -1,3 +1,13 @@ # Contact Roles -Contacts can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for administrative, operational, or emergency contacts. +[Contacts](./contact.md) can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for administrative, operational, or emergency contacts. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/tenancy/tenant.md b/docs/models/tenancy/tenant.md index 60a160b9e..7df6992d1 100644 --- a/docs/models/tenancy/tenant.md +++ b/docs/models/tenancy/tenant.md @@ -1,17 +1,17 @@ # Tenants -A tenant represents a discrete grouping of resources used for administrative purposes. Typically, tenants are used to represent individual customers or internal departments within an organization. The following objects can be assigned to tenants: +A tenant represents a discrete grouping of resources used for administrative purposes. Typically, tenants are used to represent individual customers or internal departments within an organization. -* Sites -* Racks -* Rack reservations -* Devices -* VRFs -* Prefixes -* IP addresses -* VLANs -* Circuits -* Clusters -* Virtual machines +## Fields -Tenant assignment is used to signify the ownership of an object in NetBox. As such, each object may only be owned by a single tenant. For example, if you have a firewall dedicated to a particular customer, you would assign it to the tenant which represents that customer. However, if the firewall serves multiple customers, it doesn't *belong* to any particular customer, so tenant assignment would not be appropriate. +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Group + +The [tenant group](./tenantgroup.md) to which this tenant belongs (if any). diff --git a/docs/models/tenancy/tenantgroup.md b/docs/models/tenancy/tenantgroup.md index 078a71a72..f9929ff66 100644 --- a/docs/models/tenancy/tenantgroup.md +++ b/docs/models/tenancy/tenantgroup.md @@ -1,5 +1,19 @@ # Tenant Groups -Tenants can be organized by custom groups. For instance, you might create one group called "Customers" and one called "Departments." The assignment of a tenant to a group is optional. +[Tenants](./tenant.md) can be organized by custom groups. For instance, you might create one group called "Customers" and one called "Departments." The assignment of a tenant to a group is optional. Tenant groups may be nested recursively to achieve a multi-level hierarchy. For example, you might have a group called "Customers" containing subgroups of individual tenants grouped by product or account team. + +## Fields + +### Parent + +The parent tenant group (if any). + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) From d4f976ac8dd2cd39f4e41520c003f77a7eac6210 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Fri, 12 Aug 2022 16:37:47 -0400 Subject: [PATCH 227/245] Refreshed wireless model documentation --- docs/models/wireless/wirelesslan.md | 39 +++++++++++++++++---- docs/models/wireless/wirelesslangroup.md | 16 ++++++++- docs/models/wireless/wirelesslink.md | 43 +++++++++++++++++++++--- 3 files changed, 86 insertions(+), 12 deletions(-) diff --git a/docs/models/wireless/wirelesslan.md b/docs/models/wireless/wirelesslan.md index cb478664c..5bb3dbd65 100644 --- a/docs/models/wireless/wirelesslan.md +++ b/docs/models/wireless/wirelesslan.md @@ -1,11 +1,38 @@ # Wireless LANs -A wireless LAN is a set of interfaces connected via a common wireless channel. Each instance must have an SSID, and may optionally be correlated to a VLAN. Wireless LANs can be arranged into hierarchical groups, and each may be associated with a particular tenant. +A wireless LAN is a set of interfaces connected via a common wireless channel, identified by its SSID and authentication parameters. Wireless [interfaces](../dcim/interface.md) can be associated with wireless LANs to model multi-acess wireless segments. -An interface may be attached to multiple wireless LANs, provided they are all operating on the same channel. Only wireless interfaces may be attached to wireless LANs. +## Fields -Each wireless LAN may have authentication attributes associated with it, including: +### SSID -* Authentication type -* Cipher -* Pre-shared key +The service set identifier (SSID) for the wireless network. + +### Group + +The [wireless LAN group](./wirelesslangroup.md) to which this wireless LAN is assigned (if any). + +### VLAN + +Each wireless LAN can optionally be mapped to a [VLAN](../ipam/vlan.md), to model a bridge between wired and wireless segments. + +### Authentication Type + +The type of wireless authentication in use. Options include: + +* Open +* WEP +* WPA Personal (PSK) +* WPA Enterprise + +### Authentication Cipher + +The security cipher used to apply wireless authentication. Options include: + +* Auto (automatic) +* TKIP +* AES + +### Pre-Shared Key + +The security key configured on each client to grant access to the secured wireless LAN. This applies only to certain authentication types. diff --git a/docs/models/wireless/wirelesslangroup.md b/docs/models/wireless/wirelesslangroup.md index e477abd0b..37871f208 100644 --- a/docs/models/wireless/wirelesslangroup.md +++ b/docs/models/wireless/wirelesslangroup.md @@ -1,3 +1,17 @@ # Wireless LAN Groups -Wireless LAN groups can be used to organize and classify wireless LANs. These groups are hierarchical: groups can be nested within parent groups. However, each wireless LAN may assigned only to one group. +Wireless LAN groups can be used to organize and classify [wireless LANs](./wirelesslan.md). These groups are hierarchical: groups can be nested within parent groups. However, each wireless LAN may be assigned only to one group. + +## Fields + +### Parent + +The parent wireless LAN group (if any). + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/wireless/wirelesslink.md b/docs/models/wireless/wirelesslink.md index f52dc7191..c9b331570 100644 --- a/docs/models/wireless/wirelesslink.md +++ b/docs/models/wireless/wirelesslink.md @@ -1,9 +1,42 @@ # Wireless Links -A wireless link represents a connection between exactly two wireless interfaces. It may optionally be assigned an SSID and a description. It may also have a status assigned to it, similar to the cable model. Each wireless link may also be assigned to a particular tenant. +A wireless link represents a connection between exactly two wireless interfaces. Unlike a [wireless LAN](./wirelesslan.md), which permit an arbitrary number of client associations, wireless links are used to model point-to-point wireless connections. -Each wireless link may have authentication attributes associated with it, including: +## Fields -* Authentication type -* Cipher -* Pre-shared key +### Interfaces + +Select two interfaces: One for side A and one for side B. (Both must be wireless interfaces.) + +### Status + +The operational status of the link. Options include: + +* Connected +* Planned +* Decommissioning + +### SSID + +The service set identifier (SSID) for the wireless link (optional). + +### Authentication Type + +The type of wireless authentication in use. Options include: + +* Open +* WEP +* WPA Personal (PSK) +* WPA Enterprise + +### Authentication Cipher + +The security cipher used to apply wireless authentication. Options include: + +* Auto (automatic) +* TKIP +* AES + +### Pre-Shared Key + +The security key configured on each client to grant access to the secured wireless LAN. This applies only to certain authentication types. From f76ce172e04c1f8561d48416083e72f99a992c37 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 15 Aug 2022 11:57:38 -0400 Subject: [PATCH 228/245] Update model docs for device components --- docs/models/dcim/consoleport.md | 37 ++++- docs/models/dcim/consoleporttemplate.md | 4 +- docs/models/dcim/consoleserverport.md | 37 ++++- docs/models/dcim/consoleserverporttemplate.md | 4 +- docs/models/dcim/devicebay.md | 18 ++- docs/models/dcim/devicebaytemplate.md | 4 +- docs/models/dcim/frontport.md | 41 ++++- docs/models/dcim/frontporttemplate.md | 4 +- docs/models/dcim/interface.md | 140 +++++++++++++++--- docs/models/dcim/interfacetemplate.md | 4 +- docs/models/dcim/inventoryitem.md | 40 ++++- docs/models/dcim/inventoryitemtemplate.md | 2 +- docs/models/dcim/modulebay.md | 25 +++- docs/models/dcim/modulebaytemplate.md | 4 +- docs/models/dcim/poweroutlet.md | 38 ++++- docs/models/dcim/poweroutlettemplate.md | 4 +- docs/models/dcim/powerport.md | 40 ++++- docs/models/dcim/powerporttemplate.md | 4 +- docs/models/dcim/rearport.md | 38 ++++- docs/models/dcim/rearporttemplate.md | 4 +- 20 files changed, 432 insertions(+), 60 deletions(-) diff --git a/docs/models/dcim/consoleport.md b/docs/models/dcim/consoleport.md index 1a0782f25..e9cd09836 100644 --- a/docs/models/dcim/consoleport.md +++ b/docs/models/dcim/consoleport.md @@ -1,5 +1,36 @@ -## Console Ports +# Console Ports -A console port provides connectivity to the physical console of a device. These are typically used for temporary access by someone who is physically near the device, or for remote out-of-band access provided via a networked console server. Each console port may be assigned a physical type. +A console port provides connectivity to the physical console of a device. These are typically used for temporary access by someone who is physically near the device, or for remote out-of-band access provided via a networked console server. -Cables can connect console ports to console server ports or pass-through ports. +!!! tip + Like most device components, console ports are instantiated automatically from [console port templates](./consoleporttemplate.md) assigned to the selected device type when a device is created. + +## Fields + +### Device + +The device to which this console port belongs. + +### Module + +The installed module within the assigned device to which this console port belongs (optional). + +### Name + +The name of the console port. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the console port. + +### Type + +The type of console port. + +### Speed + +Operating speed, in bits per second (bps). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/consoleporttemplate.md b/docs/models/dcim/consoleporttemplate.md index 3462ff253..67d91de68 100644 --- a/docs/models/dcim/consoleporttemplate.md +++ b/docs/models/dcim/consoleporttemplate.md @@ -1,3 +1,3 @@ -## Console Port Templates +# Console Port Templates -A template for a console port that will be created on all instantiations of the parent device type. Each console port can be assigned a physical type. +A template for a console port that will be created on all instantiations of the parent device type. See the [console port](./consoleport.md) documentation for more detail. diff --git a/docs/models/dcim/consoleserverport.md b/docs/models/dcim/consoleserverport.md index da1ee8986..1fbb653a8 100644 --- a/docs/models/dcim/consoleserverport.md +++ b/docs/models/dcim/consoleserverport.md @@ -1,5 +1,36 @@ -## Console Server Ports +# Console Server Ports -A console server is a device which provides remote access to the local consoles of connected devices. They are typically used to provide remote out-of-band access to network devices. Each console server port may be assigned a physical type. +A console server is a device which provides remote access to the local consoles of connected devices. They are typically used to provide remote out-of-band access to network devices, and generally connect to [console ports](./consoleport.md). -Cables can connect console server ports to console ports or pass-through ports. +!!! tip + Like most device components, console server ports are instantiated automatically from [console server port templates](./consoleserverporttemplate.md) assigned to the selected device type when a device is created. + +## Fields + +### Device + +The device to which this console server port belongs. + +### Module + +The installed module within the assigned device to which this console server port belongs (optional). + +### Name + +The name of the console server port. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the console server port. + +### Type + +The type of console server port. + +### Speed + +Operating speed, in bits per second (bps). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. \ No newline at end of file diff --git a/docs/models/dcim/consoleserverporttemplate.md b/docs/models/dcim/consoleserverporttemplate.md index cc4e8bcd3..c599e738a 100644 --- a/docs/models/dcim/consoleserverporttemplate.md +++ b/docs/models/dcim/consoleserverporttemplate.md @@ -1,3 +1,3 @@ -## Console Server Port Templates +# Console Server Port Templates -A template for a console server port that will be created on all instantiations of the parent device type. Each console server port can be assigned a physical type. +A template for a console server port that will be created on all instantiations of the parent device type. See the [console server port](./consoleserverport.md) documentation for more detail. diff --git a/docs/models/dcim/devicebay.md b/docs/models/dcim/devicebay.md index e79c426dc..f4f807c4a 100644 --- a/docs/models/dcim/devicebay.md +++ b/docs/models/dcim/devicebay.md @@ -1,8 +1,22 @@ -## Device Bays +# Device Bays Device bays represent a space or slot within a parent device in which a child device may be installed. For example, a 2U parent chassis might house four individual blade servers. The chassis would appear in the rack elevation as a 2U device with four device bays, and each server within it would be defined as a 0U device installed in one of the device bays. Child devices do not appear within rack elevations or count as consuming rack units. Child devices are first-class Devices in their own right: That is, they are fully independent managed entities which don't share any control plane with the parent. Just like normal devices, child devices have their own platform (OS), role, tags, and components. LAG interfaces may not group interfaces belonging to different child devices. !!! note - Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as modules installed within module bays. + Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as [modules](./module.md) installed within [module bays](./modulebay.md). + +## Fields + +### Device + +The device to which this device bay belongs. + +### Name + +The device bay's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the device bay. diff --git a/docs/models/dcim/devicebaytemplate.md b/docs/models/dcim/devicebaytemplate.md index a4c50067a..060b799c0 100644 --- a/docs/models/dcim/devicebaytemplate.md +++ b/docs/models/dcim/devicebaytemplate.md @@ -1,3 +1,3 @@ -## Device Bay Templates +# Device Bay Templates -A template for a device bay that will be created on all instantiations of the parent device type. Device bays hold child devices, such as blade servers. +A template for a device bay that will be created on all instantiations of the parent device type. See the [device bay](./devicebay.md) documentation for more detail. diff --git a/docs/models/dcim/frontport.md b/docs/models/dcim/frontport.md index 6f12e8cbf..0b291c9ed 100644 --- a/docs/models/dcim/frontport.md +++ b/docs/models/dcim/frontport.md @@ -1,3 +1,40 @@ -## Front Ports +# Front Ports -Front ports are pass-through ports used to represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific rear port on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each. +Front ports are pass-through ports which represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific [rear port](./rearport.md) on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each. + +## Fields + +### Device + +The device to which this port belongs. + +### Module + +The installed module within the assigned device to which this port belongs (optional). + +### Name + +The port's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the port. + +### Type + +The port's termination type. + +### Rear Ports + +The rear port and position to which this front port maps. + +!!! tip + When creating multiple front ports using a patterned name (e.g. `Port [1-12]`), you may select the equivalent number of rear port-position mappings from the list. + +### Color + +The port's color (optional). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/frontporttemplate.md b/docs/models/dcim/frontporttemplate.md index 03de0eae4..09535e3b6 100644 --- a/docs/models/dcim/frontporttemplate.md +++ b/docs/models/dcim/frontporttemplate.md @@ -1,3 +1,3 @@ -## Front Port Templates +# Front Port Templates -A template for a front-facing pass-through port that will be created on all instantiations of the parent device type. Front ports may have a physical type assigned, and must be associated with a corresponding rear port and position. This association will be automatically replicated when the device type is instantiated. +A template for a front-facing pass-through port that will be created on all instantiations of the parent device type. See the [front port](./frontport.md) documentation for more detail. diff --git a/docs/models/dcim/interface.md b/docs/models/dcim/interface.md index 87a1411b9..b69f7c6b1 100644 --- a/docs/models/dcim/interface.md +++ b/docs/models/dcim/interface.md @@ -1,34 +1,138 @@ -## Interfaces +# Interfaces -Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. Each interface must be assigned a type, and may optionally be assigned a MAC address, MTU, and IEEE 802.1Q mode (tagged or access). Each interface can also be enabled or disabled, and optionally designated as management-only (for out-of-band management). Additionally, each interface may optionally be assigned to a VRF. +Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. IP addresses and VLANs can be assigned to interfaces. !!! note - Although devices and virtual machines both can have interfaces, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa. + Although both devices and virtual machines both can have interfaces assigned, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa. -### Interface Types +## Fields -Interfaces may be physical or virtual in nature, but only physical interfaces may be connected via cables. Cables can connect interfaces to pass-through ports, circuit terminations, or other interfaces. Virtual interfaces, such as 802.1Q-tagged subinterfaces, may be assigned to physical parent interfaces. +### Device -Physical interfaces may be arranged into a link aggregation group (LAG) and associated with a parent LAG (virtual) interface. LAG interfaces can be recursively nested to model bonding of trunk groups. Like all virtual interfaces, LAG interfaces cannot be connected physically. +The device to which this interface belongs. -### Power over Ethernet (PoE) +### Module + +The installed module within the assigned device to which this interface belongs (optional). + +### Name + +The name of the interface, as reported by the device's operating system. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the interface. + +### Type + +The type of interface. Interfaces may be physical or virtual in nature, but only physical interfaces may be connected via cables. !!! note - This feature was added in NetBox v3.3. + The interface type refers to the physical termination or port on the device. Interfaces which employ a removable optic or similar transceiver should be defined to represent the type of transceiver in use, irrespective of the physical termination to that transceiver. -Physical interfaces can be assigned a PoE mode to indicate PoE capability: power supplying equipment (PSE) or powered device (PD). Additionally, a PoE mode may be specified. This can be one of the listed IEEE 802.3 standards, or a passive setting (24 or 48 volts across two or four pairs). +### Speed -### Wireless Interfaces +The operating speed, in kilobits per second (kbps). -Wireless interfaces may additionally track the following attributes: +### Duplex -* **Role** - AP or station -* **Channel** - One of several standard wireless channels -* **Channel Frequency** - The transmit frequency -* **Channel Width** - Channel bandwidth +The operation duplex (full, half, or auto). -If a predefined channel is selected, the frequency and width attributes will be assigned automatically. If no channel is selected, these attributes may be defined manually. +### VRF -### IP Address Assignment +The [virtual routing and forwarding](../ipam/vrf.md) instance to which this interface is assigned. -IP addresses can be assigned to interfaces. VLANs can also be assigned to each interface as either tagged or untagged. (An interface may have only one untagged VLAN.) +### MAC Address + +The 48-bit MAC address (for Ethernet interfaces). + +### WWN + +The 64-bit world-wide name (for Fibre Channel interfaces). + +### MTU + +The interface's configured maximum transmissible unit (MTU). + +### Transmit Power + +The interface's configured output power, in dBm (for optical interfaces). + +### Enabled + +If not selected, this interface will be treated as disabled/inoperative. + +### Management Only + +Designates the interface as handling management traffic only (e.g. for out-of-band management connections). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. + +### Parent Interface + +Virtual interfaces can be bound to a physical parent interface. This is helpful for modeling virtual interfaces which employ encapsulation on a physical interface, such as an 802.1Q VLAN-tagged subinterface. + +### Bridged Interface + +Interfaces can be bridged to other interfaces on a device in two manners: symmetric or grouped. + +* **Symmetric:** For example, eth0 is bridged to eth1, and eth1 is bridged to eth0. This effects a point-to-point bridge between the two interfaces, which NetBox will follow when tracing cable paths. +* **Grouped:** Multiple interfaces are each bridged to a common virtual bridge interface, effecting a multiaccess bridged segment. NetBox cannot follow these relationships when tracing cable paths, because no forwarding information is available. + +### LAG Interface + +Physical interfaces may be arranged into link aggregation groups (LAGs, also known as "trunks") and associated with a parent LAG (virtual) interface. LAG interfaces can be recursively nested to model bonding of trunk groups. Like all virtual interfaces, LAG interfaces cannot be connected physically. + +### PoE Mode + +The power over Ethernet (PoE) mode for this interface. (This field must be left empty for interfaces which do not support PoE.) Choices include: + +* Powered device (PD) +* Power-supplying equipment (PSE) + +### PoE Type + +The classification of PoE transmission supported, for PoE-enabled interfaces. This can be one of the listed IEEE 802.3 standards, or a passive setting (24 or 48 volts across two or four pairs). + +### 802.1Q Mode + +For switched Ethernet interfaces, this identifies the 802.1Q encapsulation strategy in effect. Options include: + +* **Access:** All traffic is assigned to a single VLAN, with no tagging. +* **Tagged:** One untagged "native" VLAN is allowed, as well as any number of tagged VLANs. +* **Tagged (all):** Implies that all VLANs are carried by the interface. One untagged VLAN may be designated. + +This field must be left blank for routed interfaces which do employ 802.1Q encapsulation. + +### Untagged VLAN + +The "native" (untagged) VLAN for the interface. Valid only when one of the above 802.1Q mode is selected. + +### Tagged VLANs + +The tagged VLANs which are configured to be carried by this interface. Valid only for the "tagged" 802.1Q mode above. + +### Wireless Role + +Indicates the configured role for wireless interfaces (access point or station). + +### Wireless Channel + +The configured channel for wireless interfaces. + +!!! tip + Selecting one of the pre-defined wireless channels will automatically populate the channel frequency and width upon saving the interface. + +### Channel Frequency + +The configured operation frequency of a wireless interface, in MHz. This is typically inferred by the configured channel above, but may be set manually e.g. to identify a licensed channel not available for general use. + +### Channel Width + +The configured channel width of a wireless interface, in MHz. This is typically inferred by the configured channel above, but may be set manually e.g. to identify a licensed channel not available for general use. + +### Wireless LANs + +The [wireless LANs](../wireless/wirelesslan.md) for which this interface carries traffic. (Valid for wireless interfaces only.) diff --git a/docs/models/dcim/interfacetemplate.md b/docs/models/dcim/interfacetemplate.md index e11abcce4..898c4843f 100644 --- a/docs/models/dcim/interfacetemplate.md +++ b/docs/models/dcim/interfacetemplate.md @@ -1,3 +1,3 @@ -## Interface Templates +# Interface Templates -A template for a network interface that will be created on all instantiations of the parent device type. Each interface may be assigned a physical or virtual type, and may be designated as "management-only." Power over Ethernet (PoE) mode and type may also be assigned to interface templates. +A template for a network interface that will be created on all instantiations of the parent device type. See the [interface](./interface.md) documentation for more detail. diff --git a/docs/models/dcim/inventoryitem.md b/docs/models/dcim/inventoryitem.md index fbd3172bb..1c2e894ed 100644 --- a/docs/models/dcim/inventoryitem.md +++ b/docs/models/dcim/inventoryitem.md @@ -2,6 +2,42 @@ Inventory items represent hardware components installed within a device, such as a power supply or CPU or line card. They are intended to be used primarily for inventory purposes. -Each inventory item can be assigned a functional role, manufacturer, part ID, serial number, and asset tag (all optional). A boolean toggle is also provided to indicate whether each item was entered manually or discovered automatically (by some process outside NetBox). - Inventory items are hierarchical in nature, such that any individual item may be designated as the parent for other items. For example, an inventory item might be created to represent a line card which houses several SFP optics, each of which exists as a child item within the device. An inventory item may also be associated with a specific component within the same device. For example, you may wish to associate a transceiver with an interface. + +## Fields + +### Device + +The device in which the inventory item is installed. + +### Parent + +The parent inventory item to which this item is assigned (optional). + +### Name + +The inventory item's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the inventory item. + +### Role + +The functional [role](./inventoryitemrole.md) assigned to this inventory item. + +### Manufacturer + +The [manufacturer](./manufacturer.md) that produced the item. + +### Part ID + +The part identification or model number assigned by the manufacturer. + +### Serial Number + +The serial number assigned by the manufacturer. + +### Asset Tag + +A unique, locally-administered label used to identify hardware resources. diff --git a/docs/models/dcim/inventoryitemtemplate.md b/docs/models/dcim/inventoryitemtemplate.md index 3167ed4ab..02fde5995 100644 --- a/docs/models/dcim/inventoryitemtemplate.md +++ b/docs/models/dcim/inventoryitemtemplate.md @@ -1,3 +1,3 @@ # Inventory Item Templates -A template for an inventory item that will be automatically created when instantiating a new device. All attributes of this object will be copied to the new inventory item, including the associations with a parent item and assigned component, if any. +A template for an inventory item that will be automatically created when instantiating a new device. All attributes of this object will be copied to the new inventory item, including the associations with a parent item and assigned component, if any. See the [inventory item](./inventoryitem.md) documentation for more detail. diff --git a/docs/models/dcim/modulebay.md b/docs/models/dcim/modulebay.md index 6c6f94598..9291ff554 100644 --- a/docs/models/dcim/modulebay.md +++ b/docs/models/dcim/modulebay.md @@ -1,3 +1,24 @@ -## Module Bays +# Module Bays -Module bays represent a space or slot within a device in which a field-replaceable module may be installed. A common example is that of a chassis-based switch such as the Cisco Nexus 9000 or Juniper EX9200. Modules in turn hold additional components that become available to the parent device. +Module bays represent a space or slot within a device in which a field-replaceable [module](./module.md) may be installed. A common example is that of a chassis-based switch such as the Cisco Nexus 9000 or Juniper EX9200. Modules in turn hold additional components that become available to the parent device. + +!!! note + If you need to model child devices rather than modules, use a [device bay](./devicebay.md) instead. + +## Fields + +### Device + +The device to which this module bay belongs. + +### Name + +The module bay's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the module bay. + +### Position + +The numeric position in which this module bay is situated. For example, this would be the number assigned to a slot within a chassis-based switch. diff --git a/docs/models/dcim/modulebaytemplate.md b/docs/models/dcim/modulebaytemplate.md index 463789305..3d5845d2e 100644 --- a/docs/models/dcim/modulebaytemplate.md +++ b/docs/models/dcim/modulebaytemplate.md @@ -1,3 +1,3 @@ -## Module Bay Templates +# Module Bay Templates -A template for a module bay that will be created on all instantiations of the parent device type. Module bays hold installed modules that do not have an independent management plane, such as line cards. +A template for a module bay that will be created on all instantiations of the parent device type. See the [module bay](./modulebay.md) documentation for more detail. diff --git a/docs/models/dcim/poweroutlet.md b/docs/models/dcim/poweroutlet.md index e9ef307bd..f6ca2c143 100644 --- a/docs/models/dcim/poweroutlet.md +++ b/docs/models/dcim/poweroutlet.md @@ -1,7 +1,39 @@ -## Power Outlets +# Power Outlets -Power outlets represent the outlets on a power distribution unit (PDU) or other device that supply power to dependent devices. Each power port may be assigned a physical type, and may be associated with a specific feed leg (where three-phase power is used) and/or a specific upstream power port. This association can be used to model the distribution of power within a device. +Power outlets represent the outlets on a power distribution unit (PDU) or other device that supplies power to dependent devices. Each power port may be assigned a physical type, and may be associated with a specific feed leg (where three-phase power is used) and/or a specific upstream power port. This association can be used to model the distribution of power within a device. For example, imagine a PDU with one power port which draws from a three-phase feed and 48 power outlets arranged into three banks of 16 outlets each. Outlets 1-16 would be associated with leg A on the port, and outlets 17-32 and 33-48 would be associated with legs B and C, respectively. -Cables can connect power outlets only to downstream power ports. (Pass-through ports cannot be used to model power distribution.) +## Fields + +### Device + +The device to which this power outlet belongs. + +### Module + +The installed module within the assigned device to which this power outlet belongs (optional). + +### Name + +The name of the power outlet. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the power outlet. + +### Type + +The type of power outlet. + +### Power Port + +When modeling a device which redistributes power from an upstream supply, such as a power distribution unit (PDU), each power outlet should be mapped to the respective [power port](./powerport.md) on the device which supplies power. For example, a 24-outlet PDU may two power ports, each distributing power to 12 of its outlets. + +### Feed Leg + +This field is used to indicate to which leg of three-phase power circuit the outlet is bound. (This should be left blank for single-phase applications.) + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/poweroutlettemplate.md b/docs/models/dcim/poweroutlettemplate.md index 6f81891f1..0803ede97 100644 --- a/docs/models/dcim/poweroutlettemplate.md +++ b/docs/models/dcim/poweroutlettemplate.md @@ -1,3 +1,3 @@ -## Power Outlet Templates +# Power Outlet Templates -A template for a power outlet that will be created on all instantiations of the parent device type. Each power outlet can be assigned a physical type, and its power source may be mapped to a specific feed leg and power port template. This association will be automatically replicated when the device type is instantiated. +A template for a power outlet that will be created on all instantiations of the parent device type. See the [power outlet](./poweroutlet.md) documentation for more detail. diff --git a/docs/models/dcim/powerport.md b/docs/models/dcim/powerport.md index 1948920d0..cfe513fbd 100644 --- a/docs/models/dcim/powerport.md +++ b/docs/models/dcim/powerport.md @@ -1,8 +1,40 @@ -## Power Ports +# Power Ports -A power port represents the inlet of a device where it draws its power, i.e. the connection port(s) on a device's power supply. Each power port may be assigned a physical type, as well as allocated and maximum draw values (in watts). These values can be used to calculate the overall utilization of an upstream power feed. +A power port is a device component which draws power from some external source (e.g. an upstream [power outlet](./poweroutlet.md)), and generally represents a power supply internal to a device. + +## Fields + +### Device + +The device to which this power port belongs. + +### Module + +The installed module within the assigned device to which this power port belongs (optional). + +### Name + +The name of the power port. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the power port. + +### Type + +The type of power port. + +### Maximum Draw + +The maximum amount of power this port consumes (in watts). !!! info - When creating a power port on a device which supplies power to downstream devices, the allocated and maximum draw numbers should be left blank. Utilization will be calculated by taking the sum of all power ports of devices connected downstream. + When creating a power port on a device which is mapped to outlets and supplies power to downstream devices, the maximum and allocated draw numbers should be left blank. Utilization will be calculated by taking the sum of all power ports of devices connected downstream. -Cables can connect power ports only to power outlets or power feeds. (Pass-through ports cannot be used to model power distribution.) +### Allocated Draw + +The budgeted amount of power this port consumes (in watts). + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/powerporttemplate.md b/docs/models/dcim/powerporttemplate.md index 947f146ae..32579f4d5 100644 --- a/docs/models/dcim/powerporttemplate.md +++ b/docs/models/dcim/powerporttemplate.md @@ -1,3 +1,3 @@ -## Power Port Templates +# Power Port Templates -A template for a power port that will be created on all instantiations of the parent device type. Each power port can be assigned a physical type, as well as a maximum and allocated draw in watts. +A template for a power port that will be created on all instantiations of the parent device type. See the [power port](./powerport.md) documentation for more detail. diff --git a/docs/models/dcim/rearport.md b/docs/models/dcim/rearport.md index 41c5b3037..3d161f65d 100644 --- a/docs/models/dcim/rearport.md +++ b/docs/models/dcim/rearport.md @@ -1,6 +1,40 @@ -## Rear Ports +# Rear Ports -Like front ports, rear ports are pass-through ports which represent the continuation of a path from one cable to the next. Each rear port is defined with its physical type and a number of positions: Rear ports with more than one position can be mapped to multiple front ports. This can be useful for modeling instances where multiple paths share a common cable (for example, six discrete two-strand fiber connections sharing a 12-strand MPO cable). +Like [front ports](./frontport.md), rear ports are pass-through ports which represent the continuation of a path from one cable to the next. Each rear port is defined with its physical type and a number of positions: Rear ports with more than one position can be mapped to multiple front ports. This can be useful for modeling instances where multiple paths share a common cable (for example, six discrete two-strand fiber connections sharing a 12-strand MPO cable). !!! note Front and rear ports need not necessarily reside on the actual front or rear device face. This terminology is used primarily to distinguish between the two components in a pass-through port pairing. + +## Fields + +### Device + +The device to which this port belongs. + +### Module + +The installed module within the assigned device to which this port belongs (optional). + +### Name + +The port's name. Must be unique to the parent device. + +### Label + +An alternative physical label identifying the port. + +### Type + +The port's termination type. + +### Color + +The port's color (optional). + +### Positions + +The number of [front ports](./frontport.md) to which this rear port can be mapped. For example, an MPO fiber termination cassette might have a single 12-strand rear port mapped to 12 discrete front ports, each terminating a single fiber strand. (For rear ports which map directly to a single front port, set this to `1`.) + +### Mark Connected + +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/rearporttemplate.md b/docs/models/dcim/rearporttemplate.md index 01ba02ac0..00cdfa5d2 100644 --- a/docs/models/dcim/rearporttemplate.md +++ b/docs/models/dcim/rearporttemplate.md @@ -1,3 +1,3 @@ -## Rear Port Templates +# Rear Port Templates -A template for a rear-facing pass-through port that will be created on all instantiations of the parent device type. Each rear port may have a physical type and one or more front port templates assigned to it. The number of positions associated with a rear port determines how many front ports can be assigned to it (the maximum is 1024). +A template for a rear-facing pass-through port that will be created on all instantiations of the parent device type. See the [rear port](./rearport.md) documentation for more detail. From 4307f078edf8f94137b451150eeacf932d98f8b6 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 15 Aug 2022 15:16:02 -0400 Subject: [PATCH 229/245] Finish refreshing DCIM models documentation --- docs/models/dcim/cable.md | 36 +++++++++--- docs/models/dcim/consoleserverport.md | 2 +- docs/models/dcim/device.md | 82 ++++++++++++++++++++++++++- docs/models/dcim/devicebay.md | 3 + docs/models/dcim/devicerole.md | 18 ++++++ docs/models/dcim/devicetype.md | 44 +++++++++++--- docs/models/dcim/frontport.md | 3 + docs/models/dcim/interface.md | 3 + docs/models/dcim/inventoryitem.md | 3 + docs/models/dcim/inventoryitemrole.md | 14 +++++ docs/models/dcim/location.md | 27 ++++++++- docs/models/dcim/manufacturer.md | 12 +++- docs/models/dcim/module.md | 32 ++++++++++- docs/models/dcim/modulebay.md | 3 + docs/models/dcim/moduletype.md | 18 +++++- docs/models/dcim/platform.md | 28 ++++++++- docs/models/dcim/powerfeed.md | 58 +++++++++++++++---- docs/models/dcim/poweroutlet.md | 3 + docs/models/dcim/powerpanel.md | 18 +++++- docs/models/dcim/powerport.md | 3 + docs/models/dcim/rack.md | 63 +++++++++++++++++--- docs/models/dcim/rackreservation.md | 20 ++++++- docs/models/dcim/rackrole.md | 16 +++++- docs/models/dcim/rearport.md | 3 + docs/models/dcim/region.md | 16 +++++- docs/models/dcim/site.md | 52 ++++++++++++++--- docs/models/dcim/sitegroup.md | 16 +++++- docs/models/dcim/virtualchassis.md | 21 +++++-- 28 files changed, 547 insertions(+), 70 deletions(-) diff --git a/docs/models/dcim/cable.md b/docs/models/dcim/cable.md index 43c0abfab..20f6c03c7 100644 --- a/docs/models/dcim/cable.md +++ b/docs/models/dcim/cable.md @@ -1,24 +1,42 @@ # Cables -All connections between device components in NetBox are represented using cables. A cable represents a direct physical connection between two termination points, such as between a console port and a patch panel port, or between two network interfaces. +All connections between device components in NetBox are represented using cables. A cable represents a direct physical connection between two sets of endpoints (A and B), such as a console port and a patch panel port, or between two network interfaces. Cables may be connected to the following objects: -Each cable must have two endpoints defined. These endpoints are sometimes referenced as A and B for clarity, however cables are direction-agnostic and the order in which terminations are made has no meaning. Cables may be connected to the following objects: - -* Circuit terminations +* Network interfaces * Console ports * Console server ports -* Interfaces * Pass-through ports (front and rear) -* Power feeds -* Power outlets +* Circuit terminations * Power ports +* Power outlets +* Power feeds -Each cable may be assigned a type, label, length, and color. Each cable is also assigned one of three operational statuses: +## Fields + +### Status + +The cable's operational status. Choices include: * Active (default) * Planned * Decommissioning +### Type + +The cable's physical medium or classification. + +### Label + +An arbitrary label used to identify the cable. + +### Color + +The color of the cable. + +### Length + +The numeric length of the cable, including a unit designation (e.g. 100 meters or 25 feet). + ## Tracing Cables -A cable may be traced from either of its endpoints by clicking the "trace" button. (A REST API endpoint also provides this functionality.) NetBox will follow the path of connected cables from this termination across the directly connected cable to the far-end termination. If the cable connects to a pass-through port, and the peer port has another cable connected, NetBox will continue following the cable path until it encounters a non-pass-through or unconnected termination point. The entire path will be displayed to the user. +A cable may be traced from any of its endpoints by clicking the "trace" button. (A REST API endpoint also provides this functionality.) NetBox will follow the path of connected cables from this termination across the directly connected cable to the far-end termination. If the cable connects to a pass-through port, and the peer port has another cable connected, NetBox will continue following the cable path until it encounters a non-pass-through or unconnected termination point. The entire path will be displayed to the user. diff --git a/docs/models/dcim/consoleserverport.md b/docs/models/dcim/consoleserverport.md index 1fbb653a8..5c45451db 100644 --- a/docs/models/dcim/consoleserverport.md +++ b/docs/models/dcim/consoleserverport.md @@ -33,4 +33,4 @@ Operating speed, in bits per second (bps). ### Mark Connected -If selected, this component will be treated as if a cable has been connected. \ No newline at end of file +If selected, this component will be treated as if a cable has been connected. diff --git a/docs/models/dcim/device.md b/docs/models/dcim/device.md index a99078472..ddf1bfb09 100644 --- a/docs/models/dcim/device.md +++ b/docs/models/dcim/device.md @@ -8,8 +8,86 @@ A device is said to be full-depth if its installation on one rack face prevents Each device must be instantiated from a pre-created device type, and its default components (console ports, power ports, interfaces, etc.) will be created automatically. (The device type associated with a device may be changed after its creation, however its components will not be updated retroactively.) -Each device must be assigned a site, device role, and operational status, and may optionally be assigned to a specific location and/or rack within a site. A platform, serial number, and asset tag may optionally be assigned to each device. - Device names must be unique within a site, unless the device has been assigned to a tenant. Devices may also be unnamed. When a device has one or more interfaces with IP addresses assigned, a primary IP for the device can be designated, for both IPv4 and IPv6. + +## Fields + +### Name + +The device's configured name. This field is optional; devices can be unnamed. However, if set, the name must be unique to the assigned site and tenant. + +### Device Role + +The functional [role](./devicerole.md) assigned to this device. + +### Device Type + +The hardware [device type](./devicetype.md) which defines the device's make & model. Upon creating, all templated components assigned to the device type will be replicated on the new device. + +### Airflow + +The direction in which air circulates through the device chassis for cooling. + +### Serial Number + +The unique physical serial number assigned to this device by its manufacturer. + +### Asset Tag + +A unique, locally-administered label used to identify hardware resources. + +### Site + +The [site](./site.md) in which this device is located. + +### Location + +A specific [location](./location.md) where this device resides within the assigned site (optional). + +### Rack + +The [rack](./rack.md) within which this device is installed (optional). + +### Rack Face + +If installed in a rack, this field denotes the primary face on which the device is mounted. + +### Position + +If installed in a rack, this field indicates the base rack unit in which the device is mounted. + +!!! tip + Devices with a height of more than one rack unit should be set to the lowest-numbered rack unit that they occupy. + +### Status + +The device's operational status. + +!!! tip + Additional statuses may be defined by setting `Device.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Platform + +A device may be associated with a particular [platform](./platform.md) to indicate its operating system. Note that only platforms assigned to the associated manufacturer (or to no manufacturer) will be available for selection. + +### Cluster + +If this device will serve as a host for a virtualization [cluster](../virtualization/cluster.md), it can be assigned here. (Host devices can also be assigned by editing the cluster.) + +### Virtual Chassis + +The [virtual chassis](./virtualchassis.md) of which this device is a member, if any. + +### VC Position + +If assigned to a [virtual chassis](./virtualchassis.md), this field indicates the device's member position. + +### VC Priority + +If assigned to a [virtual chassis](./virtualchassis.md), this field indicates the device's priority for master election. + +### Local Config Context Data + +Any unique [context data](../../features/context-data.md) to be associated with the device. diff --git a/docs/models/dcim/devicebay.md b/docs/models/dcim/devicebay.md index f4f807c4a..5bbb125f8 100644 --- a/docs/models/dcim/devicebay.md +++ b/docs/models/dcim/devicebay.md @@ -7,6 +7,9 @@ Child devices are first-class Devices in their own right: That is, they are full !!! note Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as [modules](./module.md) installed within [module bays](./modulebay.md). +!!! tip + Like most device components, device bays are instantiated automatically from [device bay templates](./devicebaytemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/devicerole.md b/docs/models/dcim/devicerole.md index 13b8f021e..e9bdc0fa6 100644 --- a/docs/models/dcim/devicerole.md +++ b/docs/models/dcim/devicerole.md @@ -1,3 +1,21 @@ # Device Roles Devices can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for core switches, distribution switches, and access switches within your network. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Color + +The color used when displaying the role in the NetBox UI. + +### VM Role + +If selected, this role may be assigned to [virtual machines](../virtualization/virtualmachine.md) diff --git a/docs/models/dcim/devicetype.md b/docs/models/dcim/devicetype.md index cf42185f4..050f93244 100644 --- a/docs/models/dcim/devicetype.md +++ b/docs/models/dcim/devicetype.md @@ -4,13 +4,43 @@ A device type represents a particular make and model of hardware that exists in Device types are instantiated as devices installed within sites and/or equipment racks. For example, you might define a device type to represent a Juniper EX4300-48T network switch with 48 Ethernet interfaces. You can then create multiple _instances_ of this type named "switch1," "switch2," and so on. Each device will automatically inherit the components (such as interfaces) of its device type at the time of creation. However, changes made to a device type will **not** apply to instances of that device type retroactively. -Some devices house child devices which share physical resources, like space and power, but which function independently. A common example of this is blade server chassis. Each device type is designated as one of the following: - -* A parent device (which has device bays) -* A child device (which must be installed within a device bay) -* Neither - !!! note This parent/child relationship is **not** suitable for modeling chassis-based devices, wherein child members share a common control plane. Instead, line cards and similarly non-autonomous hardware should be modeled as modules or inventory items within a device. -A device type may optionally specify an airflow direction, such as front-to-rear, rear-to-front, or passive. Airflow direction may also be set separately per device. If it is not defined for a device at the time of its creation, it will inherit the airflow setting of its device type. +## Fields + +### Manufacturer + +The [manufacturer](./manufacturer.md) which produces this type of device. + +### Model + +The model number assigned to this device type by its manufacturer. Must be unique to the manufacturer. + +### Slug + +A unique URL-friendly representation of the model identifier. (This value can be used for filtering.) + +### Part Number + +An alternative part number to uniquely identify the device type. + +### Height + +The height of the physical device in rack units. (For device types that are not rack-mountable, this should be `0`.) + +### Is Full Depth + +If selected, this device type is considered to occupy both the front and rear faces of a rack, regardless of which face it is assigned. + +### Parent/Child Status + +Indicates whether this is a parent type (capable of housing child devices), a child type (which must be installed within a device bay), or neither. + +### Airflow + +The default direction in which airflow circulates within the device chassis. This may be configured differently for instantiated devices (e.g. because of different fan modules). + +### Front & Rear Images + +Users can upload illustrations of the device's front and rear panels. If present, these will be used to render the device in [rack](./rack.md) elevation diagrams. diff --git a/docs/models/dcim/frontport.md b/docs/models/dcim/frontport.md index 0b291c9ed..7ea617250 100644 --- a/docs/models/dcim/frontport.md +++ b/docs/models/dcim/frontport.md @@ -2,6 +2,9 @@ Front ports are pass-through ports which represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific [rear port](./rearport.md) on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each. +!!! tip + Like most device components, front ports are instantiated automatically from [front port templates](./frontporttemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/interface.md b/docs/models/dcim/interface.md index b69f7c6b1..42b570964 100644 --- a/docs/models/dcim/interface.md +++ b/docs/models/dcim/interface.md @@ -2,6 +2,9 @@ Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. IP addresses and VLANs can be assigned to interfaces. +!!! tip + Like most device components, interfaces are instantiated automatically from [interface templates](./interfacetemplate.md) assigned to the selected device type when a device is created. + !!! note Although both devices and virtual machines both can have interfaces assigned, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa. diff --git a/docs/models/dcim/inventoryitem.md b/docs/models/dcim/inventoryitem.md index 1c2e894ed..f61586eda 100644 --- a/docs/models/dcim/inventoryitem.md +++ b/docs/models/dcim/inventoryitem.md @@ -4,6 +4,9 @@ Inventory items represent hardware components installed within a device, such as Inventory items are hierarchical in nature, such that any individual item may be designated as the parent for other items. For example, an inventory item might be created to represent a line card which houses several SFP optics, each of which exists as a child item within the device. An inventory item may also be associated with a specific component within the same device. For example, you may wish to associate a transceiver with an interface. +!!! tip + Like most device components, inventory items can be instantiated automatically from [templates](./inventoryitemtemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/inventoryitemrole.md b/docs/models/dcim/inventoryitemrole.md index 8ed31481a..50eb61abd 100644 --- a/docs/models/dcim/inventoryitemrole.md +++ b/docs/models/dcim/inventoryitemrole.md @@ -1,3 +1,17 @@ # Inventory Item Roles Inventory items can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for power supplies, fans, interface optics, etc. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Color + +The color used when displaying the role in the NetBox UI. diff --git a/docs/models/dcim/location.md b/docs/models/dcim/location.md index fb72c218d..96ab13039 100644 --- a/docs/models/dcim/location.md +++ b/docs/models/dcim/location.md @@ -1,5 +1,28 @@ # Locations -Racks and devices can be grouped by location within a site. A location may represent a floor, room, cage, or similar organizational unit. Locations can be nested to form a hierarchy. For example, you may have floors within a site, and rooms within a floor. +[Racks](./rack.md) and [devices](./device.md) can be grouped by location within a [site](./site.md). A location may represent a floor, room, cage, or similar organizational unit. Locations can be nested to form a hierarchy. For example, you may have floors within a site, and rooms within a floor. -Each location must have a name that is unique within its parent site and location, if any, and must be assigned an operational status. (The set of available statuses is configurable.) +## Fields + +### Site + +The parent [site](./site.md) to which this location belongs. + +### Parent + +The parent location of which this location is a child (optional). + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Status + +The location's operational status. + +!!! tip + Additional statuses may be defined by setting `Location.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. diff --git a/docs/models/dcim/manufacturer.md b/docs/models/dcim/manufacturer.md index df227ee17..6beee5a90 100644 --- a/docs/models/dcim/manufacturer.md +++ b/docs/models/dcim/manufacturer.md @@ -1,3 +1,13 @@ # Manufacturers -A manufacturer represents the "make" of a device; e.g. Cisco or Dell. Each device type must be assigned to a manufacturer. (Inventory items and platforms may also be associated with manufacturers.) Each manufacturer must have a unique name and may have a description assigned to it. +A manufacturer represents the "make" of a device; e.g. Cisco or Dell. Each [device type](./devicetype.md) must be assigned to a manufacturer. ([Inventory items](./inventoryitem.md) and [platforms](./platform.md) may also be associated with manufacturers.) + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/dcim/module.md b/docs/models/dcim/module.md index bc9753ecc..c90430faa 100644 --- a/docs/models/dcim/module.md +++ b/docs/models/dcim/module.md @@ -2,4 +2,34 @@ A module is a field-replaceable hardware component installed within a device which houses its own child components. The most common example is a chassis-based router or switch. -Similar to devices, modules are instantiated from module types, and any components associated with the module type are automatically instantiated on the new model. Each module must be installed within a module bay on a device, and each module bay may have only one module installed in it. A module may optionally be assigned a serial number and asset tag. +Similar to devices, modules are instantiated from [module types](./moduletype.md), and any components associated with the module type are automatically instantiated on the new model. Each module must be installed within a [module bay](./modulebay.md) on a [device](./device.md), and each module bay may have only one module installed in it. + +## Fields + +### Device + +The parent [device](./device.md) into which the module is installed. + +### Module Bay + +The [module bay](./modulebay.md) into which the module is installed. + +### Module Type + +The [module type](./moduletype.md) which represents the physical make & model of hardware. By default, module components will be instantiated automatically from the module type when creating a new module. + +### Serial Number + +The unique physical serial number assigned to this module by its manufacturer. + +### Asset Tag + +A unique, locally-administered label used to identify hardware resources. + +### Replicate Components + +Controls whether templates module type components are automatically added when creating a new module. + +### Adopt Components + +Controls whether pre-existing components assigned to the device with the same names as components that would be created automatically will be assigned to the new module. diff --git a/docs/models/dcim/modulebay.md b/docs/models/dcim/modulebay.md index 9291ff554..c77909511 100644 --- a/docs/models/dcim/modulebay.md +++ b/docs/models/dcim/modulebay.md @@ -5,6 +5,9 @@ Module bays represent a space or slot within a device in which a field-replaceab !!! note If you need to model child devices rather than modules, use a [device bay](./devicebay.md) instead. +!!! tip + Like most device components, module bays are instantiated automatically from [module bay templates](./modulebaytemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/moduletype.md b/docs/models/dcim/moduletype.md index c1c8c5079..b8ec0ac6e 100644 --- a/docs/models/dcim/moduletype.md +++ b/docs/models/dcim/moduletype.md @@ -1,8 +1,8 @@ # Module Types -A module type represent a specific make and model of hardware component which is installable within a device and has its own child components. For example, consider a chassis-based switch or router with a number of field-replaceable line cards. Each line card has its own model number and includes a certain set of components such as interfaces. Each module type may have a manufacturer, model number, and part number assigned to it. +A module type represents a specific make and model of hardware component which is installable within a device's [module bay](./modulebay.md) and has its own child components. For example, consider a chassis-based switch or router with a number of field-replaceable line cards. Each line card has its own model number and includes a certain set of components such as interfaces. Each module type may have a manufacturer, model number, and part number assigned to it. -Similar to device types, each module type can have any of the following component templates associated with it: +Similar to [device types](./devicetype.md), each module type can have any of the following component templates associated with it: * Interfaces * Console ports @@ -21,3 +21,17 @@ When adding component templates to a module type, the string `{module}` can be u For example, you can create a module type with interface templates named `Gi{module}/0/[1-48]`. When a new module of this type is "installed" to a module bay with a position of "3", NetBox will automatically name these interfaces `Gi3/0/[1-48]`. Automatic renaming is supported for all modular component types (those listed above). + +## Fields + +### Manufacturer + +The [manufacturer](./manufacturer.md) which produces this type of module. + +### Model + +The model number assigned to this module type by its manufacturer. Must be unique to the manufacturer. + +### Part Number + +An alternative part number to uniquely identify the module type. diff --git a/docs/models/dcim/platform.md b/docs/models/dcim/platform.md index 347abc5b8..d080f74a4 100644 --- a/docs/models/dcim/platform.md +++ b/docs/models/dcim/platform.md @@ -1,9 +1,31 @@ # Platforms -A platform defines the type of software running on a device or virtual machine. This can be helpful to model when it is necessary to distinguish between different versions or feature sets. Note that two devices of the same type may be assigned different platforms: For example, one Juniper MX240 might run Junos 14 while another runs Junos 15. +A platform defines the type of software running on a [device](./device.md) or [virtual machine](../virtualization/virtualmachine.md). This can be helpful to model when it is necessary to distinguish between different versions or feature sets. Note that two devices of the same type may be assigned different platforms: For example, one Juniper MX240 might run Junos 14 while another runs Junos 15. -Platforms may optionally be limited by manufacturer: If a platform is assigned to a particular manufacturer, it can only be assigned to devices with a type belonging to that manufacturer. +Platforms may optionally be limited by [manufacturer](./manufacturer.md): If a platform is assigned to a particular manufacturer, it can only be assigned to devices with a type belonging to that manufacturer. -The platform model is also used to indicate which NAPALM driver (if any) and any associated arguments NetBox should use when connecting to a remote device. The name of the driver along with optional parameters are stored with the platform. +The platform model is also used to indicate which [NAPALM driver](../../integrations/napalm.md) (if any) and any associated arguments NetBox should use when connecting to a remote device. The name of the driver along with optional parameters are stored with the platform. The assignment of platforms to devices is an optional feature, and may be disregarded if not desired. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Manufacturer + +If designated, this platform will be available for use only to devices assigned to this [manufacturer](./manufacturer.md). This can be handy e.g. for limiting network operating systems to use on hardware produced by the relevant vendor. However, it should not be used when defining general-purpose software platforms. + +### NAPALM Driver + +The [NAPALM driver](https://napalm.readthedocs.io/en/latest/support/index.html) associated with this platform. + +### NAPALM Arguments + +Any additional arguments to send when invoking the NAPALM driver assigned to this platform. diff --git a/docs/models/dcim/powerfeed.md b/docs/models/dcim/powerfeed.md index bac7214f1..f98c758ff 100644 --- a/docs/models/dcim/powerfeed.md +++ b/docs/models/dcim/powerfeed.md @@ -1,21 +1,55 @@ # Power Feed -A power feed represents the distribution of power from a power panel to a particular device, typically a power distribution unit (PDU). The power port (inlet) on a device can be connected via a cable to a power feed. A power feed may optionally be assigned to a rack to allow more easily tracking the distribution of power among racks. +A power feed represents the distribution of power from a [power panel](./powerpanel.md) to a particular [device](./device.md), typically a power distribution unit (PDU). The [power port](./powerport.md) (inlet) on a device can be connected via a cable to a power feed. A power feed may optionally be assigned to a rack to allow more easily tracking the distribution of power among racks. -Each power feed is assigned an operational type (primary or redundant) and one of the following statuses: +## Fields -* Offline -* Active -* Planned -* Failed +### Power Panel -Each power feed also defines the electrical characteristics of the circuit which it represents. These include the following: +The [power panel](./powerpanel.md) which supplies upstream power to this feed. -* Supply type (AC or DC) -* Phase (single or three-phase) -* Voltage -* Amperage -* Maximum utilization (percentage) +### Rack + +The [rack](./rack.md) within which this feed delivers power (optional). + +### Name + +The feed's name or other identifier. Must be unique to the assigned power panel. + +### Status + +The feed's operational status. + +!!! tip + Additional statuses may be defined by setting `PowerFeed.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Type + +In redundant environments, each power feed can be designated as providing either primary or redundant power. (In environment with only one power source, all power feeds should be designated as primary.) + +### Mark Connected + +If selected, the power feed will be treated as if a cable has been connected. + +### Supply + +Electrical current type (AC or DC). + +### Voltage + +Operating circuit voltage, in volts. + +### Amperage + +Operation circuit amperage, in amperes. + +### Phase + +Indicates whether the circuit provides single- or three-phase power. + +### Max Utilization + +The maximum safe utilization of the feed, expressed as a percentage of the total available power. (Typically this will be set to around 80%, to avoid tripping a breaker during heaving spikes in current draw.) !!! info The power utilization of a rack is calculated when one or more power feeds are assigned to the rack and connected to devices that draw power. diff --git a/docs/models/dcim/poweroutlet.md b/docs/models/dcim/poweroutlet.md index f6ca2c143..5c8bd6ff0 100644 --- a/docs/models/dcim/poweroutlet.md +++ b/docs/models/dcim/poweroutlet.md @@ -4,6 +4,9 @@ Power outlets represent the outlets on a power distribution unit (PDU) or other For example, imagine a PDU with one power port which draws from a three-phase feed and 48 power outlets arranged into three banks of 16 outlets each. Outlets 1-16 would be associated with leg A on the port, and outlets 17-32 and 33-48 would be associated with legs B and C, respectively. +!!! tip + Like most device components, power outlets are instantiated automatically from [power outlet templates](./poweroutlettemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/powerpanel.md b/docs/models/dcim/powerpanel.md index 813321179..dd02a57f0 100644 --- a/docs/models/dcim/powerpanel.md +++ b/docs/models/dcim/powerpanel.md @@ -1,8 +1,20 @@ # Power Panel -A power panel represents the origin point in NetBox for electrical power being disseminated by one or more power feeds. In a data center environment, one power panel often serves a group of racks, with an individual power feed extending to each rack, though this is not always the case. It is common to have two sets of panels and feeds arranged in parallel to provide redundant power to each rack. - -Each power panel must be assigned to a site, and may optionally be assigned to a particular location within that site. +A power panel represents the origin point in NetBox for electrical power being disseminated by one or more [power feeds](./powerfeed.md). In a data center environment, one power panel often serves a group of racks, with an individual power feed extending to each rack, though this is not always the case. It is common to have two sets of panels and feeds arranged in parallel to provide redundant power to each rack. !!! note NetBox does not model the mechanism by which power is delivered to a power panel. Power panels define the root level of the power distribution hierarchy in NetBox. + +## Fields + +### Site + +The [site](./site.md) in which the power panel resides. + +### Location + +A specific [location](./location.md) within the assigned site where the power panel is installed. + +### Name + +The power panel's name. Must be unique to the assigned site. diff --git a/docs/models/dcim/powerport.md b/docs/models/dcim/powerport.md index cfe513fbd..7cc1dd60a 100644 --- a/docs/models/dcim/powerport.md +++ b/docs/models/dcim/powerport.md @@ -2,6 +2,9 @@ A power port is a device component which draws power from some external source (e.g. an upstream [power outlet](./poweroutlet.md)), and generally represents a power supply internal to a device. +!!! tip + Like most device components, power ports are instantiated automatically from [power port templates](./powerporttemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/rack.md b/docs/models/dcim/rack.md index 9465a828c..57e7bec98 100644 --- a/docs/models/dcim/rack.md +++ b/docs/models/dcim/rack.md @@ -1,12 +1,51 @@ # Racks -The rack model represents a physical two- or four-post equipment rack in which devices can be installed. Each rack must be assigned to a site, and may optionally be assigned to a location and/or tenant. Racks can also be organized by user-defined functional roles. The name and facility ID of each rack within a location must be unique. +The rack model represents a physical two- or four-post equipment rack in which [devices](./device.md) can be installed. Each rack must be assigned to a [site](./site.md), and may optionally be assigned to a [location](./location.md) within that site. Racks can also be organized by user-defined functional roles. The name and facility ID of each rack within a location must be unique. Rack height is measured in *rack units* (U); racks are commonly between 42U and 48U tall, but NetBox allows you to define racks of arbitrary height. A toggle is provided to indicate whether rack units are in ascending (from the ground up) or descending order. Each rack is assigned a name and (optionally) a separate facility ID. This is helpful when leasing space in a data center your organization does not own: The facility will often assign a seemingly arbitrary ID to a rack (for example, "M204.313") whereas internally you refer to is simply as "R113." A unique serial number and asset tag may also be associated with each rack. -A rack must be designated as one of the following types: +## Fields + +### Site + +The [site](./site.md) to which the rack is assigned. + +### Location + +The [location](./location.md) within a site where the rack has been installed (optional). + +### Name + +The rack's name or identifier. Must be unique to the rack's location, if assigned. + +### Status + +Operational status. + +!!! tip + Additional statuses may be defined by setting `Rack.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Role + +The functional [role](./rackrole.md) fulfilled by the rack. + +### Facility ID + +An alternative identifier assigned to the rack e.g. by the facility operator. This is helpful for tracking datacenter rack designations in a colocation facility. + +### Serial Number + +The unique physical serial number assigned to this rack. + +### Asset Tag + +A unique, locally-administered label used to identify hardware resources. + +### Type + +A rack can be designated as one of the following types: * 2-post frame * 4-post frame @@ -14,12 +53,18 @@ A rack must be designated as one of the following types: * Wall-mounted frame * Wall-mounted cabinet -Similarly, each rack must be assigned an operational status, which is one of the following: +### Width -* Reserved -* Available -* Planned -* Active -* Deprecated +The canonical distance between the two vertical rails on a face. (This is typically 19 inches, however other standard widths exist.) -Each rack has two faces (front and rear) on which devices can be mounted. Rail-to-rail width may be 10, 19, 21, or 23 inches. The outer width and depth of a rack or cabinet can also be annotated in millimeters or inches. +### Height + +The height of the rack, measured in units. + +### Outer Dimensions + +The external width and depth of the rack can be tracked to aid in floorplan calculations. These measurements must be designated in either millimeters or inches. + +### Descending Units + +If selected, the rack's elevation will display unit 1 at the top of the rack. (Most racks use asceneding numbering, with unit 1 assigned to the bottommost position.) diff --git a/docs/models/dcim/rackreservation.md b/docs/models/dcim/rackreservation.md index 0ed9651a0..32d52c9d7 100644 --- a/docs/models/dcim/rackreservation.md +++ b/docs/models/dcim/rackreservation.md @@ -1,3 +1,21 @@ # Rack Reservations -Users can reserve specific units within a rack for future use. An arbitrary set of units within a rack can be associated with a single reservation, but reservations cannot span multiple racks. A description is required for each reservation, reservations may optionally be associated with a specific tenant. +Users can reserve specific units within a [rack](./rackreservation.md) for future use. An arbitrary set of units within a rack can be associated with a single reservation, but reservations cannot span multiple racks. A description is required for each reservation, reservations may optionally be associated with a specific tenant. + +## Fields + +### Rack + +The [rack](./rack.md) being reserved. + +### Units + +The rack unit or units being reserved. Multiple units can be expressed using commas and/or hyphens. For example, `1,3,5-7` specifies units 1, 3, 5, 6, and 7. + +### User + +The NetBox user account associated with the reservation. Note that users with sufficient permission can make rack reservations for other users. + +### Description + +Every rack reservation must include a description of its purpose. diff --git a/docs/models/dcim/rackrole.md b/docs/models/dcim/rackrole.md index 1375ce692..88f171af8 100644 --- a/docs/models/dcim/rackrole.md +++ b/docs/models/dcim/rackrole.md @@ -1,3 +1,17 @@ # Rack Roles -Each rack can optionally be assigned a user-defined functional role. For example, you might designate a rack for compute or storage resources, or to house colocated customer devices. Rack roles are fully customizable and may be color-coded. +Each rack can optionally be assigned a user-defined functional role. For example, you might designate a rack for compute or storage resources, or to house colocated customer devices. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Color + +The color used when displaying the role in the NetBox UI. diff --git a/docs/models/dcim/rearport.md b/docs/models/dcim/rearport.md index 3d161f65d..b23d4a29b 100644 --- a/docs/models/dcim/rearport.md +++ b/docs/models/dcim/rearport.md @@ -5,6 +5,9 @@ Like [front ports](./frontport.md), rear ports are pass-through ports which repr !!! note Front and rear ports need not necessarily reside on the actual front or rear device face. This terminology is used primarily to distinguish between the two components in a pass-through port pairing. +!!! tip + Like most device components, rear ports are instantiated automatically from [rear port templates](./rearporttemplate.md) assigned to the selected device type when a device is created. + ## Fields ### Device diff --git a/docs/models/dcim/region.md b/docs/models/dcim/region.md index bac186264..27673b2df 100644 --- a/docs/models/dcim/region.md +++ b/docs/models/dcim/region.md @@ -1,5 +1,17 @@ # Regions -Sites can be arranged geographically using regions. A region might represent a continent, country, city, campus, or other area depending on your use case. Regions can be nested recursively to construct a hierarchy. For example, you might define several country regions, and within each of those several state or city regions to which sites are assigned. +[Sites](./site.md) can be arranged geographically using regions. A region might represent a continent, country, city, campus, or other area depending on your use case. Regions can be nested recursively to construct a hierarchy. For example, you might define several country regions, and within each of those several state or city regions to which sites are assigned. -Each region must have a name that is unique within its parent region, if any. +## Fields + +### Parent + +The parent region, if any. + +### Name + +The region's name. Must be unique to the parent region, if one is assigned. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/dcim/site.md b/docs/models/dcim/site.md index 6617b950c..c74c209e1 100644 --- a/docs/models/dcim/site.md +++ b/docs/models/dcim/site.md @@ -2,14 +2,50 @@ How you choose to employ sites when modeling your network may vary depending on the nature of your organization, but generally a site will equate to a building or campus. For example, a chain of banks might create a site to represent each of its branches, a site for its corporate headquarters, and two additional sites for its presence in two colocation facilities. -Each site must be assigned a unique name and may optionally be assigned to a region and/or tenant. The following operational statuses are available: +## Fields -* Planned -* Staging -* Active -* Decommissioning -* Retired +### Name -The site model also provides a facility ID field which can be used to annotate a facility ID (such as a datacenter name) associated with the site. Each site may also have an autonomous system (AS) number and time zone associated with it. (Time zones are provided by the [pytz](https://pypi.org/project/pytz/) package.) +The site's unique name. -The site model also includes several fields for storing contact and address information as well as geolocation data (GPS coordinates). +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Status + +The site's operational status. + +!!! tip + Additional statuses may be defined by setting `Site.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Region + +The parent [region](./region.md) to which the site belongs, if any. + +### Facility + +Data center or facility designation for identifying the site. + +### ASNs + +Each site can have multiple [AS numbers](../ipam/asn.md) assigned to it. + +### Time Zone + +The site's local time zone. (Time zones are provided by the [pytz](https://pypi.org/project/pytz/) package.) + +### Physical Address + +The site's physical address, used for mapping. + +### Shipping Address + +The address to use for deliveries destined for the site. + +!!! tip + You can also designate [points of contact](../../features/contacts.md) for each site to provide additional contact details. + +### Latitude & Longitude + +GPS coordinates of the site for geolocation. diff --git a/docs/models/dcim/sitegroup.md b/docs/models/dcim/sitegroup.md index 04ebcc1a5..e1c5215d9 100644 --- a/docs/models/dcim/sitegroup.md +++ b/docs/models/dcim/sitegroup.md @@ -1,5 +1,17 @@ # Site Groups -Like regions, site groups can be used to organize sites. Whereas regions are intended to provide geographic organization, site groups can be used to classify sites by role or function. Also like regions, site groups can be nested to form a hierarchy. Sites which belong to a child group are also considered to be members of any of its parent groups. +Like [regions](./region.md), site groups can be used to organize [sites](./site.md). Whereas regions are intended to provide geographic organization, site groups can be used to classify sites by role or function. Also like regions, site groups can be nested to form a hierarchy. Sites which belong to a child group are also considered to be members of all its parent groups. -Each site group must have a name that is unique within its parent group, if any. +## Fields + +### Parent + +The parent site group, if any. + +### Name + +The site group's name. Must be unique to the parent group, if one is assigned. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/dcim/virtualchassis.md b/docs/models/dcim/virtualchassis.md index 2466b065d..e68b2fda6 100644 --- a/docs/models/dcim/virtualchassis.md +++ b/docs/models/dcim/virtualchassis.md @@ -1,9 +1,22 @@ # Virtual Chassis -A virtual chassis represents a set of devices which share a common control plane. A common example of this is a stack of switches which are connected and configured to operate as a single device. A virtual chassis must be assigned a name and may be assigned a domain. +A virtual chassis represents a set of devices which share a common control plane. A common example of this is a stack of switches which are connected and configured to operate as a single managed device. Each device in the virtual chassis is referred to as a VC member, and assigned a position and (optionally) a priority. VC member devices commonly reside within the same rack, though this is not a requirement. -Each device in the virtual chassis is referred to as a VC member, and assigned a position and (optionally) a priority. VC member devices commonly reside within the same rack, though this is not a requirement. One of the devices may be designated as the VC master: This device will typically be assigned a name, services, virtual interfaces, and other attributes related to managing the VC. -If a VC master is defined, interfaces from all VC members are displayed when navigating to its device interfaces view. This does not include other members interfaces declared as management-only. +One of the member devices may be designated as the VC master: This device will typically be assigned a name, services, virtual interfaces, and other attributes related to managing the VC. If a VC master is defined, interfaces from all VC members are displayed when navigating to its device interfaces view. This does not include management-only interfaces belonging to other members. !!! note - It's important to recognize the distinction between a virtual chassis and a chassis-based device. A virtual chassis is **not** suitable for modeling a chassis-based switch with removable line cards (such as the Juniper EX9208), as its line cards are _not_ physically autonomous devices. + It's important to recognize the distinction between a virtual chassis and a chassis-based device. A virtual chassis is **not** suitable for modeling a chassis-based switch with removable line cards (such as the Juniper EX9208), as its line cards are _not_ physically autonomous devices. Instead, use [modules](./module.md) for these. + +## Fields + +### Name + +The virtual chassis' name. + +### Domain + +The domain assigned for VC member devices. + +### Master + +The member device which has been designated as the chassis master (optional). From d43c98d546aa5f650db520b1bf7ce0f8f0446197 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 16 Aug 2022 15:32:00 -0400 Subject: [PATCH 230/245] Update IPAM models documentation --- docs/models/ipam/aggregate.md | 20 ++++++-- docs/models/ipam/asn.md | 20 +++++--- docs/models/ipam/fhrpgroup.md | 33 +++++++++--- docs/models/ipam/fhrpgroupassignment.md | 16 +++++- docs/models/ipam/ipaddress.md | 68 ++++++++++++++++--------- docs/models/ipam/iprange.md | 28 +++++++--- docs/models/ipam/l2vpn.md | 28 ++++++++-- docs/models/ipam/l2vpntermination.md | 17 ++++--- docs/models/ipam/prefix.md | 45 ++++++++++++---- docs/models/ipam/rir.md | 16 +++++- docs/models/ipam/role.md | 14 +++++ docs/models/ipam/routetarget.md | 6 ++- docs/models/ipam/service.md | 22 +++++++- docs/models/ipam/servicetemplate.md | 16 +++++- docs/models/ipam/vlan.md | 29 ++++++++--- docs/models/ipam/vlangroup.md | 20 +++++++- docs/models/ipam/vrf.md | 22 ++++++-- 17 files changed, 331 insertions(+), 89 deletions(-) diff --git a/docs/models/ipam/aggregate.md b/docs/models/ipam/aggregate.md index ff5a50a39..eadeb813c 100644 --- a/docs/models/ipam/aggregate.md +++ b/docs/models/ipam/aggregate.md @@ -20,9 +20,23 @@ NetBox allows us to specify the portions of IP space that are interesting to us * 192.168.0.0/16 (RFC 1918) * One or more /48s within fd00::/8 (IPv6 unique local addressing) -Each aggregate is assigned to a RIR. For "public" aggregates, this will be the real-world authority which has granted your organization permission to use the specified IP space on the public Internet. For "private" aggregates, this will be a statutory authority, such as RFC 1918. Each aggregate can also annotate that date on which it was allocated, where applicable. +Each aggregate is assigned to a [RIR](./rir.md). For "public" aggregates, this will be the real-world authority which has granted your organization permission to use the specified IP space on the public Internet. For "private" aggregates, this will be a statutory authority, such as RFC 1918. Each aggregate can also annotate that date on which it was allocated, where applicable. -Prefixes are automatically arranged beneath their parent aggregates in NetBox. Typically you'll want to create aggregates only for the prefixes and IP addresses that your organization actually manages: There is no need to define aggregates for provider-assigned space which is only used on Internet circuits, for example. +Prefixes are automatically arranged beneath their parent aggregates in NetBox. Typically, you'll want to create aggregates only for the prefixes and IP addresses that your organization actually manages: There is no need to define aggregates for provider-assigned space which is only used on Internet circuits, for example. !!! note - Because aggregates represent swaths of the global IP space, they cannot overlap with one another: They can only exist side-by-side. For instance, you cannot define both 10.0.0.0/8 and 10.16.0.0/16 as aggregates, because they overlap. 10.16.0.0/16 in this example would be created as a container prefix and automatically grouped under the 10.0.0.0/8 aggregate. Remember, the purpose of aggregates is to establish the root of your IP addressing hierarchy. + Because aggregates represent segments of the global IP space, they cannot overlap with one another: They can only exist side-by-side. For instance, you cannot define both 10.0.0.0/8 and 10.16.0.0/16 as aggregates, because they overlap. 10.16.0.0/16 in this example would be created as a container prefix and automatically grouped under the 10.0.0.0/8 aggregate. Remember, the purpose of aggregates is to establish the root of your IP addressing hierarchy. + +## Fields + +### Prefix + +The IPv4 or IPv6 network this aggregate represents. + +### RIR + +The [Regional Internet Registry](./rir.md) or similar authority which governs allocations of this address space from the global pool. + +### Date Added + +The date on which the address space was allocated or deployed. diff --git a/docs/models/ipam/asn.md b/docs/models/ipam/asn.md index cfef1da29..e34790406 100644 --- a/docs/models/ipam/asn.md +++ b/docs/models/ipam/asn.md @@ -1,15 +1,19 @@ # ASN -ASN is short for Autonomous System Number. This identifier is used in the BGP protocol to identify which "autonomous system" a particular prefix is originating and transiting through. +An Autonomous System Number (ASN) is a numeric identifier used in the BGP protocol to identify which [autonomous system](https://en.wikipedia.org/wiki/Autonomous_system_%28Internet%29) a particular prefix is originating and transiting through. NetBox support both 32- and 64- ASNs. -The AS number model within NetBox allows you to model some of this real-world relationship. +ASNs must be globally unique within NetBox, must each may be assigned to multiple [sites](../dcim/site.md). -Within NetBox: +## Fields -* AS numbers are globally unique -* Each AS number must be associated with a RIR (ARIN, RFC 6996, etc) -* Each AS number can be associated with many different sites -* Each site can have many different AS numbers -* Each AS number can be assigned to a single tenant +### AS Number +The 32- or 64-bit AS number. +### RIR + +The [Regional Internet Registry](./rir.md) or similar authority responsible for the allocation of this particular ASN. + +### Sites + +The [site(s)](../dcim/site.md) to which this ASN is assigned. diff --git a/docs/models/ipam/fhrpgroup.md b/docs/models/ipam/fhrpgroup.md index c5baccd7b..4da390310 100644 --- a/docs/models/ipam/fhrpgroup.md +++ b/docs/models/ipam/fhrpgroup.md @@ -1,10 +1,31 @@ # FHRP Group -A first-hop redundancy protocol (FHRP) enables multiple physical interfaces to present a virtual IP address in a redundant manner. Example of such protocols include: +A first-hop redundancy protocol (FHRP) enables multiple physical interfaces to present a virtual [IP address](./ipaddress.md) (VIP) in a redundant manner. Examples of such protocols include: -* Hot Standby Router Protocol (HSRP) -* Virtual Router Redundancy Protocol (VRRP) -* Common Address Redundancy Protocol (CARP) -* Gateway Load Balancing Protocol (GLBP) +* [Hot Standby Router Protocol](https://en.wikipedia.org/wiki/Hot_Standby_Router_Protocol) (HSRP) +* [Virtual Router Redundancy Protocol](https://en.wikipedia.org/wiki/Virtual_Router_Redundancy_Protocol) (VRRP) +* [Common Address Redundancy Protocol](https://en.wikipedia.org/wiki/Common_Address_Redundancy_Protocol) (CARP) +* [Gateway Load Balancing Protocol](https://en.wikipedia.org/wiki/Gateway_Load_Balancing_Protocol) (GLBP) -NetBox models these redundancy groups by protocol and group ID. Each group may optionally be assigned an authentication type and key. (Note that the authentication key is stored as a plaintext value in NetBox.) Each group may be assigned or more virtual IPv4 and/or IPv6 addresses. +When creating a new FHRP group, the user may optionally create a VIP as well. This IP address will be automatically assigned to the new group. (Virtual IP addresses can also be assigned after the group has been created.) + +## Fields + +### Protocol + +The wire protocol employed by cooperating servers to maintain the virtual [IP address(es)](./ipaddress.md) for the group. + +### Group ID + +The group's numeric identifier. + +### Authentication Type + +The type of authentication employed by group nodes, if any. + +### Authentication Key + +The shared key used for group authentication, if any. + +!!! warning + The authentication key value is stored in plaintext in NetBox's database. Do not utilize this field if you require encryption at rest for shared keys. diff --git a/docs/models/ipam/fhrpgroupassignment.md b/docs/models/ipam/fhrpgroupassignment.md index c3e0bf200..c65217c62 100644 --- a/docs/models/ipam/fhrpgroupassignment.md +++ b/docs/models/ipam/fhrpgroupassignment.md @@ -1,5 +1,19 @@ # FHRP Group Assignments -Member device and VM interfaces can be assigned to FHRP groups, along with a numeric priority value. For instance, three interfaces, each belonging to a different router, may each be assigned to the same FHRP group to serve a common virtual IP address. Each of these assignments would typically receive a different priority. +Member device and VM interfaces can be assigned to [FHRP groups](./fhrpgroup.md) to indicate their participation in maintaining a common virtual IP address (VIP). For instance, three interfaces, each belonging to a different router, may each be assigned to the same FHRP group to serve a shared VIP. Each of these assignments would typically receive a different priority. Interfaces are assigned to FHRP groups under the interface detail view. + +## Fields + +### Group + +The [FHRP group](./fhrpgroup.md) being assigned. + +### Interface + +The device or VM interface to which the group is being assigned. + +### Priority + +A value between 0 and 255 indicating the interface's priority for being elected as the master/primary node in the group. diff --git a/docs/models/ipam/ipaddress.md b/docs/models/ipam/ipaddress.md index 1ea613997..ecfdc4b96 100644 --- a/docs/models/ipam/ipaddress.md +++ b/docs/models/ipam/ipaddress.md @@ -1,30 +1,8 @@ # IP Addresses -An IP address comprises a single host address (either IPv4 or IPv6) and its subnet mask. Its mask should match exactly how the IP address is configured on an interface in the real world. +An IP address object in NetBox comprises a single host address (either IPv4 or IPv6) and its subnet mask, and represents an IP address as configured on a network interface. IP addresses can be assigned to [device](../dcim/device.md) and [virtual machine](../virtualization/virtualmachine.md) interfaces, as well as to [FHRP groups](./fhrpgroup.md). Further, each device and virtual machine may have one of its interface IPs designated as its primary IP per address family (one for IPv4 and one for IPv6). -Like a prefix, an IP address can optionally be assigned to a VRF (otherwise, it will appear in the "global" table). IP addresses are automatically arranged under parent prefixes within their respective VRFs according to the IP hierarchy. - -Each IP address can also be assigned an operational status and a functional role. Statuses are hard-coded in NetBox and include the following: - -* Active -* Reserved -* Deprecated -* DHCP -* SLAAC (IPv6 Stateless Address Autoconfiguration) - -Roles are used to indicate some special attribute of an IP address; for example, use as a loopback or as the the virtual IP for a VRRP group. (Note that functional roles are conceptual in nature, and thus cannot be customized by the user.) Available roles include: - -* Loopback -* Secondary -* Anycast -* VIP -* VRRP -* HSRP -* GLBP - -An IP address can be assigned to any device or virtual machine interface, and an interface may have multiple IP addresses assigned to it. Further, each device and virtual machine may have one of its interface IPs designated as its primary IP per address family (one for IPv4 and one for IPv6). - -!!! note +!!! tip When primary IPs are set for both IPv4 and IPv6, NetBox will prefer IPv6. This can be changed by setting the `PREFER_IPV4` configuration parameter. ## Network Address Translation (NAT) @@ -32,4 +10,44 @@ An IP address can be assigned to any device or virtual machine interface, and an An IP address can be designated as the network address translation (NAT) inside IP address for exactly one other IP address. This is useful primarily to denote a translation between public and private IP addresses. This relationship is followed in both directions: For example, if 10.0.0.1 is assigned as the inside IP for 192.0.2.1, 192.0.2.1 will be displayed as the outside IP for 10.0.0.1. !!! note - NetBox does not support tracking one-to-many NAT relationships (also called port address translation). This type of policy requires additional logic to model and cannot be fully represented by IP address alone. + NetBox does not currently support tracking application-level NAT relationships (also called _port address translation_ or PAT). This type of policy requires additional logic to model and cannot be fully represented by IP address alone. + +## Fields + +### Address + +The IPv4 or IPv6 address and mask, in CIDR notation (e.g. `192.0.2.0/24`). + +### Status + +The operational status of the IP address. + +!!! tip + Additional statuses may be defined by setting `IPAddress.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Role + +The functional role fulfilled by this IP address. Options include: + +* **Loopback:** Configured on a loopback interface +* **Secondary:** One of multiple IP addresses configured on an interface +* **Anycast:** Employed for anycast services +* **VIP:** A general-purpose virtual IP address +* **VRRP:** A virtual IP address managed with the VRRP protocol +* **HSRP:** A virtual IP address managed with the HSRP protocol +* **GLBP:** A virtual IP address managed with the GLBP protocol +* **CARP:** A virtual IP address managed with the CARP protocol + +!!! tip + Virtual IP addresses should be assigned to [FHRP groups](./fhrpgroup.md) rather than to actual interfaces to accurately model their shared nature. + +### VRF + +The [Virtual Routing and Forwarding](./vrf.md) instance in which this IP address exists. + +!!! note + VRF assignment is optional. IP addresses with no VRF assigned are considered to exist in the "global" table. + +### DNS Name + +A DNS A/AAAA record value associated with this IP address. diff --git a/docs/models/ipam/iprange.md b/docs/models/ipam/iprange.md index 7b0457f27..53abf10b8 100644 --- a/docs/models/ipam/iprange.md +++ b/docs/models/ipam/iprange.md @@ -1,14 +1,30 @@ # IP Ranges -This model represents an arbitrary range of individual IPv4 or IPv6 addresses, inclusive of its starting and ending addresses. For instance, the range 192.0.2.10 to 192.0.2.20 has eleven members. (The total member count is available as the `size` property on an IPRange instance.) Like prefixes and IP addresses, each IP range may optionally be assigned to a VRF and/or tenant. +This model represents an arbitrary range of individual IPv4 or IPv6 addresses, inclusive of its starting and ending addresses. For instance, the range 192.0.2.10 to 192.0.2.20 has eleven members. (The total member count is available as the `size` property on an IPRange instance.) Like [prefixes](./prefix.md) and [IP addresses](./ipaddress.md), each IP range may optionally be assigned to a [VRF](./vrf.md). -IP also ranges share the same functional roles as prefixes and VLANs, although the assignment of a role is optional. Each IP range must be assigned an operational status, which is one of the following: +## Fields -* Active - Provisioned and in use -* Reserved - Designated for future use -* Deprecated - No longer in use +### VRF -The status of a range does _not_ have any impact on its member IP addresses, which may have their statuses modified separately. +The [Virtual Routing and Forwarding](./vrf.md) instance in which this IP range exists. + +!!! note + VRF assignment is optional. IP ranges with no VRF assigned are considered to exist in the "global" table. + +### Start & End Address + +The beginning and ending IP addresses (inclusive) which define the boundaries of the range. Both IP addresses must specify the correct mask. !!! note The maximum supported size of an IP range is 2^32 - 1. + +### Role + +The user-defined functional [role](./role.md) assigned to the IP range. + +### Status + +The IP range's operational status. Note that the status of a range does _not_ have any impact on its member IP addresses, which may have their statuses defined independently. + +!!! tip + Additional statuses may be defined by setting `IPRange.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. diff --git a/docs/models/ipam/l2vpn.md b/docs/models/ipam/l2vpn.md index 214b8aab0..86a2eed9d 100644 --- a/docs/models/ipam/l2vpn.md +++ b/docs/models/ipam/l2vpn.md @@ -1,8 +1,20 @@ # L2VPN -A L2VPN object is NetBox is a representation of a layer 2 bridge technology such as VXLAN, VPLS or EPL. Each L2VPN can be identified by name as well as an optional unique identifier (VNI would be an example). +A L2VPN object is NetBox is a representation of a layer 2 bridge technology such as VXLAN, VPLS, or EPL. Each L2VPN can be identified by name as well as by an optional unique identifier (VNI would be an example). Once created, L2VPNs can be terminated to [interfaces](../dcim/interface.md) and [VLANs](./vlan.md). -Each L2VPN instance must have one of the following type associated with it: +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Type + +The technology employed in forming and operating the L2VPN. Choices include: * VPLS * VPWS @@ -13,9 +25,17 @@ Each L2VPN instance must have one of the following type associated with it: * EP-TREE * EVP-TREE * VXLAN -* VXLAN EVPN +* VXLAN-EVPN * MPLS-EVPN * PBB-EVPN !!! note - Choosing VPWS, EPL, EP-LAN, EP-TREE will result in only being able to add two terminations to a given L2VPN. + Designating the type as VPWS, EPL, EP-LAN, EP-TREE will limit the L2VPN instance to two terminations. + +### Identifier + +An optional unique numeric identifier. + +### Import & Export Targets + +The [route targets](./routetarget.md) associated with this L2VPN to control the import and export of forwarding information. diff --git a/docs/models/ipam/l2vpntermination.md b/docs/models/ipam/l2vpntermination.md index e7c6a6810..c3c27b8d2 100644 --- a/docs/models/ipam/l2vpntermination.md +++ b/docs/models/ipam/l2vpntermination.md @@ -1,15 +1,18 @@ # L2VPN Termination -A L2VPN Termination is the termination point of a L2VPN. Certain types of L2VPNs may only have 2 termination points (point-to-point) while others may have many terminations (multipoint). - -Each termination consists of a L2VPN it is a member of as well as the connected endpoint which can be an interface or a VLAN. - -The following types of L2VPNs are considered point-to-point: +A L2VPN termination is the attachment of an [L2VPN](./l2vpn.md) to an [interface](../dcim/interface.md) or [VLAN](./vlan.md). Note that the L2VPNs of the following types may have only two terminations assigned to them: * VPWS * EPL * EP-LAN * EP-TREE -!!! note - Choosing any of the above types will result in only being able to add 2 terminations to a given L2VPN. +## Fields + +### L2VPN + +The [L2VPN](./l2vpn.md) instance. + +### VLAN or Interface + +The [VLAN](./vlan.md), [device interface](../dcim/interface.md), or [virtual machine interface](../virtualization/virtualmachine.md) attached to the L2VPN. diff --git a/docs/models/ipam/prefix.md b/docs/models/ipam/prefix.md index bd5e9695f..2fb01daf0 100644 --- a/docs/models/ipam/prefix.md +++ b/docs/models/ipam/prefix.md @@ -1,18 +1,43 @@ # Prefixes -A prefix is an IPv4 or IPv6 network and mask expressed in CIDR notation (e.g. 192.0.2.0/24). A prefix entails only the "network portion" of an IP address: All bits in the address not covered by the mask must be zero. (In other words, a prefix cannot be a specific IP address.) +A prefix is an IPv4 or IPv6 network and mask expressed in CIDR notation (e.g. 192.0.2.0/24). A prefix entails only the "network portion" of an IP address: All bits in the address not covered by the mask must be zero. (In other words, a prefix cannot be a specific IP address.) Prefixes are automatically organized by their parent [aggregate](./aggregate.md) and assigned [VRF](./vrf.md). -Prefixes are automatically organized by their parent aggregates. Additionally, each prefix can be assigned to a particular site and virtual routing and forwarding instance (VRF). Each VRF represents a separate IP space or routing table. All prefixes not assigned to a VRF are considered to be in the "global" table. +## Fields -Each prefix can be assigned a status and a role. These terms are often used interchangeably so it's important to recognize the difference between them. The **status** defines a prefix's operational state. Statuses are hard-coded in NetBox and can be one of the following: +### Prefix -* Container - A summary of child prefixes -* Active - Provisioned and in use -* Reserved - Designated for future use -* Deprecated - No longer in use +The IPv4 or IPv6 network this prefix represents. -On the other hand, a prefix's **role** defines its function. Role assignment is optional and roles are fully customizable. For example, you might create roles to differentiate between production and development infrastructure. +### Status -A prefix may also be assigned to a VLAN. This association is helpful for associating address space with layer two domains. A VLAN may have multiple prefixes assigned to it. +The prefix's operational status. Note that the status of a prefix does _not_ have any impact on its member [IP addresses](./ipaddress.md), which may have their statuses defined independently. The "container" status indicates that the prefix exists merely as a container for organizing child prefixes. -The prefix model include an "is pool" flag. If enabled, NetBox will treat this prefix as a range (such as a NAT pool) wherein every IP address is valid and assignable. This logic is used when identifying available IP addresses within a prefix. If this flag is disabled, NetBox will assume that the first and last (broadcast) address within an IPv4 prefix are unusable. +!!! tip + Additional statuses may be defined by setting `Prefix.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### VRF + +The [Virtual Routing and Forwarding](./vrf.md) instance in which this prefix exists. + +!!! note + VRF assignment is optional. Prefixes with no VRF assigned are considered to exist in the "global" table. + +### Role + +The user-defined functional [role](./role.md) assigned to the prefix. + +### Is a Pool + +Designates whether the prefix should be treated as a pool. If selected, the first and last IP addresses within the prefix (normally reserved as the network and broadcast addresses, respectively) will be considered usable. This option is ideal for documenting NAT pools. + +### Mark Utilized + +If selected, this prefix will report 100% utilization regardless of how many child objects have been defined within it. + +### Site + +The [site](../dcim/site.md) to which this prefix is assigned (optional). + +### VLAN + +The [VLAN](./vlan.md) to which this prefix is assigned (optional). This mapping is helpful for associating IP space with layer two domains. A VLAN may have multiple prefixes assigned to it. diff --git a/docs/models/ipam/rir.md b/docs/models/ipam/rir.md index 6904381ac..efa5cf0f5 100644 --- a/docs/models/ipam/rir.md +++ b/docs/models/ipam/rir.md @@ -2,6 +2,18 @@ [Regional Internet registries](https://en.wikipedia.org/wiki/Regional_Internet_registry) are responsible for the allocation of globally-routable address space. The five RIRs are ARIN, RIPE, APNIC, LACNIC, and AFRINIC. However, some address space has been set aside for internal use, such as defined in RFCs 1918 and 6598. NetBox considers these RFCs as a sort of RIR as well; that is, an authority which "owns" certain address space. There also exist lower-tier registries which serve particular geographic areas. -Users can create whatever RIRs they like, but each aggregate must be assigned to one RIR. The RIR model includes a boolean flag which indicates whether the RIR allocates only private IP space. +Users can create whatever RIRs they like, but each [aggregate](./aggregate.md) must be assigned to one RIR. For example, suppose your organization has been allocated 104.131.0.0/16 by ARIN. It also makes use of RFC 1918 addressing internally. You would first create RIRs named "ARIN" and "RFC 1918," then create an aggregate for each of these top-level prefixes, assigning it to its respective RIR. -For example, suppose your organization has been allocated 104.131.0.0/16 by ARIN. It also makes use of RFC 1918 addressing internally. You would first create RIRs named "ARIN" and "RFC 1918," then create an aggregate for each of these top-level prefixes, assigning it to its respective RIR. +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Private + +Designates this RIR as an authority for private/local IP space only (e.g. an RFC). diff --git a/docs/models/ipam/role.md b/docs/models/ipam/role.md index 8623e5282..7685f7d85 100644 --- a/docs/models/ipam/role.md +++ b/docs/models/ipam/role.md @@ -1,3 +1,17 @@ # Prefix/VLAN Roles A role indicates the function of a prefix or VLAN. For example, you might define Data, Voice, and Security roles. Generally, a prefix will be assigned the same functional role as the VLAN to which it is assigned (if any). + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Weight + +A numeric weight employed to influence the ordering of roles. Roles with a lower weight will be listed before those with higher weights. diff --git a/docs/models/ipam/routetarget.md b/docs/models/ipam/routetarget.md index b71e96904..298900f88 100644 --- a/docs/models/ipam/routetarget.md +++ b/docs/models/ipam/routetarget.md @@ -2,4 +2,8 @@ A route target is a particular type of [extended BGP community](https://tools.ietf.org/html/rfc4360#section-4) used to control the redistribution of routes among VRF tables in a network. Route targets can be assigned to individual VRFs in NetBox as import or export targets (or both) to model this exchange in an L3VPN. Each route target must be given a unique name, which should be in a format prescribed by [RFC 4364](https://tools.ietf.org/html/rfc4364#section-4.2), similar to a VR route distinguisher. -Each route target can optionally be assigned to a tenant, and may have tags assigned to it. +## Fields + +### Name + +The route target identifier formatted in accordance with [RFC 4360](https://tools.ietf.org/html/rfc4360). diff --git a/docs/models/ipam/service.md b/docs/models/ipam/service.md index 057544a91..316828b61 100644 --- a/docs/models/ipam/service.md +++ b/docs/models/ipam/service.md @@ -1,5 +1,23 @@ # Services -A service represents a layer four TCP or UDP service available on a device or virtual machine. For example, you might want to document that an HTTP service is running on a device. Each service includes a name, protocol, and port number; for example, "SSH (TCP/22)" or "DNS (UDP/53)." +A service represents a layer seven application available on a device or virtual machine. For example, a service might be created in NetBox to represent an HTTP server running on TCP/8000. Each service may optionally be further bound to one or more specific interfaces assigned to the selected device or virtual machine. -A service may optionally be bound to one or more specific IP addresses belonging to its parent device or VM. (If no IP addresses are bound, the service is assumed to be reachable via any assigned IP address.) +To aid in the efficient creation of services, users may opt to first create a [service template](./servicetemplate.md) from which service definitions can be quickly replicated. + +## Fields + +### Name + +A service or protocol name. + +### Protocol + +The wire protocol on which the service runs. Choices include UDP, TCP, and SCTP. + +### Ports + +One or more numeric ports to which the service is bound. Multiple ports can be expressed using commas and/or hyphens. For example, `80,8001-8003` specifies ports 80, 8001, 8002, and 8003. + +### IP Addresses + +The [IP address(es)](./ipaddress.md) to which this service is bound. If no IP addresses are bound, the service is assumed to be reachable via any assigned IP address. diff --git a/docs/models/ipam/servicetemplate.md b/docs/models/ipam/servicetemplate.md index 7fed40211..28c66b648 100644 --- a/docs/models/ipam/servicetemplate.md +++ b/docs/models/ipam/servicetemplate.md @@ -1,3 +1,17 @@ # Service Templates -Service templates can be used to instantiate services on devices and virtual machines. A template defines a name, protocol, and port number(s), and may optionally include a description. Services can be instantiated from templates and applied to devices and/or virtual machines, and may be associated with specific IP addresses. +Service templates can be used to instantiate [services](./service.md) on [devices](../dcim/device.md) and [virtual machines](../virtualization/virtualmachine.md). + +## Fields + +### Name + +A service or protocol name. + +### Protocol + +The wire protocol on which the service runs. Choices include UDP, TCP, and SCTP. + +### Ports + +One or more numeric ports to which the service is bound. Multiple ports can be expressed using commas and/or hyphens. For example, `80,8001-8003` specifies ports 80, 8001, 8002, and 8003. diff --git a/docs/models/ipam/vlan.md b/docs/models/ipam/vlan.md index c7aa0d05f..2dd5ec2d3 100644 --- a/docs/models/ipam/vlan.md +++ b/docs/models/ipam/vlan.md @@ -1,11 +1,28 @@ # VLANs -A VLAN represents an isolated layer two domain, identified by a name and a numeric ID (1-4094) as defined in [IEEE 802.1Q](https://en.wikipedia.org/wiki/IEEE_802.1Q). VLANs are arranged into VLAN groups to define scope and to enforce uniqueness. +A Virtual LAN (VLAN) represents an isolated layer two domain, identified by a name and a numeric ID (1-4094) as defined in [IEEE 802.1Q](https://en.wikipedia.org/wiki/IEEE_802.1Q). VLANs are arranged into [VLAN groups](./vlangroup.md) to define scope and to enforce uniqueness. -Each VLAN must be assigned one of the following operational statuses: +## Fields -* Active -* Reserved -* Deprecated +### ID -As with prefixes, each VLAN may also be assigned a functional role. Prefixes and VLANs share the same set of customizable roles. +A 12-bit numeric ID for the VLAN, 1-4094 (inclusive). + +### Name + +The configured VLAN name. + +### Status + +The VLAN's operational status. + +!!! tip + Additional statuses may be defined by setting `VLAN.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Role + +The user-defined functional [role](./role.md) assigned to the VLAN. + +### VLAN Group or Site + +The [VLAN group](./vlangroup.md) or [site](../dcim/site.md) to which the VLAN is assigned. diff --git a/docs/models/ipam/vlangroup.md b/docs/models/ipam/vlangroup.md index 2840fafed..a2920fb70 100644 --- a/docs/models/ipam/vlangroup.md +++ b/docs/models/ipam/vlangroup.md @@ -1,7 +1,23 @@ # VLAN Groups -VLAN groups can be used to organize VLANs within NetBox. Each VLAN group can be scoped to a particular region, site group, site, location, rack, cluster group, or cluster. Member VLANs will be available for assignment to devices and/or virtual machines within the specified scope. +VLAN groups can be used to organize [VLANs](./vlan.md) within NetBox. Each VLAN group can be scoped to a particular [region](../dcim/region.md), [site group](../dcim/sitegroup.md), [site](../dcim/sitegroup.md), [location](../dcim/location.md), [rack](../dcim/rack.md), [cluster group](../virtualization/clustergroup.md), or [cluster](../virtualization/cluster.md). Member VLANs will be available for assignment to devices and/or virtual machines within the specified scope. + +Groups can also be used to enforce uniqueness: Each VLAN within a group must have a unique ID and name. VLANs which are not assigned to a group may have overlapping names and IDs (including VLANs which belong to a common site). For example, two VLANs with ID 123 may be created, but they cannot both be assigned to the same group. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) + +### Minimum & Maximum VLAN IDs A minimum and maximum child VLAN ID must be set for each group. (These default to 1 and 4094 respectively.) VLANs created within a group must have a VID that falls between these values (inclusive). -Groups can also be used to enforce uniqueness: Each VLAN within a group must have a unique ID and name. VLANs which are not assigned to a group may have overlapping names and IDs (including VLANs which belong to a common site). For example, you can create two VLANs with ID 123, but they cannot both be assigned to the same group. +### Scope + +The domain covered by a VLAN group, defined as one of the supported object types. This conveys the context in which a VLAN group applies. diff --git a/docs/models/ipam/vrf.md b/docs/models/ipam/vrf.md index 392141fdd..e45a81daf 100644 --- a/docs/models/ipam/vrf.md +++ b/docs/models/ipam/vrf.md @@ -1,14 +1,26 @@ # Virtual Routing and Forwarding (VRF) -A VRF object in NetBox represents a virtual routing and forwarding (VRF) domain. Each VRF is essentially a separate routing table. VRFs are commonly used to isolate customers or organizations from one another within a network, or to route overlapping address space (e.g. multiple instances of the 10.0.0.0/8 space). Each VRF may be assigned to a specific tenant to aid in organizing the available IP space by customer or internal user. +A VRF object in NetBox represents a Virtual Routing and Forwarding (VRF) domain. Each VRF is essentially an independent routing table. VRFs are commonly used to isolate customers or organizations from one another within a network, or to route overlapping address space (e.g. multiple instances of the 10.0.0.0/8 space). Each VRF may be assigned to a specific tenant to aid in organizing the available IP space by customer or internal user. -Each VRF is assigned a unique name and an optional route distinguisher (RD). The RD is expected to take one of the forms prescribed in [RFC 4364](https://tools.ietf.org/html/rfc4364#section-4.2), however its formatting is not strictly enforced. +Each [prefix](./prefix.md), [IP range](./iprange.md), and [IP address](./ipaddress.md) may be assigned to one (and only one) VRF. If you have a prefix or IP address which exists in multiple VRFs, you will need to create a separate instance of it in NetBox for each VRF. Any such object not assigned to a VRF is said to belong to the "global" table. -Each prefix and IP address may be assigned to one (and only one) VRF. If you have a prefix or IP address which exists in multiple VRFs, you will need to create a separate instance of it in NetBox for each VRF. Any prefix or IP address not assigned to a VRF is said to belong to the "global" table. +## Fields -By default, NetBox will allow duplicate prefixes to be assigned to a VRF. This behavior can be toggled by setting the "enforce unique" flag on the VRF model. +### Name + +The configured or administrative name for the VRF instance. + +### Route Distinguisher + +A route distinguisher is used to map routes to VRFs within a device's routing table e.g. for MPLS/VPN. The assignment of a route distinguisher is optional. If defined, the RD is expected to take one of the forms prescribed in [RFC 4364](https://tools.ietf.org/html/rfc4364#section-4.2), however its formatting is not strictly enforced. + +### Enforce Unique Space + +By default, NetBox will permit duplicate prefixes to be assigned to a VRF. This behavior can be toggled by setting the "enforce unique" flag on the VRF model. !!! note Enforcement of unique IP space can be toggled for global table (non-VRF prefixes) using the `ENFORCE_GLOBAL_UNIQUE` configuration setting. -Each VRF may have one or more import and/or export route targets applied to it. Route targets are used to control the exchange of routes (prefixes) among VRFs in L3VPNs. +### Import & Export Targets + +Each VRF may have one or more import and/or export [route targets](./routetarget.md) applied to it. Route targets are used to control the exchange of routes (prefixes) among VRFs in L3VPNs. From 0ba45caabf9ad26f51d19687ee6108f80eef5d1a Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 16 Aug 2022 15:57:29 -0400 Subject: [PATCH 231/245] Update virtualization models documentation --- docs/models/dcim/device.md | 7 +++ docs/models/virtualization/cluster.md | 27 +++++++++- docs/models/virtualization/clustergroup.md | 12 ++++- docs/models/virtualization/clustertype.md | 12 ++++- docs/models/virtualization/virtualmachine.md | 57 ++++++++++++++++---- docs/models/virtualization/vminterface.md | 54 ++++++++++++++++++- 6 files changed, 154 insertions(+), 15 deletions(-) diff --git a/docs/models/dcim/device.md b/docs/models/dcim/device.md index ddf1bfb09..33d07e07e 100644 --- a/docs/models/dcim/device.md +++ b/docs/models/dcim/device.md @@ -72,6 +72,13 @@ The device's operational status. A device may be associated with a particular [platform](./platform.md) to indicate its operating system. Note that only platforms assigned to the associated manufacturer (or to no manufacturer) will be available for selection. +### Primary IPv4 & IPv6 Addresses + +Each device may designate one primary IPv4 address and/or one primary IPv6 address for management purposes. + +!!! tip + NetBox will prefer IPv6 addresses over IPv4 addresses by default. This can be changed by setting the `PREFER_IPV4` configuration parameter. + ### Cluster If this device will serve as a host for a virtualization [cluster](../virtualization/cluster.md), it can be assigned here. (Host devices can also be assigned by editing the cluster.) diff --git a/docs/models/virtualization/cluster.md b/docs/models/virtualization/cluster.md index 3e3516cd6..50b5dbd1d 100644 --- a/docs/models/virtualization/cluster.md +++ b/docs/models/virtualization/cluster.md @@ -1,5 +1,28 @@ # Clusters -A cluster is a logical grouping of physical resources within which virtual machines run. A cluster must be assigned a type (technological classification) and operational status, and may optionally be assigned to a cluster group, site, and/or tenant. Each cluster must have a unique name within its assigned group and/or site, if any. +A cluster is a logical grouping of physical resources within which [virtual machines](./virtualmachine.md) run. Physical [devices](../dcim/device.md) may be associated with clusters as hosts. This allows users to track on which host(s) a particular virtual machine may reside. -Physical devices may be associated with clusters as hosts. This allows users to track on which host(s) a particular virtual machine may reside. However, NetBox does not support pinning a specific VM within a cluster to a particular host device. +## Fields + +### Name + +A human-friendly name for the cluster. Must be unique within the assigned group and site. + +### Type + +The [cluster type](./clustertype.md) assigned for this cluster. + +### Group + +The [cluster group](./clustergroup.md) to which this cluster belongs. + +### Status + +The cluster's operational status. + +!!! tip + Additional statuses may be defined by setting `Cluster.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Site + +The [site](../dcim/site.md) with which the cluster is associated. diff --git a/docs/models/virtualization/clustergroup.md b/docs/models/virtualization/clustergroup.md index 6dd0f9688..bae177792 100644 --- a/docs/models/virtualization/clustergroup.md +++ b/docs/models/virtualization/clustergroup.md @@ -1,3 +1,13 @@ # Cluster Groups -Cluster groups may be created for the purpose of organizing clusters. The arrangement of clusters into groups is optional. +Cluster groups may be created for the purpose of organizing [clusters](./cluster.md). The arrangement of clusters into groups is optional. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/virtualization/clustertype.md b/docs/models/virtualization/clustertype.md index cee557df3..51eed5ec4 100644 --- a/docs/models/virtualization/clustertype.md +++ b/docs/models/virtualization/clustertype.md @@ -1,3 +1,13 @@ # Cluster Types -A cluster type represents a technology or mechanism by which a cluster is formed. For example, you might create a cluster type named "VMware vSphere" for a locally hosted cluster or "DigitalOcean NYC3" for one hosted by a cloud provider. +A cluster type represents a technology or mechanism by which a [cluster](./cluster.md) is formed. For example, you might create a cluster type named "VMware vSphere" for a locally hosted cluster or "DigitalOcean NYC3" for one hosted by a cloud provider. + +## Fields + +### Name + +A unique human-friendly name. + +### Slug + +A unique URL-friendly identifier. (This value can be used for filtering.) diff --git a/docs/models/virtualization/virtualmachine.md b/docs/models/virtualization/virtualmachine.md index 4ddffb99a..769d49154 100644 --- a/docs/models/virtualization/virtualmachine.md +++ b/docs/models/virtualization/virtualmachine.md @@ -1,16 +1,53 @@ # Virtual Machines -A virtual machine represents a virtual compute instance hosted within a cluster. Each VM must be assigned to a site and/or cluster, and may optionally be assigned to a particular host device within a cluster. +A virtual machine (VM) represents a virtual compute instance hosted within a [cluster](./cluster.md). Each VM must be assigned to a [site](../dcim/site.md) and/or cluster, and may optionally be assigned to a particular host [device](../dcim/device.md) within a cluster. -Like devices, each VM can be assigned a platform and/or functional role, and must have one of the following operational statuses assigned to it: +Virtual machines may have virtual [interfaces](./vminterface.md) assigned to them, but do not support any physical component. When a VM has one or more interfaces with IP addresses assigned, a primary IP for the device can be designated, for both IPv4 and IPv6. -* Active -* Offline -* Planned -* Staged -* Failed -* Decommissioning +## Fields -Additional fields are available for annotating the vCPU count, memory (GB), and disk (GB) allocated to each VM. A VM may be allocated a partial vCPU count (e.g. 1.5 vCPU). +### Name -Each VM may optionally be assigned to a tenant. Virtual machines may have virtual interfaces assigned to them, but do not support any physical component. +The virtual machine's configured name. Must be unique to the assigned cluster and tenant. + +### Role + +The functional [role](../dcim/devicerole.md) assigned to the VM. + +### Status + +The VM's operational status. + +!!! tip + Additional statuses may be defined by setting `VirtualMachine.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Site & Cluster + +The [site](../dcim/site.md) and/or [cluster](./cluster.md) to which the VM is assigned. + +### Device + +The physical host [device](../dcim/device.md) within the assigned site/cluster on which this VM resides. + +### Platform + +A VM may be associated with a particular [platform](../dcim/platform.md) to indicate its operating system. + +### Primary IPv4 & IPv6 Addresses + +Each VM may designate one primary IPv4 address and/or one primary IPv6 address for management purposes. + +!!! tip + NetBox will prefer IPv6 addresses over IPv4 addresses by default. This can be changed by setting the `PREFER_IPV4` configuration parameter. + +### vCPUs + +The number of virtual CPUs provisioned. A VM may be allocated a partial vCPU count (e.g. 1.5 vCPU). + +### Memory + +The amount of running memory provisioned, in megabytes. + +### Disk + +The amount of disk storage provisioned, in gigabytes. diff --git a/docs/models/virtualization/vminterface.md b/docs/models/virtualization/vminterface.md index 7f1a5082d..264fb95ba 100644 --- a/docs/models/virtualization/vminterface.md +++ b/docs/models/virtualization/vminterface.md @@ -1,3 +1,55 @@ ## Interfaces -Virtual machine interfaces behave similarly to device interfaces, and can be assigned to VRFs, and may have IP addresses, VLANs, and services attached to them. However, given their virtual nature, they lack properties pertaining to physical attributes. For example, VM interfaces do not have a physical type and cannot have cables attached to them. +[Virtual machine](./virtualmachine.md) interfaces behave similarly to device [interfaces](../dcim/interface.md): They can be assigned to VRFs, may have IP addresses, VLANs, and services attached to them, and so on. However, given their virtual nature, they lack properties pertaining to physical attributes. For example, VM interfaces do not have a physical type and cannot have cables attached to them. + +## Fields + +### Virtual Machine + +The [virtual machine](./virtualmachine.md) to which this interface is assigned. + +### Name + +The interface's name. Must be unique to the assigned VM. + +### Parent Interface + +Identifies the parent interface of a subinterface (e.g. used to employ encapsulation). + +### Bridged Interface + +An interface on the same VM with which this interface is bridged. + +### Enabled + +If not selected, this interface will be treated as disabled/inoperative. + +### MAC Address + +The 48-bit MAC address (for Ethernet interfaces). + +### MTU + +The interface's configured maximum transmissible unit (MTU). + +### 802.1Q Mode + +For switched Ethernet interfaces, this identifies the 802.1Q encapsulation strategy in effect. Options include: + +* **Access:** All traffic is assigned to a single VLAN, with no tagging. +* **Tagged:** One untagged "native" VLAN is allowed, as well as any number of tagged VLANs. +* **Tagged (all):** Implies that all VLANs are carried by the interface. One untagged VLAN may be designated. + +This field must be left blank for routed interfaces which do employ 802.1Q encapsulation. + +### Untagged VLAN + +The "native" (untagged) VLAN for the interface. Valid only when one of the above 802.1Q mode is selected. + +### Tagged VLANs + +The tagged VLANs which are configured to be carried by this interface. Valid only for the "tagged" 802.1Q mode above. + +### VRF + +The [virtual routing and forwarding](../ipam/vrf.md) instance to which this interface is assigned. From e6c69127e49c92040d17a1948de011bd20d051b0 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 16 Aug 2022 16:06:48 -0400 Subject: [PATCH 232/245] Add model documentation for JournalEntry --- docs/models/extras/journalentry.md | 16 ++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 17 insertions(+) create mode 100644 docs/models/extras/journalentry.md diff --git a/docs/models/extras/journalentry.md b/docs/models/extras/journalentry.md new file mode 100644 index 000000000..7e9bc986d --- /dev/null +++ b/docs/models/extras/journalentry.md @@ -0,0 +1,16 @@ +# Journal Entries + +Most objects in NetBox support journaling. This is the ability of users to record chronological notes indicating changes to or work performed on resources in NetBox. For example, a data center technician might add a journal entry for a device when swapping out a failed power supply. + +## Fields + +### Kind + +A general classification for the entry type (info, success, warning, or danger.) + +!!! tip + Additional kinds may be defined by setting `JournalEntry.kind` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Comments + +The body of the journal entry. [Markdown](../../reference/markdown.md) rendering is supported. diff --git a/mkdocs.yml b/mkdocs.yml index be9c31651..eef000481 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -196,6 +196,7 @@ nav: - CustomLink: 'models/extras/customlink.md' - ExportTemplate: 'models/extras/exporttemplate.md' - ImageAttachment: 'models/extras/imageattachment.md' + - JournalEntry: 'models/extras/journalentry.md' - Tag: 'models/extras/tag.md' - Webhook: 'models/extras/webhook.md' - IPAM: From a8576e54c72cb3ea5c11d6b683edc387ddff0043 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 10:30:35 -0400 Subject: [PATCH 233/245] Optimize database queries --- netbox/dcim/tables/template_code.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/netbox/dcim/tables/template_code.py b/netbox/dcim/tables/template_code.py index cc2cc4c84..6e9ed6672 100644 --- a/netbox/dcim/tables/template_code.py +++ b/netbox/dcim/tables/template_code.py @@ -101,7 +101,7 @@ MODULAR_COMPONENT_TEMPLATE_BUTTONS = """ CONSOLEPORT_BUTTONS = """ {% if perms.dcim.add_inventoryitem %} - + {% endif %} @@ -133,7 +133,7 @@ CONSOLEPORT_BUTTONS = """ CONSOLESERVERPORT_BUTTONS = """ {% if perms.dcim.add_inventoryitem %} - + {% endif %} @@ -165,7 +165,7 @@ CONSOLESERVERPORT_BUTTONS = """ POWERPORT_BUTTONS = """ {% if perms.dcim.add_inventoryitem %} - + {% endif %} @@ -196,7 +196,7 @@ POWERPORT_BUTTONS = """ POWEROUTLET_BUTTONS = """ {% if perms.dcim.add_inventoryitem %} - + {% endif %} @@ -232,7 +232,7 @@ INTERFACE_BUTTONS = """
  • IP Address
    • {% endif %} {% if perms.dcim.add_inventoryitem %} -
  • Inventory Item
    • +
  • Inventory Item
    • {% endif %} @@ -272,7 +272,7 @@ INTERFACE_BUTTONS = """ {% endif %} {% elif record.is_wireless and perms.wireless.add_wirelesslink %} - + {% endif %} @@ -280,7 +280,7 @@ INTERFACE_BUTTONS = """ FRONTPORT_BUTTONS = """ {% if perms.dcim.add_inventoryitem %} - + {% endif %} @@ -317,7 +317,7 @@ FRONTPORT_BUTTONS = """ REARPORT_BUTTONS = """ {% if perms.dcim.add_inventoryitem %} - + {% endif %} @@ -373,7 +373,7 @@ MODULEBAY_BUTTONS = """ {% else %} - + {% endif %} From e523006ec32a5c8cede592558c494de662883410 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 10:39:30 -0400 Subject: [PATCH 234/245] Fixes #9758: Display parent object of connected termination --- docs/release-notes/version-3.3.md | 1 + netbox/dcim/tables/template_code.py | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 9ec4eb9b5..3c3121c66 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -99,6 +99,7 @@ Custom field UI visibility has no impact on API operation. ### Bug Fixes (from Beta2) +* [#9758](https://github.com/netbox-community/netbox/issues/9758) - Display parent object of connected termination * [#9900](https://github.com/netbox-community/netbox/issues/9900) - Pre-populate site & rack fields for cable connection form * [#9938](https://github.com/netbox-community/netbox/issues/9938) - Exclude virtual interfaces from terminations list when connecting a cable * [#9939](https://github.com/netbox-community/netbox/issues/9939) - Fix list of next nodes for split paths under trace view diff --git a/netbox/dcim/tables/template_code.py b/netbox/dcim/tables/template_code.py index 6e9ed6672..3403f9392 100644 --- a/netbox/dcim/tables/template_code.py +++ b/netbox/dcim/tables/template_code.py @@ -1,5 +1,9 @@ LINKTERMINATION = """ {% for termination in value %} + {% if termination.parent_object %} + {{ termination.parent_object }} + + {% endif %} {{ termination }}{% if not forloop.last %},{% endif %} {% empty %} {{ ''|placeholder }} From 93b36ed58070c287e95881f2f8e35ad60d42e9ab Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 10:47:42 -0400 Subject: [PATCH 235/245] Closes #10032: Remove unique constraint from L2VPN identifier --- docs/models/ipam/l2vpn.md | 2 +- netbox/ipam/migrations/0059_l2vpn.py | 4 +--- netbox/ipam/models/l2vpn.py | 8 +++++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/models/ipam/l2vpn.md b/docs/models/ipam/l2vpn.md index 86a2eed9d..e7ee1e187 100644 --- a/docs/models/ipam/l2vpn.md +++ b/docs/models/ipam/l2vpn.md @@ -34,7 +34,7 @@ The technology employed in forming and operating the L2VPN. Choices include: ### Identifier -An optional unique numeric identifier. +An optional numeric identifier. This can be used to track a pseudowire ID, for example. ### Import & Export Targets diff --git a/netbox/ipam/migrations/0059_l2vpn.py b/netbox/ipam/migrations/0059_l2vpn.py index 7436989f7..bd4761593 100644 --- a/netbox/ipam/migrations/0059_l2vpn.py +++ b/netbox/ipam/migrations/0059_l2vpn.py @@ -1,5 +1,3 @@ -# Generated by Django 4.0.5 on 2022-07-06 16:51 - import django.core.serializers.json from django.db import migrations, models import django.db.models.deletion @@ -26,7 +24,7 @@ class Migration(migrations.Migration): ('name', models.CharField(max_length=100, unique=True)), ('slug', models.SlugField()), ('type', models.CharField(max_length=50)), - ('identifier', models.BigIntegerField(blank=True, null=True, unique=True)), + ('identifier', models.BigIntegerField(blank=True, null=True)), ('description', models.CharField(blank=True, max_length=200)), ('export_targets', models.ManyToManyField(blank=True, related_name='exporting_l2vpns', to='ipam.routetarget')), ('import_targets', models.ManyToManyField(blank=True, related_name='importing_l2vpns', to='ipam.routetarget')), diff --git a/netbox/ipam/models/l2vpn.py b/netbox/ipam/models/l2vpn.py index 5adf5e05d..25810c1a6 100644 --- a/netbox/ipam/models/l2vpn.py +++ b/netbox/ipam/models/l2vpn.py @@ -15,11 +15,13 @@ class L2VPN(NetBoxModel): unique=True ) slug = models.SlugField() - type = models.CharField(max_length=50, choices=L2VPNTypeChoices) + type = models.CharField( + max_length=50, + choices=L2VPNTypeChoices + ) identifier = models.BigIntegerField( null=True, - blank=True, - unique=True + blank=True ) import_targets = models.ManyToManyField( to='ipam.RouteTarget', From 5671a37f43fe4d512fc23ac1509f0c8770e3adaa Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 10:51:50 -0400 Subject: [PATCH 236/245] Closes #10036: Set clone_fields on L2VPNTermination --- netbox/ipam/models/l2vpn.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/netbox/ipam/models/l2vpn.py b/netbox/ipam/models/l2vpn.py index 25810c1a6..3c08b5f48 100644 --- a/netbox/ipam/models/l2vpn.py +++ b/netbox/ipam/models/l2vpn.py @@ -8,6 +8,11 @@ from ipam.choices import L2VPNTypeChoices from ipam.constants import L2VPN_ASSIGNMENT_MODELS from netbox.models import NetBoxModel +__all__ = ( + 'L2VPN', + 'L2VPNTermination', +) + class L2VPN(NetBoxModel): name = models.CharField( @@ -79,6 +84,8 @@ class L2VPNTermination(NetBoxModel): fk_field='assigned_object_id' ) + clone_fields = ('l2vpn',) + class Meta: ordering = ('l2vpn',) verbose_name = 'L2VPN termination' From 107f19a0e9413ad88c6a4382900e64a1079731af Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 10:59:17 -0400 Subject: [PATCH 237/245] Closes #10035: Include assigned_object_parent column by default in L2VPN terminations table --- netbox/ipam/tables/l2vpn.py | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/netbox/ipam/tables/l2vpn.py b/netbox/ipam/tables/l2vpn.py index e2eae7a32..168c8ca89 100644 --- a/netbox/ipam/tables/l2vpn.py +++ b/netbox/ipam/tables/l2vpn.py @@ -49,21 +49,27 @@ class L2VPNTerminationTable(NetBoxTable): verbose_name='Object Type' ) assigned_object = tables.Column( - verbose_name='Assigned Object', linkify=True, - orderable=False + orderable=False, + verbose_name='Object' ) assigned_object_parent = tables.Column( linkify=True, - orderable=False + orderable=False, + verbose_name='Object Parent' ) assigned_object_site = tables.Column( linkify=True, - orderable=False + orderable=False, + verbose_name='Object Site' ) class Meta(NetBoxTable.Meta): model = L2VPNTermination - fields = ('pk', 'l2vpn', 'assigned_object_type', 'assigned_object', 'assigned_object_parent', - 'assigned_object_site', 'actions') - default_columns = ('pk', 'l2vpn', 'assigned_object_type', 'assigned_object', 'actions') + fields = ( + 'pk', 'l2vpn', 'assigned_object_type', 'assigned_object', 'assigned_object_parent', 'assigned_object_site', + 'actions', + ) + default_columns = ( + 'pk', 'l2vpn', 'assigned_object_type', 'assigned_object_parent', 'assigned_object', 'actions', + ) From bfa3c957d7d2da4f37c2f1adf8280dd7a8073630 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 11:31:45 -0400 Subject: [PATCH 238/245] Clean up release notes --- docs/release-notes/version-3.3.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 3c3121c66..a08192940 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -1,10 +1,10 @@ # NetBox v3.3 -## v3.3-beta2 (2022-08-03) +## v3.3.0 (FUTURE) ### Breaking Changes -* Device position and rack unit values are now reported as decimals (e.g. `1.0` or `1.5`) to support modeling half-height rack units. +* Device position, device type height, and rack unit values are now reported as decimals (e.g. `1.0` or `1.5`) to support modeling half-height rack units. * The `nat_outside` relation on the IP address model now returns a list of zero or more related IP addresses, rather than a single instance (or None). * Several fields on the cable API serializers have been altered or removed to support multiple-object cable terminations: @@ -33,26 +33,26 @@ #### Multi-object Cable Terminations ([#9102](https://github.com/netbox-community/netbox/issues/9102)) -When creating a cable in NetBox, each end can now be attached to multiple objects. This allows accurate modeling of duplex fiber connections to individual termination ports and breakout cables, as examples. (Note that all terminations attached to one end of a cable must be the same object type, but do not need to connect to the same parent object.) Additionally, cable terminations can now be modified without needing to delete and recreate the cable. +When creating a cable in NetBox, each end can now be attached to multiple termination points. This allows accurate modeling of duplex fiber connections to individual termination ports and breakout cables, for example. (Note that all terminations attached to one end of a cable must be the same object type, but do not need to connect to the same parent object.) Additionally, cable terminations can now be modified without needing to delete and recreate the cable. #### L2VPN Modeling ([#8157](https://github.com/netbox-community/netbox/issues/8157)) -NetBox can now model a variety of L2 VPN technologies, including VXLAN, VPLS, and others. Each L2VPN can be terminated to multiple device or virtual machine interfaces and/or VLANs to track connectivity across an overlay. Similarly to VRFs, each L2VPN can also have import and export route targets associated with it. +NetBox can now model a variety of L2 VPN technologies, including VXLAN, VPLS, and others. Interfaces and VLANs can be attached to L2VPNs to track connectivity across an overlay. Similarly to VRFs, each L2VPN can also have import and export route targets associated with it. #### PoE Interface Attributes ([#1099](https://github.com/netbox-community/netbox/issues/1099)) -Two new fields have been added to the device interface model to track power over Ethernet (PoE) capabilities: +Two new fields have been added to the device interface model to track Power over Ethernet (PoE) capabilities: * **PoE mode**: Power supplying equipment (PSE) or powered device (PD) * **PoE type**: Applicable IEEE standard or other power type #### Half-Height Rack Units ([#51](https://github.com/netbox-community/netbox/issues/51)) -Device type height can now be specified in 0.5U increments, allowing for the creation of half-height devices. Additionally, a device can be installed at the half-unit mark within a rack (e.g. U2.5). For example, two half-height devices positioned in sequence will consume a single rack unit; two consecutive 1.5U devices will consume 3U of space. +Device type height can now be specified in 0.5U increments, allowing for the creation of devices consume partial rack units. Additionally, a device can be installed at the half-unit mark within a rack (e.g. U2.5). For example, two half-height devices positioned in sequence will consume a single rack unit; two consecutive 1.5U devices will consume 3U of space. #### Restrict API Tokens by Client IP ([#8233](https://github.com/netbox-community/netbox/issues/8233)) -API tokens can now be restricted to use by certain client IP addresses or networks. For example, an API token with its `allowed_ips` list set to `[192.0.2.0/24]` will only permit authentication from API clients within that network; requests from other sources will fail authentication. This can be very useful for restricting the use of a token to specific clients. +API tokens can now be restricted to use by certain client IP addresses or networks. For example, an API token with its `allowed_ips` list set to `[192.0.2.0/24]` will permit authentication only from API clients within that network; requests from other sources will fail authentication. This enables administrators to restrict the use of a token to specific clients. #### Reference User in Permission Constraints ([#9074](https://github.com/netbox-community/netbox/issues/9074)) @@ -66,11 +66,11 @@ NetBox's permission constraints have been expanded to support referencing the cu #### Custom Field Grouping ([#8495](https://github.com/netbox-community/netbox/issues/8495)) -A `group_name` field has been added to the custom field model to enable organizing related custom fields by group. Similarly to custom links, custom links which have been assigned to a common group will be rendered within that group when viewing an object in the UI. (Custom field grouping has no effect on API operation.) +A `group_name` field has been added to the custom field model to enable organizing related custom fields by group. Similarly to custom links, custom fields which have been assigned to the same group will be rendered within that group when viewing an object in the UI. (Custom field grouping has no effect on API operation.) #### Toggle Custom Field Visibility ([#9166](https://github.com/netbox-community/netbox/issues/9166)) -The behavior of each custom field within the NetBox UI can now be controlled individually by toggling its UI visibility. Three settings are available: +The behavior of each custom field within the NetBox UI can now be controlled individually by toggling its UI visibility. Three options are available: * **Read/write**: The custom field is included when viewing and editing objects (default). * **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) From 9e22946bb891006a23d73b1cd965fd36ed467126 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 12:00:11 -0400 Subject: [PATCH 239/245] #9986: Update tzdata & remove pytz pin --- requirements.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/requirements.txt b/requirements.txt index bdb674565..ebe5c3b8b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -30,10 +30,7 @@ social-auth-app-django==5.0.0 social-auth-core==4.3.0 svgwrite==1.4.3 tablib==3.2.1 -tzdata==2022.1 +tzdata==2022.2 # Workaround for #7401 jsonschema==3.2.0 - -# Workaround for #9986 -pytz==2022.1 From f9a6e368a7432216132444ac36aba9284257a2db Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 13:55:21 -0400 Subject: [PATCH 240/245] Release v3.3.0 --- .github/ISSUE_TEMPLATE/bug_report.yaml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yaml | 2 +- docs/release-notes/version-3.3.md | 2 +- netbox/netbox/settings.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index dc8dd8275..3844b6753 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -14,7 +14,7 @@ body: attributes: label: NetBox version description: What version of NetBox are you currently running? - placeholder: v3.3-beta2 + placeholder: v3.3.0 validations: required: true - type: dropdown diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml index d9e5a26fd..3c7638f42 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yaml +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -14,7 +14,7 @@ body: attributes: label: NetBox version description: What version of NetBox are you currently running? - placeholder: v3.3-beta2 + placeholder: v3.3.0 validations: required: true - type: dropdown diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index a08192940..5cafa685e 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -1,6 +1,6 @@ # NetBox v3.3 -## v3.3.0 (FUTURE) +## v3.3.0 (2022-08-17) ### Breaking Changes diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index 0dcde9cf6..22b1e1f02 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -29,7 +29,7 @@ django.utils.encoding.force_text = force_str # Environment setup # -VERSION = '3.3-beta2' +VERSION = '3.3.0' # Hostname HOSTNAME = platform.node() From 3b4dd051f2492aa05f84ca85ffb891ece831b210 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 14:11:47 -0400 Subject: [PATCH 241/245] PRVB --- docs/release-notes/version-3.3.md | 4 ++++ netbox/netbox/settings.py | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 5cafa685e..98004e2a5 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -1,5 +1,9 @@ # NetBox v3.3 +## v3.3.1 (FUTURE) + +--- + ## v3.3.0 (2022-08-17) ### Breaking Changes diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index 22b1e1f02..0edce8f69 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -29,7 +29,7 @@ django.utils.encoding.force_text = force_str # Environment setup # -VERSION = '3.3.0' +VERSION = '3.3.1-dev' # Hostname HOSTNAME = platform.node() From c7d6fe2d6236b691b65a73a63db65282bc342bbe Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Wed, 17 Aug 2022 15:37:48 -0400 Subject: [PATCH 242/245] Fixes #10053: Custom fields header should not be displayed when editing circuit terminations with no custom fields --- docs/release-notes/version-3.3.md | 4 ++++ .../templates/circuits/circuittermination_edit.html | 12 +++++++----- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 98004e2a5..e633e35de 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -2,6 +2,10 @@ ## v3.3.1 (FUTURE) +### Bug Fixes + +* [#10053](https://github.com/netbox-community/netbox/issues/10053) - Custom fields header should not be displayed when editing circuit terminations with no custom fields + --- ## v3.3.0 (2022-08-17) diff --git a/netbox/templates/circuits/circuittermination_edit.html b/netbox/templates/circuits/circuittermination_edit.html index 9c38a3c72..5196eddf2 100644 --- a/netbox/templates/circuits/circuittermination_edit.html +++ b/netbox/templates/circuits/circuittermination_edit.html @@ -49,10 +49,12 @@ {% render_field form.description %}
    -
    -
    -
    Custom Fields
    + {% if form.custom_fields %} +
    +
    +
    Custom Fields
    +
    + {% render_custom_fields form %}
    - {% render_custom_fields form %} -
    + {% endif %} {% endblock %} From 279253c486e4aff7f1471c93431c35eb91338237 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 18 Aug 2022 09:49:45 -0400 Subject: [PATCH 243/245] Fixes #10040: Fix exception when ordering prefixes by flat representation --- docs/release-notes/version-3.3.md | 1 + netbox/ipam/tables/ip.py | 15 +++------------ 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index e633e35de..222ba797b 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -4,6 +4,7 @@ ### Bug Fixes +* [#10040](https://github.com/netbox-community/netbox/issues/10040) - Fix exception when ordering prefixes by flat representation * [#10053](https://github.com/netbox-community/netbox/issues/10053) - Custom fields header should not be displayed when editing circuit terminations with no custom fields --- diff --git a/netbox/ipam/tables/ip.py b/netbox/ipam/tables/ip.py index 087d0de73..20e63fe55 100644 --- a/netbox/ipam/tables/ip.py +++ b/netbox/ipam/tables/ip.py @@ -32,15 +32,6 @@ PREFIX_LINK = """ {{ record.prefix }} """ -PREFIXFLAT_LINK = """ -{% load helpers %} -{% if record.pk %} - {{ record.prefix }} -{% else %} - {{ record.prefix }} -{% endif %} -""" - IPADDRESS_LINK = """ {% if record.pk %} {{ record.address }} @@ -229,9 +220,9 @@ class PrefixTable(TenancyColumnsMixin, NetBoxTable): export_raw=True, attrs={'td': {'class': 'text-nowrap'}} ) - prefix_flat = tables.TemplateColumn( - template_code=PREFIXFLAT_LINK, - attrs={'td': {'class': 'text-nowrap'}}, + prefix_flat = tables.Column( + accessor=Accessor('prefix'), + linkify=True, verbose_name='Prefix (Flat)', ) depth = tables.Column( From 9059c096278e9e278f457368268b45425d6058dd Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 18 Aug 2022 13:40:44 -0400 Subject: [PATCH 244/245] Refresh development docs --- docs/development/getting-started.md | 92 ++++++++--------- docs/development/index.md | 51 +++++++--- docs/development/models.md | 2 +- docs/development/release-checklist.md | 107 +++++++++++--------- docs/development/style-guide.md | 71 ++++++++----- docs/media/development/github.png | Bin 0 -> 112957 bytes docs/media/development/github_new_issue.png | Bin 0 -> 46534 bytes 7 files changed, 186 insertions(+), 137 deletions(-) create mode 100644 docs/media/development/github.png create mode 100644 docs/media/development/github_new_issue.png diff --git a/docs/development/getting-started.md b/docs/development/getting-started.md index dbbe8378d..38d521de6 100644 --- a/docs/development/getting-started.md +++ b/docs/development/getting-started.md @@ -4,12 +4,12 @@ Getting started with NetBox development is pretty straightforward, and should feel very familiar to anyone with Django development experience. There are a few things you'll need: -* A Linux system or environment +* A Linux system or compatible environment * A PostgreSQL server, which can be installed locally [per the documentation](../installation/1-postgresql.md) * A Redis server, which can also be [installed locally](../installation/2-redis.md) -* A supported version of Python +* Python 3.8 or later -### Fork the Repo +### 1. Fork the Repo Assuming you'll be working on your own fork, your first step will be to fork the [official git repository](https://github.com/netbox-community/netbox). (If you're a maintainer who's going to be working directly with the official repo, skip this step.) Click the "fork" button at top right (be sure that you've logged into GitHub first). @@ -21,7 +21,7 @@ Copy the URL provided in the dialog box. You can then clone your GitHub fork locally for development: -```no-highlight +```no-highlight hl_lines="1 9" $ git clone https://github.com/$username/netbox.git Cloning into 'netbox'... remote: Enumerating objects: 85949, done. @@ -38,90 +38,85 @@ CHANGELOG.md CONTRIBUTING.md LICENSE.txt netbox README.md scri The NetBox project utilizes three persistent git branches to track work: * `master` - Serves as a snapshot of the current stable release -* `develop` - All development on the upcoming stable release occurs here -* `feature` - Tracks work on an upcoming major release +* `develop` - All development on the upcoming stable (patch) release occurs here +* `feature` - Tracks work on an upcoming minor release -Typically, you'll base pull requests off of the `develop` branch, or off of `feature` if you're working on a new major release. **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 `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). -For example, assume that the current NetBox release is v3.1.1. Work applied to the `develop` branch will appear in v3.1.2, and work done under the `feature` branch will be included in the next minor release (v3.2.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. -### Enable Pre-Commit Hooks +### 2. Enable Pre-Commit Hooks NetBox ships with a [git pre-commit hook](https://githooks.com/) script that automatically checks for style compliance and missing database migrations prior to committing changes. This helps avoid erroneous commits that result in CI test failures. You are encouraged to enable it by creating a link to `scripts/git-hooks/pre-commit`: ```no-highlight -$ cd .git/hooks/ -$ ln -s ../../scripts/git-hooks/pre-commit +cd .git/hooks/ +ln -s ../../scripts/git-hooks/pre-commit ``` -### Create a Python Virtual Environment +### 3. Create a Python Virtual Environment A [virtual environment](https://docs.python.org/3/tutorial/venv.html) (or "venv" for short) is like a container for a set of Python packages. These allow you to build environments suited to specific projects without interfering with system packages or other projects. When installed per the documentation, NetBox uses a virtual environment in production. Create a virtual environment using the `venv` Python module: ```no-highlight -$ mkdir ~/.venv -$ python3 -m venv ~/.venv/netbox +mkdir ~/.venv +python3 -m venv ~/.venv/netbox ``` This will create a directory named `.venv/netbox/` in your home directory, which houses a virtual copy of the Python executable and its related libraries and tooling. When running NetBox for development, it will be run using the Python binary at `~/.venv/netbox/bin/python`. -!!! info "Where to Create Your Virtual Environments" - Keeping virtual environments in `~/.venv/` is a common convention but entirely optional: Virtual environments can be created almost wherever you please. Also consider using [`virtualenvwrapper`](https://virtualenvwrapper.readthedocs.io/en/stable/) to simplify the management of multiple venvs. +!!! tip "Virtual Environments" + Keeping virtual environments in `~/.venv/` is a common convention but entirely optional: Virtual environments can be created almost wherever you please. Also consider using [`virtualenvwrapper`](https://virtualenvwrapper.readthedocs.io/en/stable/) to simplify the management of multiple environments. Once created, activate the virtual environment: ```no-highlight -$ source ~/.venv/netbox/bin/activate -(netbox) $ +source ~/.venv/netbox/bin/activate ``` Notice that the console prompt changes to indicate the active environment. This updates the necessary system environment variables to ensure that any Python scripts are run within the virtual environment. -### Install Dependencies +### 4. Install Required Packages -With the virtual environment activated, install the project's required Python packages using the `pip` module: +With the virtual environment activated, install the project's required Python packages using the `pip` module. Required packages are defined in `requirements.txt`. Each line in this file specifies the name and specific version of a required package. ```no-highlight -(netbox) $ python -m pip install -r requirements.txt -Collecting Django==3.1 (from -r requirements.txt (line 1)) - Cache entry deserialization failed, entry ignored - Using cached https://files.pythonhosted.org/packages/2b/5a/4bd5624546912082a1bd2709d0edc0685f5c7827a278d806a20cf6adea28/Django-3.1-py3-none-any.whl -... +python -m pip install -r requirements.txt ``` -### Configure NetBox +### 5. Configure NetBox 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 * `DATABASE`: PostgreSQL database connection parameters -* `REDIS`: Redis configuration, if different from the defaults +* `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` * `DEVELOPER`: Set to `True` (this enables the creation of new database migrations) -### Start the Development Server +### 6. Start the Development Server -Django provides a lightweight, auto-updating HTTP/WSGI server for development use. It is started with the `runserver` management command: +Django provides a lightweight, auto-updating [HTTP/WSGI server](https://docs.djangoproject.com/en/stable/ref/django-admin/#runserver) for development use. It is started with the `runserver` management command: -```no-highlight +```no-highlight hl_lines="1" $ ./manage.py runserver -Watching for file changes with StatReloader Performing system checks... System check identified no issues (0 silenced). -February 18, 2022 - 20:29:57 -Django version 4.0.2, using settings 'netbox.settings' +August 18, 2022 - 15:17:52 +Django version 4.0.7, using settings 'netbox.settings' Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C. ``` -This ensures that your development environment is now complete and operational. Any changes you make to the code base will be automatically adapted by the development server. +This ensures that your development environment is now complete and operational. The development server will monitor the development environment and automatically reload in response to any changes made. -!!! info "IDE Integration" - Some IDEs, such as PyCharm, will integrate with Django's development server and allow you to run it directly within the IDE. This is strongly encouraged as it makes for a much more convenient development environment. +!!! tip "IDE Integration" + Some IDEs, such as the highly-recommended [PyCharm](https://www.jetbrains.com/pycharm/), will integrate with Django's development server and allow you to run it directly within the IDE. This is strongly encouraged as it makes for a much more convenient development environment. ## Populating Demo Data @@ -131,48 +126,51 @@ The demo data is provided in JSON format and loaded into an empty database using ## Running Tests -Prior to committing any substantial changes to the code base, be sure to run NetBox's test suite to catch any potential errors. Tests are run using the `test` management command, which employs Python's [`unittest`](https://docs.python.org/3/library/unittest.html#module-unittest) library. Remember to ensure the Python virtual environment is active before running this command. Also keep in mind that these commands are executed in the `netbox/` directory, not the root directory of the repository. +Prior to committing any substantial changes to the code base, be sure to run NetBox's test suite to catch potential errors. Tests are run using the `test` management command, which employs Python's [`unittest`](https://docs.python.org/3/library/unittest.html#module-unittest) library. Remember to ensure that the Python virtual environment is active before running this command. Also keep in mind that these commands are executed in the `netbox/` directory, not the root directory of the repository. To avoid potential issues with your local configuration file, set the `NETBOX_CONFIGURATION` to point to the packaged test configuration at `netbox/configuration_testing.py`. This will handle things like ensuring that the dummy plugin is enabled for comprehensive testing. ```no-highlight -$ export NETBOX_CONFIGURATION=netbox.configuration_testing -$ cd netbox/ -$ python manage.py test +export NETBOX_CONFIGURATION=netbox.configuration_testing +cd netbox/ +python manage.py test ``` In cases where you haven't made any changes to the database schema (which is typical), you can append the `--keepdb` argument to this command to reuse the test database between runs. This cuts down on the time it takes to run the test suite since the database doesn't have to be rebuilt each time. (Note that this argument will cause errors if you've modified any model fields since the previous test run.) ```no-highlight -$ python manage.py test --keepdb +python manage.py test --keepdb ``` You can also reduce testing time by enabling parallel test execution with the `--parallel` flag. (By default, this will run as many parallel tests as you have processors. To avoid sluggishness, it's a good idea to specify a lower number of parallel tests.) This flag can be combined with `--keepdb`, although if you encounter any strange errors, try running the test suite again with parallelization disabled. ```no-highlight -$ python manage.py test --parallel +python manage.py test --parallel ``` Finally, it's possible to limit the run to a specific set of tests, specified by their Python path. For example, to run only IPAM and DCIM view tests: ```no-highlight -$ python manage.py test dcim.tests.test_views ipam.tests.test_views +python manage.py test dcim.tests.test_views ipam.tests.test_views ``` This is handy for instances where just a few tests are failing and you want to re-run them individually. +!!! info + NetBox uses [django-rich](https://github.com/adamchainz/django-rich) to enhance Django's default `test` management command. + ## Submitting Pull Requests -Once you're happy with your work and have verified that all tests pass, commit your changes and push it upstream to your fork. Always provide descriptive (but not excessively verbose) commit messages. When working on a specific issue, be sure to prefix your commit message with the word "Fixes" or "Closes" and the issue number (with a hash mark). This tells GitHub to automatically close the referenced issue once the commit has been merged. +Once you're happy with your work and have verified that all tests pass, commit your changes and push it upstream to your fork. Always provide descriptive (but not excessively verbose) commit messages. Be sure to prefix your commit message with the word "Fixes" or "Closes" and the relevant issue number (with a hash mark). This tells GitHub to automatically close the referenced issue once the commit has been merged. ```no-highlight -$ git commit -m "Closes #1234: Add IPv5 support" -$ git push origin +git commit -m "Closes #1234: Add IPv5 support" +git push origin ``` Once your fork has the new commit, submit a [pull request](https://github.com/netbox-community/netbox/compare) to the NetBox repo to propose the changes. Be sure to provide a detailed accounting of the changes being made and the reasons for doing so. Once submitted, a maintainer will review your pull request and either merge it or request changes. If changes are needed, you can make them via new commits to your fork: The pull request will update automatically. -!!! note "Remember to Open an Issue First" +!!! warning Remember, pull requests are permitted only for **accepted** issues. If an issue you want to work on hasn't been approved by a maintainer yet, it's best to avoid risking your time and effort on a change that might not be accepted. (The one exception to this is trivial changes to the documentation or other non-critical resources.) diff --git a/docs/development/index.md b/docs/development/index.md index 85762d0fe..0d570abe6 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -1,22 +1,18 @@ # NetBox Development -NetBox is maintained as a [GitHub project](https://github.com/netbox-community/netbox) under the Apache 2 license. Users are encouraged to submit GitHub issues for feature requests and bug reports, however we are very selective about pull requests. Each pull request must be preceded by an **approved** issue. Please see the `CONTRIBUTING` guide for more direction on contributing to NetBox. +Thanks for your interest in contributing to NetBox! This introduction covers a few important things to know before you get started. -## Communication +## The Code -There are several official forums for communication among the developers and community members: +NetBox and many of its related projects are maintained on [GitHub](https://github.com/netbox-community/netbox). GitHub also serves as one of our primary discussion forums. While all the code and discussion is publicly accessible, you'll need register for a [free GitHub account](https://github.com/signup) to engage in participation. Most people begin by [forking](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the NetBox repository under their own GitHub account to begin working on the code. -* [GitHub issues](https://github.com/netbox-community/netbox/issues) - All feature requests, bug reports, and other substantial changes to the code base **must** be documented in a GitHub issue. -* [GitHub discussions](https://github.com/netbox-community/netbox/discussions) - The preferred forum for general discussion and support issues. Ideal for shaping a feature request prior to submitting an issue. -* [#netbox on NetDev Community Slack](https://netdev.chat/) - Good for quick chats. Avoid any discussion that might need to be referenced later on, as the chat history is not retained long. +![GitHub](../media/development/github.png) -## Governance +There are three permanent branches in the repository: -NetBox follows the [benevolent dictator](http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel) model of governance, with [Jeremy Stretch](https://github.com/jeremystretch) ultimately responsible for all changes to the code base. While community contributions are welcomed and encouraged, the lead maintainer's primary role is to ensure the project's long-term maintainability and continued focus on its primary functions. - -## Project Structure - -All development of the current NetBox release occurs in the `develop` branch; releases are packaged from the `master` branch. The `master` branch should _always_ represent the current stable release in its entirety, such that installing NetBox by either downloading a packaged release or cloning the `master` branch provides the same code base. Only pull requests representing new releases should be merged into `master`. +* `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). NetBox components are arranged into Django apps. Each app holds the models, views, and other resources relevant to a particular function: @@ -31,3 +27,34 @@ NetBox components are arranged into Django apps. Each app holds the models, view * `wireless`: Wireless links and LANs All core functionality is stored within the `netbox/` subdirectory. HTML templates are stored in a common `templates/` directory, with model- and view-specific templates arranged by app. Documentation is kept in the `docs/` root directory. + +## Proposing Changes + +All substantial changes made to the code base are tracked using [GitHub issues](https://docs.github.com/en/issues). Feature requests, bug reports, and similar proposals must all be filed as issues and approved by a maintainer before work begins. This ensures that all changes to the code base are properly documented for future reference. + +To submit a new feature request or bug report for NetBox, select and complete the appropriate [issue template](https://github.com/netbox-community/netbox/issues/new/choose). Once your issue has been approved, you're welcome to submit a [pull request](https://docs.github.com/en/pull-requests) containing your proposed changes. + +![Opening a new GitHub issue](../media/development/github_new_issue.png) + +Check out our [issue intake policy](https://github.com/netbox-community/netbox/wiki/Issue-Intake-Policy) for an overview of the issue triage and approval processes. + +!!! tip + Avoid starting work on a proposal before it has been accepted. Not all proposed changes will be accepted, and we'd hate for you to waste time working on code that might not make it into the project. + +## Getting Help + +There are two primary forums for getting assistance with NetBox development: + +* [GitHub discussions](https://github.com/netbox-community/netbox/discussions) - The preferred forum for general discussion and support issues. Ideal for shaping a feature requests prior to submitting an issue. +* [#netbox on NetDev Community Slack](https://netdev.chat/) - Good for quick chats. Avoid any discussion that might need to be referenced later on, as the chat history is not retained indefinitely. + +!!! note + Don't use GitHub issues to ask for help: These are reserved for proposed code changes only. + +## Governance + +NetBox follows the [benevolent dictator](http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel) model of governance, with [Jeremy Stretch](https://github.com/jeremystretch) ultimately responsible for all changes to the code base. While community contributions are welcomed and encouraged, the lead maintainer's primary role is to ensure the project's long-term maintainability and continued focus on its primary functions. + +## 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. diff --git a/docs/development/models.md b/docs/development/models.md index 3b03c8935..01070fa3d 100644 --- a/docs/development/models.md +++ b/docs/development/models.md @@ -2,7 +2,7 @@ ## Model Types -A NetBox model represents a discrete object type such as a device or IP address. Each model is defined as a Python class and has its own SQL table. All NetBox data models can be categorized by type. +A NetBox model represents a discrete object type such as a device or IP address. Per [Django convention](https://docs.djangoproject.com/en/stable/topics/db/models/), each model is defined as a Python class and has its own SQL table. All NetBox data models can be categorized by type. The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/) framework can be used to reference models within the database. A ContentType instance references a model by its `app_label` and `name`: For example, the Site model is referred to as `dcim.site`. The content type combined with an object's primary key form a globally unique identifier for the object (e.g. `dcim.site:123`). diff --git a/docs/development/release-checklist.md b/docs/development/release-checklist.md index 17c27948d..efb0f44b9 100644 --- a/docs/development/release-checklist.md +++ b/docs/development/release-checklist.md @@ -1,62 +1,62 @@ # Release Checklist -## Minor Version Bumps +This documentation describes the process of packaging and publishing a new NetBox release. There are three types of release: -### Address Pinned Dependencies +* Major release (e.g. v2.11 to v3.0) +* Minor release (e.g. v3.2 to v3.3) +* Patch release (e.g. v3.3.0 to v3.3.1) -Check `base_requirements.txt` for any dependencies pinned to a specific version, and upgrade them to their most stable release (where possible). +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. -### Link to the Release Notes Page +## Minor Version Releases -Add the release notes (`/docs/release-notes/X.Y.md`) to the table of contents within `mkdocs.yml`, and add a summary of the major changes to `index.md`. +### Address Constrained Dependencies -### Manually Perform a New Install - -Install `mkdocs` in your local environment, then start the documentation server: - -```no-highlight -$ pip install -r docs/requirements.txt -$ mkdocs serve -``` - -Follow these instructions to perform a new installation of NetBox. 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. - -### Close the Release Milestone - -Close the release milestone on GitHub after ensuring there are no remaining open issues associated with it. - -### Merge the Release Branch - -Submit a pull request to merge the `feature` branch into the `develop` branch in preparation for its release. - ---- - -## All Releases - -### Update Requirements - -Required Python packages are maintained in two files. `base_requirements.txt` contains a list of all the packages required by NetBox. Some of them may be pinned to a specific version of the package due to a known issue. For example: +Sometimes it becomes necessary to constrain dependencies to a particular version, e.g. to work around a bug in a newer release or to avoid a breaking change that we have yet to accommodate. (Another common example is to limit the upstream Django release.) For example: ``` # https://github.com/encode/django-rest-framework/issues/6053 djangorestframework==3.8.1 ``` -The other file is `requirements.txt`, which lists each of the required packages pinned to its current stable version. When NetBox is installed, the Python environment is configured to match this file. This helps ensure that a new release of a dependency doesn't break NetBox. +These version constraints are added to `base_requirements.txt` to ensure that newer packages are not installed when updating the pinned dependencies in `requirements.txt` (see the [Update Requirements](#update-requirements) section below). Before each new minor version of NetBox is released, all such constraints on dependent packages should be addressed if feasible. This guards against the collection of stale constraints over time. -Every release should refresh `requirements.txt` so that it lists the most recent stable release of each package. To do this: +### Close the Release Milestone -1. Create a new virtual environment. -2. Install the latest version of all required packages `pip install -U -r base_requirements.txt`). -3. Run all tests and check that the UI and API function as expected. -4. Review each requirement's release notes for any breaking or otherwise noteworthy changes. -5. Update the package versions in `requirements.txt` as appropriate. +Close the [release milestone](https://github.com/netbox-community/netbox/milestones) on GitHub after ensuring there are no remaining open issues associated with it. -In cases where upgrading a dependency to its most recent release is breaking, it should be pinned to its current minor version in `base_requirements.txt` (with an explanatory comment) and revisited for the next major NetBox release. +### Update the Release Notes -### Verify CI Build Status +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`. -Ensure that continuous integration testing on the `develop` branch is completing successfully. +### Manually Perform a New Install + +Start the documentation server and navigate to the current version of the installation docs: + +```no-highlight +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. + +### Merge the Release Branch + +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. + +--- + +## Patch Releases + +### Update Requirements + +Before each release, update each of NetBox's Python dependencies to its most recent stable version. These are defined in `requirements.txt`, which is updated from `base_requirements.txt` using `pip`. To do this: + +1. Upgrade the installed version of all required packages in your environment (`pip install -U -r base_requirements.txt`). +2. Run all tests and check that the UI and API function as expected. +3. Review each requirement's release notes for any breaking or otherwise noteworthy changes. +4. Update the package versions in `requirements.txt` as appropriate. + +In cases where upgrading a dependency to its most recent release is breaking, it should be constrained to its current minor version in `base_requirements.txt` with an explanatory comment and revisited for the next major NetBox release (see the [Address Constrained Dependencies](#address-constrained-dependencies) section above). ### Update Version and Changelog @@ -64,28 +64,35 @@ Ensure that continuous integration testing on the `develop` branch is completing * Update the example version numbers in the feature request and bug report templates under `.github/ISSUE_TEMPLATES/`. * Replace the "FUTURE" placeholder in the release notes with the current date. -Commit these changes to the `develop` branch. +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 proceding with the release. ### Submit a Pull Request -Submit a pull request title **"Release vX.Y.Z"** to merge the `develop` branch into `master`. Copy the documented release notes into the pull request's body. +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. -Once CI has completed on the PR, merge it. +Once CI has completed on the PR, merge it. This effects a new release in the `master` branch. ### Create a New Release -Draft a [new release](https://github.com/netbox-community/netbox/releases/new) with the following parameters. +Create a [new release](https://github.com/netbox-community/netbox/releases/new) on GitHub with the following parameters. -* **Tag:** Current version (e.g. `v2.9.9`) +* **Tag:** Current version (e.g. `v3.3.1`) * **Target:** `master` -* **Title:** Version and date (e.g. `v2.9.9 - 2020-11-09`) +* **Title:** Version and date (e.g. `v3.3.1 - 2022-08-25`) +* **Description:** Copy from the pull request body -Copy the description from the pull request to the release. +Once created, the release will become available for users to install. ### Update the Development Version -On the `develop` branch, update `VERSION` in `settings.py` to point to the next release. For example, if you just released v2.9.9, set: +On the `develop` branch, update `VERSION` in `settings.py` to point to the next release. For example, if you just released v3.3.1, set: ``` -VERSION = 'v2.9.10-dev' +VERSION = 'v3.3.2-dev' ``` + +Commit this change with the comment "PRVB" (for _post-release version bump_) and push the commit upstream. diff --git a/docs/development/style-guide.md b/docs/development/style-guide.md index 2a6d86ab0..283ad698c 100644 --- a/docs/development/style-guide.md +++ b/docs/development/style-guide.md @@ -1,34 +1,53 @@ # Style Guide -NetBox generally follows the [Django style guide](https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/coding-style/), which is itself based on [PEP 8](https://www.python.org/dev/peps/pep-0008/). [Pycodestyle](https://github.com/pycqa/pycodestyle) is used to validate code formatting, ignoring certain violations. See `scripts/cibuild.sh` for details. +NetBox generally follows the [Django style guide](https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/coding-style/), which is itself based on [PEP 8](https://www.python.org/dev/peps/pep-0008/). [Pycodestyle](https://github.com/pycqa/pycodestyle) is used to validate code formatting, ignoring certain violations. -## PEP 8 Exceptions +## Code -* Wildcard imports (for example, `from .constants import *`) are acceptable under any of the following conditions: - * The library being import contains only constant declarations (e.g. `constants.py`) - * The library being imported explicitly defines `__all__` +### General Guidance -* Maximum line length is 120 characters (E501) - * This does not apply to HTML templates or to automatically generated code (e.g. database migrations). +* When in doubt, remain consistent: It is better to be consistently incorrect than inconsistently correct. If you notice in the course of unrelated work a pattern that should be corrected, continue to follow the pattern for now and submit a separate bug report so that the entire code base can be evaluated at a later point. -* Line breaks are permitted following binary operators (W504) +* Prioritize readability over concision. Python is a very flexible language that typically offers several multiple options for expressing a given piece of logic, but some may be more friendly to the reader than others. (List comprehensions are particularly vulnerable to over-optimization.) Always remain considerate of the future reader who may need to interpret your code without the benefit of the context within which you are writing it. -## Enforcing Code Style +* Include a newline at the end of every file. -The `pycodestyle` utility (previously `pep8`) is used by the CI process to enforce code style. It is strongly recommended to include as part of your commit process. A git commit hook is provided in the source at `scripts/git-hooks/pre-commit`. Linking to this script from `.git/hooks/` will invoke `pycodestyle` prior to every commit attempt and abort if the validation fails. +* No easter eggs. While they can be fun, NetBox must be considered as a business-critical tool. The potential, however minor, for introducing a bug caused by unnecessary code is best avoided entirely. -``` -$ cd .git/hooks/ -$ ln -s ../../scripts/git-hooks/pre-commit -``` +* Constants (variables which do not change) should be declared in `constants.py` within each app. Wildcard imports from the file are acceptable. -To invoke `pycodestyle` manually, run: +* Every model must have a [docstring](https://peps.python.org/pep-0257/). Every custom method should include an explanation of its function. + +* Nested API serializers generate minimal representations of an object. These are stored separately from the primary serializers to avoid circular dependencies. Always import nested serializers from other apps directly. For example, from within the DCIM app you would write `from ipam.api.nested_serializers import NestedIPAddressSerializer`. + +### PEP 8 Exceptions + +NetBox ignores certain PEP8 assertions. These are listed below. + +#### Wildcard Imports + +Wildcard imports (for example, `from .constants import *`) are acceptable under any of the following conditions: + +* The library being import contains only constant declarations (e.g. `constants.py`) +* The library being imported explicitly defines `__all__` + +#### Maximum Line Length (E501) + +NetBox does not restrict lines to a maximum length of 79 characters. We use a maximum line length of 120 characters, however this is not enforced by CI. The maximum length does not apply to HTML templates or to automatically generated code (e.g. database migrations). + +#### Line Breaks Following Binary Operators (W504) + +Line breaks are permitted following binary operators. + +### Enforcing Code Style + +The [`pycodestyle`](https://pypi.org/project/pycodestyle/) utility (formerly `pep8`) is used by the CI process to enforce code style. A [pre-commit hook](./getting-started.md#2-enable-pre-commit-hooks) which runs this automatically is included with NetBox. To invoke `pycodestyle` manually, run: ``` pycodestyle --ignore=W504,E501 netbox/ ``` -## Introducing New Dependencies +### Introducing New Dependencies The introduction of a new dependency is best avoided unless it is absolutely necessary. For small features, it's generally preferable to replicate functionality within the NetBox code base rather than to introduce reliance on an external project. This reduces both the burden of tracking new releases and our exposure to outside bugs and supply chain attacks. @@ -39,24 +58,22 @@ If there's a strong case for introducing a new dependency, it must meet the foll * It must be actively maintained, with no longer than one year between releases. * It must be available via the [Python Package Index](https://pypi.org/) (PyPI). -When adding a new dependency, a short description of the package and the URL of its code repository must be added to `base_requirements.txt`. Additionally, a line specifying the package name pinned to the current stable release must be added to `requirements.txt`. This ensures that NetBox will install only the known-good release and simplify support efforts. +When adding a new dependency, a short description of the package and the URL of its code repository must be added to `base_requirements.txt`. Additionally, a line specifying the package name pinned to the current stable release must be added to `requirements.txt`. This ensures that NetBox will install only the known-good release. -## General Guidance +## Written Works -* When in doubt, remain consistent: It is better to be consistently incorrect than inconsistently correct. If you notice in the course of unrelated work a pattern that should be corrected, continue to follow the pattern for now and submit a separate bug report so that the entire code base can be evaluated at a later point. +### General Guidance -* Prioritize readability over concision. Python is a very flexible language that typically offers several options for expressing a given piece of logic, but some may be more friendly to the reader than others. (List comprehensions are particularly vulnerable to over-optimization.) Always remain considerate of the future reader who may need to interpret your code without the benefit of the context within which you are writing it. +* Written material must always meet a reasonable professional standard, with proper grammar, spelling, and punctuation. -* No easter eggs. While they can be fun, NetBox must be considered as a business-critical tool. The potential, however minor, for introducing a bug caused by unnecessary logic is best avoided entirely. +* Use two line breaks between paragraphs. -* Constants (variables which generally do not change) should be declared in `constants.py` within each app. Wildcard imports from the file are acceptable. +* Use only a single space between sentences. -* Every model should have a docstring. Every custom method should include an explanation of its function. +* All documentation is to be written in [Markdown](../reference/markdown.md), with modest amounts of HTML permitted where needed to overcome technical limitations. -* Nested API serializers generate minimal representations of an object. These are stored separately from the primary serializers to avoid circular dependencies. Always import nested serializers from other apps directly. For example, from within the DCIM app you would write `from ipam.api.nested_serializers import NestedIPAddressSerializer`. +### Branding -## Branding - -* When referring to NetBox in writing, use the proper form "NetBox," with the letters N and B capitalized. The lowercase form "netbox" should be used in code, filenames, etc. But never "Netbox" or any other deviation. +* When referring to NetBox in writing, use the proper form "NetBox," with the letters N and B capitalized. The lowercase form "netbox" should be used in code, filenames, etc. but never "Netbox" or any other deviation. * There is an SVG form of the NetBox logo at [docs/netbox_logo.svg](../netbox_logo.svg). It is preferred to use this logo for all purposes as it scales to arbitrary sizes without loss of resolution. If a raster image is required, the SVG logo should be converted to a PNG image of the prescribed size. diff --git a/docs/media/development/github.png b/docs/media/development/github.png new file mode 100644 index 0000000000000000000000000000000000000000..6ac58f5fb2afbe24a1ed642907d946c6d2936a96 GIT binary patch literal 112957 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 o#uWDohEwk-lq+&NKIiP1pP#m}Z+1uc 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≻gw5&lrYyOO5K5{K0r71HCG(nVvFauV}a- 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 literal 0 HcmV?d00001 From 804c064a7efd5dac8a6df0850b878d35bae587ef Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 18 Aug 2022 15:19:34 -0400 Subject: [PATCH 245/245] Closes #10061: Replicate type when cloning L2VPN instances --- docs/release-notes/version-3.3.md | 4 ++++ netbox/ipam/models/l2vpn.py | 2 ++ 2 files changed, 6 insertions(+) diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md index 222ba797b..382d6c29e 100644 --- a/docs/release-notes/version-3.3.md +++ b/docs/release-notes/version-3.3.md @@ -2,6 +2,10 @@ ## v3.3.1 (FUTURE) +### Enhancements + +* [#10061](https://github.com/netbox-community/netbox/issues/10061) - Replicate type when cloning L2VPN instances + ### Bug Fixes * [#10040](https://github.com/netbox-community/netbox/issues/10040) - Fix exception when ordering prefixes by flat representation diff --git a/netbox/ipam/models/l2vpn.py b/netbox/ipam/models/l2vpn.py index 3c08b5f48..0e948b18e 100644 --- a/netbox/ipam/models/l2vpn.py +++ b/netbox/ipam/models/l2vpn.py @@ -53,6 +53,8 @@ class L2VPN(NetBoxModel): to='tenancy.ContactAssignment' ) + clone_fields = ('type',) + class Meta: ordering = ('name', 'identifier') verbose_name = 'L2VPN'