Closed #9763: Treat IP ranges as fully populated (#19064)

jeremystretch · web-flow · commit f8f2ad1d148c · 2025-04-09T07:30:11.000-07:00
diff --git a/docs/models/ipam/iprange.md b/docs/models/ipam/iprange.md
@@ -2,6 +2,12 @@
 
 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).
 
+Each IP range can be marked as populated, which instructs NetBox to treat the range as though every IP address within it has been created (even though these individual IP addresses don't actually exist in the database). This can be helpful in scenarios where the management of a subset of IP addresses has been deferred to an external system of record, such as a DHCP server. NetBox will prohibit the creation of individual IP addresses within a range that has been marked as populated.
+
+An IP range can also be marked as utilized. This will cause its utilization to always be reported as 100% when viewing the range or when calculating the utilization of a parent prefix. (If not enabled, a range's utilization is calculated based on the number of IP addresses which have been created within it.)
+
+Typically, IP ranges marked as populated should also be marked as utilized, although there may be scenarios where this is undesirable (e.g. when reclaiming old IP space). An IP range which has been marked as populated but _not_ marked as utilized will always report a utilization of 0%, as it cannot contain child IP addresses.
+
 ## Fields
 
 ### VRF
@@ -29,6 +35,12 @@ The IP range's operational status. Note that the status of a range does _not_ ha
 !!! tip
     Additional statuses may be defined by setting `IPRange.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter.
 
+### Mark Populated
+
+!!! note "This field was added in NetBox v4.3."
+
+If enabled, NetBox will treat this IP range as being fully populated when calculating available IP space. It will also prevent the creation of IP addresses which fall within the declared range (and assigned VRF, if any).
+
 ### Mark Utilized
 
 If enabled, the IP range will be considered 100% utilized regardless of how many IP addresses are defined within it. This is useful for documenting DHCP ranges, for example.
diff --git a/netbox/ipam/api/serializers_/ip.py b/netbox/ipam/api/serializers_/ip.py
@@ -147,7 +147,8 @@ class Meta:
         fields = [
             'id', 'url', 'display_url', 'display', 'family', 'start_address', 'end_address', 'size', 'vrf', 'tenant',
             'status', 'role', 'description', 'comments', 'tags', 'custom_fields', 'created', 'last_updated',
-            'mark_utilized', 'description', 'comments', 'tags', 'custom_fields', 'created', 'last_updated',
+            'mark_populated', 'mark_utilized', 'description', 'comments', 'tags', 'custom_fields', 'created',
+            'last_updated',
         ]
         brief_fields = ('id', 'url', 'display', 'family', 'start_address', 'end_address', 'description')
 
diff --git a/netbox/ipam/filtersets.py b/netbox/ipam/filtersets.py
@@ -478,7 +478,7 @@ class IPRangeFilterSet(TenancyFilterSet, NetBoxModelFilterSet):
 
     class Meta:
         model = IPRange
-        fields = ('id', 'mark_utilized', 'size', 'description')
+        fields = ('id', 'mark_populated', 'mark_utilized', 'size', 'description')
 
     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
@@ -296,6 +296,11 @@ class IPRangeBulkEditForm(NetBoxModelBulkEditForm):
         queryset=Role.objects.all(),
         required=False
     )
+    mark_populated = forms.NullBooleanField(
+        required=False,
+        widget=BulkEditNullBooleanSelect(),
+        label=_('Treat as populated')
+    )
     mark_utilized = forms.NullBooleanField(
         required=False,
         widget=BulkEditNullBooleanSelect(),
diff --git a/netbox/ipam/forms/bulk_import.py b/netbox/ipam/forms/bulk_import.py
@@ -268,8 +268,8 @@ class IPRangeImportForm(NetBoxModelImportForm):
     class Meta:
         model = IPRange
         fields = (
-            'start_address', 'end_address', 'vrf', 'tenant', 'status', 'role', 'mark_utilized', 'description',
-            'comments', 'tags',
+            'start_address', 'end_address', 'vrf', 'tenant', 'status', 'role', 'mark_populated', 'mark_utilized',
+            'description', 'comments', 'tags',
         )
 
 
diff --git a/netbox/ipam/forms/filtersets.py b/netbox/ipam/forms/filtersets.py
@@ -266,7 +266,7 @@ class IPRangeFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm):
     model = IPRange
     fieldsets = (
         FieldSet('q', 'filter_id', 'tag'),
-        FieldSet('family', 'vrf_id', 'status', 'role_id', 'mark_utilized', name=_('Attributes')),
+        FieldSet('family', 'vrf_id', 'status', 'role_id', 'mark_populated', 'mark_utilized', name=_('Attributes')),
         FieldSet('tenant_group_id', 'tenant_id', name=_('Tenant')),
     )
     family = forms.ChoiceField(
@@ -291,6 +291,13 @@ class IPRangeFilterForm(TenancyFilterForm, NetBoxModelFilterSetForm):
         null_option='None',
         label=_('Role')
     )
+    mark_populated = forms.NullBooleanField(
+        required=False,
+        label=_('Treat as populated'),
+        widget=forms.Select(
+            choices=BOOLEAN_WITH_BLANK_CHOICES
+        )
+    )
     mark_utilized = forms.NullBooleanField(
         required=False,
         label=_('Treat as fully utilized'),
diff --git a/netbox/ipam/forms/model_forms.py b/netbox/ipam/forms/model_forms.py
@@ -257,17 +257,17 @@ class IPRangeForm(TenancyForm, NetBoxModelForm):
 
     fieldsets = (
         FieldSet(
-            'vrf', 'start_address', 'end_address', 'role', 'status', 'mark_utilized', 'description', 'tags',
-            name=_('IP Range')
+            'vrf', 'start_address', 'end_address', 'role', 'status', 'mark_populated', 'mark_utilized', 'description',
+            'tags', name=_('IP Range')
         ),
         FieldSet('tenant_group', 'tenant', name=_('Tenancy')),
     )
 
     class Meta:
         model = IPRange
         fields = [
-            'vrf', 'start_address', 'end_address', 'status', 'role', 'tenant_group', 'tenant', 'mark_utilized',
-            'description', 'comments', 'tags',
+            'vrf', 'start_address', 'end_address', 'status', 'role', 'tenant_group', 'tenant', 'mark_populated',
+            'mark_utilized', 'description', 'comments', 'tags',
         ]
 
 
diff --git a/netbox/ipam/migrations/0078_iprange_mark_utilized.py b/netbox/ipam/migrations/0078_iprange_mark_utilized.py
@@ -0,0 +1,16 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('ipam', '0077_vlangroup_tenant'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='iprange',
+            name='mark_populated',
+            field=models.BooleanField(default=False),
+        ),
+    ]
diff --git a/netbox/ipam/models/ip.py b/netbox/ipam/models/ip.py
@@ -383,14 +383,15 @@ def get_child_prefixes(self):
         else:
             return Prefix.objects.filter(prefix__net_contained=str(self.prefix), vrf=self.vrf)
 
-    def get_child_ranges(self):
+    def get_child_ranges(self, **kwargs):
         """
         Return all IPRanges within this Prefix and VRF.
         """
         return IPRange.objects.filter(
             vrf=self.vrf,
             start_address__net_host_contained=str(self.prefix),
-            end_address__net_host_contained=str(self.prefix)
+            end_address__net_host_contained=str(self.prefix),
+            **kwargs
         )
 
     def get_child_ips(self):
@@ -407,15 +408,14 @@ def get_available_ips(self):
         """
         Return all available IPs within this prefix as an IPSet.
         """
-        if self.mark_utilized:
-            return netaddr.IPSet()
-
         prefix = netaddr.IPSet(self.prefix)
-        child_ips = netaddr.IPSet([ip.address.ip for ip in self.get_child_ips()])
-        child_ranges = []
-        for iprange in self.get_child_ranges():
-            child_ranges.append(iprange.range)
-        available_ips = prefix - child_ips - netaddr.IPSet(child_ranges)
+        child_ips = netaddr.IPSet([
+            ip.address.ip for ip in self.get_child_ips()
+        ])
+        child_ranges = netaddr.IPSet([
+            iprange.range for iprange in self.get_child_ranges().filter(mark_populated=True)
+        ])
+        available_ips = prefix - child_ips - child_ranges
 
         # IPv6 /127's, pool, or IPv4 /31-/32 sets are fully usable
         if (self.family == 6 and self.prefix.prefixlen >= 127) or self.is_pool or (
@@ -433,6 +433,7 @@ def get_available_ips(self):
             # For IPv6 prefixes, omit the Subnet-Router anycast address
             # per RFC 4291
             available_ips -= netaddr.IPSet([netaddr.IPAddress(self.prefix.first)])
+
         return available_ips
 
     def get_first_available_ip(self):
@@ -461,9 +462,11 @@ def get_utilization(self):
             utilization = float(child_prefixes.size) / self.prefix.size * 100
         else:
             # Compile an IPSet to avoid counting duplicate IPs
-            child_ips = netaddr.IPSet(
-                [_.range for _ in self.get_child_ranges()] + [_.address.ip for _ in self.get_child_ips()]
-            )
+            child_ips = netaddr.IPSet()
+            for iprange in self.get_child_ranges().filter(mark_utilized=True):
+                child_ips.add(iprange.range)
+            for ip in self.get_child_ips():
+                child_ips.add(ip.address.ip)
 
             prefix_size = self.prefix.size
             if self.prefix.version == 4 and self.prefix.prefixlen < 31 and not self.is_pool:
@@ -519,14 +522,19 @@ class IPRange(ContactsMixin, PrimaryModel):
         null=True,
         help_text=_('The primary function of this range')
     )
+    mark_populated = models.BooleanField(
+        verbose_name=_('mark populated'),
+        default=False,
+        help_text=_("Prevent the creation of IP addresses within this range")
+    )
     mark_utilized = models.BooleanField(
         verbose_name=_('mark utilized'),
         default=False,
-        help_text=_("Treat as fully utilized")
+        help_text=_("Report space as 100% utilized")
     )
 
     clone_fields = (
-        'vrf', 'tenant', 'status', 'role', 'description',
+        'vrf', 'tenant', 'status', 'role', 'description', 'mark_populated', 'mark_utilized',
     )
 
     class Meta:
@@ -663,6 +671,9 @@ def get_available_ips(self):
         """
         Return all available IPs within this range as an IPSet.
         """
+        if self.mark_populated:
+            return netaddr.IPSet()
+
         range = netaddr.IPRange(self.start_address.ip, self.end_address.ip)
         child_ips = netaddr.IPSet([ip.address.ip for ip in self.get_child_ips()])
 
@@ -875,6 +886,20 @@ def clean(self):
                         )
                     })
 
+            # Disallow the creation of IPAddresses within an IPRange with mark_populated=True
+            parent_range = IPRange.objects.filter(
+                start_address__lte=self.address,
+                end_address__gte=self.address,
+                vrf=self.vrf,
+                mark_populated=True
+            ).first()
+            if parent_range:
+                raise ValidationError({
+                    'address': _(
+                        "Cannot create IP address {ip} inside range {range}."
+                    ).format(ip=self.address, range=parent_range)
+                })
+
         if self._original_assigned_object_id and self._original_assigned_object_type_id:
             parent = getattr(self.assigned_object, 'parent_object', None)
             ct = ObjectType.objects.get_for_id(self._original_assigned_object_type_id)
diff --git a/netbox/ipam/tables/ip.py b/netbox/ipam/tables/ip.py
@@ -10,6 +10,7 @@
 
 __all__ = (
     'AggregateTable',
+    'AnnotatedIPAddressTable',
     'AssignedIPAddressesTable',
     'IPAddressAssignTable',
     'IPAddressTable',
@@ -268,6 +269,10 @@ class IPRangeTable(TenancyColumnsMixin, NetBoxTable):
         verbose_name=_('Role'),
         linkify=True
     )
+    mark_populated = columns.BooleanColumn(
+        verbose_name=_('Marked Populated'),
+        false_mark=None
+    )
     mark_utilized = columns.BooleanColumn(
         verbose_name=_('Marked Utilized'),
         false_mark=None
@@ -288,7 +293,8 @@ class Meta(NetBoxTable.Meta):
         model = IPRange
         fields = (
             'pk', 'id', 'start_address', 'end_address', 'size', 'vrf', 'status', 'role', 'tenant', 'tenant_group',
-            'mark_utilized', 'utilization', 'description', 'comments', 'tags', 'created', 'last_updated',
+            'mark_populated', 'mark_utilized', 'utilization', 'description', 'comments', 'tags', 'created',
+            'last_updated',
         )
         default_columns = (
             'pk', 'start_address', 'end_address', 'size', 'vrf', 'status', 'role', 'tenant', 'description',
@@ -303,8 +309,8 @@ class Meta(NetBoxTable.Meta):
 #
 
 class IPAddressTable(TenancyColumnsMixin, NetBoxTable):
-    address = tables.TemplateColumn(
-        template_code=IPADDRESS_LINK,
+    address = tables.Column(
+        linkify=True,
         verbose_name=_('IP Address')
     )
     vrf = tables.TemplateColumn(
@@ -369,6 +375,16 @@ class Meta(NetBoxTable.Meta):
         }
 
 
+class AnnotatedIPAddressTable(IPAddressTable):
+    address = tables.TemplateColumn(
+        template_code=IPADDRESS_LINK,
+        verbose_name=_('IP Address')
+    )
+
+    class Meta(IPAddressTable.Meta):
+        pass
+
+
 class IPAddressAssignTable(NetBoxTable):
     address = tables.TemplateColumn(
         template_code=IPADDRESS_ASSIGN_LINK,
diff --git a/netbox/ipam/tables/template_code.py b/netbox/ipam/tables/template_code.py
@@ -26,12 +26,12 @@
 """ + PREFIX_LINK
 
 IPADDRESS_LINK = """
-{% if record.pk %}
-    <a href="{{ record.get_absolute_url }}" id="ipaddress_{{ record.pk }}">{{ record.address }}</a>
+{% if record.address or record.start_address %}
+    <a href="{{ record.get_absolute_url }}">{{ record }}</a>
 {% elif perms.ipam.add_ipaddress %}
-    <a href="{% url 'ipam:ipaddress_add' %}?address={{ record.1 }}{% if object.vrf %}&vrf={{ object.vrf.pk }}{% endif %}{% if object.tenant %}&tenant={{ object.tenant.pk }}{% endif %}&return_url={% url 'ipam:prefix_ipaddresses' pk=object.pk %}" class="btn btn-sm btn-success">{% if record.0 <= 65536 %}{{ record.0 }}{% else %}Many{% endif %} IP{{ record.0|pluralize }} available</a>
+    <a href="{% url 'ipam:ipaddress_add' %}?address={{ record.first_ip }}{% if object.vrf %}&vrf={{ object.vrf.pk }}{% endif %}{% if object.tenant %}&tenant={{ object.tenant.pk }}{% endif %}&return_url={% url 'ipam:prefix_ipaddresses' pk=object.pk %}" class="btn btn-sm btn-success">{{ record.title }}</a>
 {% else %}
-    {% if record.0 <= 65536 %}{{ record.0 }}{% else %}Many{% endif %} IP{{ record.0|pluralize }} available
+    {{ record.title }}
 {% endif %}
 """
 
diff --git a/netbox/ipam/tests/test_filtersets.py b/netbox/ipam/tests/test_filtersets.py
@@ -918,7 +918,9 @@ def setUpTestData(cls):
                 tenant=None,
                 role=None,
                 status=IPRangeStatusChoices.STATUS_ACTIVE,
-                description='foobar1'
+                description='foobar1',
+                mark_populated=True,
+                mark_utilized=True,
             ),
             IPRange(
                 start_address='10.0.2.100/24',
@@ -955,7 +957,9 @@ def setUpTestData(cls):
                 vrf=None,
                 tenant=None,
                 role=None,
-                status=IPRangeStatusChoices.STATUS_ACTIVE
+                status=IPRangeStatusChoices.STATUS_ACTIVE,
+                mark_populated=True,
+                mark_utilized=True,
             ),
             IPRange(
                 start_address='2001:db8:0:2::1/64',
@@ -1051,6 +1055,18 @@ def test_parent(self):
         params = {'parent': ['10.0.1.0/25']}  # Range 10.0.1.100-199 is not fully contained by 10.0.1.0/25
         self.assertEqual(self.filterset(params, self.queryset).qs.count(), 0)
 
+    def test_mark_utilized(self):
+        params = {'mark_utilized': 'true'}
+        self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2)
+        params = {'mark_utilized': 'false'}
+        self.assertEqual(self.filterset(params, self.queryset).qs.count(), 6)
+
+    def test_mark_populated(self):
+        params = {'mark_populated': 'true'}
+        self.assertEqual(self.filterset(params, self.queryset).qs.count(), 2)
+        params = {'mark_populated': 'false'}
+        self.assertEqual(self.filterset(params, self.queryset).qs.count(), 6)
+
 
 class IPAddressTestCase(TestCase, ChangeLoggedFilterSetTests):
     queryset = IPAddress.objects.all()
diff --git a/netbox/ipam/tests/test_models.py b/netbox/ipam/tests/test_models.py
diff --git a/netbox/ipam/utils.py b/netbox/ipam/utils.py
diff --git a/netbox/ipam/views.py b/netbox/ipam/views.py
diff --git a/netbox/templates/ipam/iprange.html b/netbox/templates/ipam/iprange.html

Original file line number	Diff line number	Diff line change
`@@ -147,7 +147,8 @@ class Meta:`
`147`	`147`	`fields = [`
`148`	`148`	`'id', 'url', 'display_url', 'display', 'family', 'start_address', 'end_address', 'size', 'vrf', 'tenant',`
`149`	`149`	`'status', 'role', 'description', 'comments', 'tags', 'custom_fields', 'created', 'last_updated',`
`150`		`- 'mark_utilized', 'description', 'comments', 'tags', 'custom_fields', 'created', 'last_updated',`
	`150`	`+ 'mark_populated', 'mark_utilized', 'description', 'comments', 'tags', 'custom_fields', 'created',`
	`151`	`+ 'last_updated',`
`151`	`152`	`]`
`152`	`153`	`brief_fields = ('id', 'url', 'display', 'family', 'start_address', 'end_address', 'description')`
`153`	`154`
Original file line number	Diff line number	Diff line change
`@@ -268,8 +268,8 @@ class IPRangeImportForm(NetBoxModelImportForm):`
`268`	`268`	`class Meta:`
`269`	`269`	`model = IPRange`
`270`	`270`	`fields = (`
`271`		`- 'start_address', 'end_address', 'vrf', 'tenant', 'status', 'role', 'mark_utilized', 'description',`
`272`		`- 'comments', 'tags',`
	`271`	`+ 'start_address', 'end_address', 'vrf', 'tenant', 'status', 'role', 'mark_populated', 'mark_utilized',`
	`272`	`+ 'description', 'comments', 'tags',`
`273`	`273`	`)`
`274`	`274`
`275`	`275`