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 host address, except in the case of /32 IPv4 prefixes and /128 IPv6 prefixes.)

At the database level, a prefix stores its network information in the fields network, broadcast, prefix_length, and ip_version. For convenience, the Nautobot UI, REST API, and Django ORM permit defining all of these via a single prefix parameter as an alternative.

Each prefix belongs to a specific Namespace, and is unique within that namespace. Each prefix can also optionally be assigned to a particular Location(s), as well as to zero or more virtual routing and forwarding (VRF) instances. All prefixes not assigned to a VRF are considered to be in the "global" VRF within their namespace.

Changed in version 2.0.0 — Prefixes are unique per Namespace

In Nautobot 1.x, prior to the introduction of the namespace data model, a prefix might or might not be unique within its assigned VRF. In Nautobot 2.0, prefixes are always unique within their namespace. You may need to do some cleanup of your data after migrating from Nautobot 1.x to suit the new data requirements.

Changed in version 2.2.0 — Prefixes can now be assigned to multiple Locations

A Prefix can now be assigned to multiple Locations if desired.

Each prefix must be assigned a status and can optionally be assigned 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. The following statuses are provided by default:

Active - Provisioned and in use
Reserved - Designated for future use
Deprecated - No longer in use

Changed in version 2.0.0 — Introduction of type field

The "Container" status was removed and its functionality was replaced by the Prefix.type field (see below).

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.

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.

A prefix can be assigned to an RIR to track which RIR has granted your organization permission to use the specified IP space on the public Internet.

The date_allocated field can be used to track any date and time you would like to define as the "allocated date" for a prefix. This could be the date an RIR assigned a prefix to your organization or the date a prefix was assigned to a specific internal team.

Added in version 2.0.0 — Introduction of date_allocated and rir fields

The date_allocated and rir fields were added, migrating data from the removed Aggregate model.

Prefix and IP Address Hierarchy¶

The hierarchy of prefixes and their constituent IP addresses is tracked in the Nautobot database via parent foreign keys. For example you might have in a given namespace:

Prefix 10.0.0.0/8 (with no parent)
- IP address 10.0.1.0/32 (with parent 10.0.0.0/8)
- Prefix 10.1.1.0/24 (with parent 10.0.0.0/8)
  - IP address 10.1.1.1/24 (with parent 10.1.1.0/24)

Note that in Nautobot, all IP addresses must have a parent prefix; "orphaned" IP addresses are not permitted.

In most cases, you will not need to ever explicitly specify the parent value yourself, as specifying the namespace is generally more user-friendly and will result in the parent being automatically determined and updated as needed by Nautobot.

Prefix List View and Hierarchy Display¶

The default (unfiltered) Prefix list view (/ipam/prefixes/) includes indentation or nesting of child Prefixes under their parent Prefixes, similar to the example above, as this is useful information to be aware of. However, in most cases, applying sorting, filtering, or search to this list view will remove the indentation from display, as it would be misleading or outright confusing when not showing the full list of prefixes in their default network order.

Added in version 3.1.0 — Added exemptions for specific filters

There are a small set of filters which, when applied individually or in combination, do not remove the indentation, because these filters preserve the hierarchy and ordering of the filtered set of Prefixes. Examples of such filters include ip_version, namespace, and max_depth. The "default filters" described in the next section, for much the same reasons, also do not remove indentation when in effect.

Tip

The indentation-preserving filters only preserve indentation if they are the only filter(s) applied to the view. Adding search, sorting, or any additional filters will still remove the indentation as normal. In other words:

/ipam/prefixes/?ip_version=4&namespace=Global -- indentation preserved
/ipam/prefixes/?ip_version=4&sort=status -- indentation removed due to sorting
/ipam/prefixes/?ip_version=4&status=Active -- indentation removed due to additional filtering

Prefix List View Configuration¶

Added in version 3.1.0 — Added configuration parameters

To improve performance of the initial rendering of the Prefix list view when a large number of records and/or a deep hierarchy of records are present, an administrator can configure the settings PREFIX_LIST_DEFAULT_CONTAINER_ONLY and/or PREFIX_LIST_DEFAULT_MAX_DEPTH. When enabled, these settings effectively apply a default filter (similar to a default saved view) for all users when initially accessing the Prefix list view, such as from the navigation menu.

In both cases, these default filters will only apply when viewing the otherwise-unfiltered Prefix list view; applying any other filter to the view will bypass these default filters and display the full set of records as selected by the user-specified filter.

`PREFIX_LIST_DEFAULT_CONTAINER_ONLY`¶

When this setting is enabled, the default Prefix list view will only display Prefixes of type Container, omitting the more narrowly-scoped Network and Pool Prefixes. Users can then either apply an appropriate filter of their choice to narrow the scope of the list view further, or simply select the relevant Container Prefix and navigate to its "detail" view to see and interact with the Networks and Pools it contains.

`PREFIX_LIST_DEFAULT_MAX_DEPTH`¶

When this setting is configured to a non-negative number, the default Prefix list view will only display Prefixes down to a certain nesting depth. For example, a value of 0 (zero) will only display root Prefixes (those with no higher-level parent), a value of 1 (one) will display root Prefixes and their immediate children, but not their grandchildren, and so forth. As with PREFIX_LIST_DEFAULT_CONTAINER_ONLY, the intent here would be for users to use the Prefix list view to quickly find the general prefix of interest and then use filters, search, and/or the relevant "detail" view to "drill down" to a specific network or pool.

Hierarchy Updates when Editing Prefixes¶

Added in version 2.4.17 — Added support and validation for changing prefix and namespace values

Prior to Nautobot v2.4.17, Nautobot lacked some essential logic for handling changes to these fields on an existing Prefix, and as a result, changing these fields could result in incorrect data in some cases. Refer to Repairing Prefix and IP Address Hierarchy below for details.

When editing a Prefix and changing its prefix value (network, prefix_length, etc.), or namespace, Nautobot will automatically update the parent field of the record and related Prefix and IP Address records as needed to preserve the correct hierarchy. Such edits to a Prefix do not "renumber" or "re-IP" the descendant Prefixes and IP Addresses below this Prefix. For example, if the aforementioned 10.1.1.0/24 Prefix were edited to have a network of 10.0.1.0/24, IP address 10.1.1.1/24 would be updated such that its parent was now the 10.0.0.0/8 Prefix, as 10.0.1.0/24 does not contain host 10.1.1.1, but 10.0.0.0/8 does. Similarly, IP address 10.0.1.0/32 would be updated to have its parent become the newly updated 10.0.1.0/24 Prefix:

Prefix 10.0.0.0/8 (with no parent)
- Prefix ~~10.1.1.0/24~~ 10.0.1.0/24 (with parent 10.0.0.0/8)
  - IP address 10.0.1.0/32 (with parent ~~10.0.0.0/8~~ 10.0.1.0/24)
- IP address 10.1.1.1/24 (with parent ~~10.1.1.0/24~~ 10.0.0.0/8)

Orphaned IP addresses

If editing an existing Prefix would result in some of its child IP Addresses becoming "orphans" with no valid parent Prefix, Nautobot will raise a validation error and reject the change with an appropriate explanation.

Changed in version 2.4.17 — Cascading namespace updates

Additionally, when changing a Prefix's namespace, not only the specified Prefix record, but also all of its descendant Prefix records will be moved into the new Namespace. This is in service of the "principle of least surprise", because IP Address records do not have their own individual Namespaces but instead derive their namespace from their parent Prefixes, and it would be surprising to most users if only IPs directly under a given Prefix were brought along, while IPs under a nested subnet Prefix were left behind in the original Namespace.

Uniqueness violations when changing Namespace

Because Prefix and IP Address uniqueness is enforced per-Namespace, if the target Namespace already contains existing Prefix and/or IP Address records, moving a Prefix and its descendants into that Namespace may result in data "collision" and violations of the uniqueness constraint. Nautobot will detect such a scenario and prevent the change.

VRFs are specific to a Namespace

Because VRFs are specific to a Namespace, moving a Prefix that's associated to one or more VRFs into a different Namespace is blocked by Nautobot, and will result in a validation error with a message about needing to disassociate the Prefix (and its descendants) from VRFs before changing the Namespace. The workflow you'd need to follow here would be:

Disassociate the Prefix and its descendant Prefixes from any and all VRFs in the initial Namespace.
Move the Prefix (and implicitly its descendants) into the target Namespace.
Create and/or associate VRFs in the target Namespace to the Prefix(es) as desired.

If you find yourself needing to perform this workflow frequently, consider implementing a simple Nautobot Job to consolidate these three steps into a single repeatable task.

Repairing Prefix and IP Address Hierarchy¶

Added in version 2.4.17 — Added system Job for repairing incorrect parent values

It is possible in some cases, particularly due to insufficient validation in earlier Nautobot 2.x releases, but also due to incorrect logic in custom Jobs and the like, for parent values to become incorrectly set on some Prefix and IP Address records. One symptom of such an issue can be seen when a Prefix's reported "utilization" value is reported as an incorrect value, such as in some cases showing greater than 100% utilization.

If you encounter or suspect an issue of this sort, Nautobot provides a system Job named "Check/Fix IPAM Parents" which can be run to efficiently detect and repair various problems of this sort.

If, after running this Job, you later find that this issue recurs, we recommend reviewing any Apps and Jobs that are making programmatic updates to Prefix and IP Address data, as this should not recur during normal Nautobot UI or REST API updates in v2.4.17 and later.

Prefix Types¶

The prefix model can be set to one of three types through the type field. The valid prefix types are:

Container
Network (default)
Pool

We recommend that you think of "Networks" as the actual host-containing subnets in your network, while "Containers" represent groups of related "Networks", and "Pools" are used as needed within a "Network". In other words, "Containers" contain "Networks" which may contain "Pools". However, Nautobot does not strictly enforce this hierarchy. There are however a few ways in which different prefix types behave differently, as described below.

Changed in version 2.0.0 — Removal of is_pool field

The is_pool field was removed and its functionality was replaced by the Prefix.type field.

Allocatable Hosts by Prefix Type¶

If a prefix's type is set to "Pool", Nautobot 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 type is set to "Network" or "Container", Nautobot will assume that the first and last (network and broadcast) addresses within an IPv4 prefix are unusable as hosts.

Prefix Utilization Calculation by Prefix Type¶

If the prefix type is "Container", the utilization is calculated as the sum of the total address space of all child prefixes. Individual IP addresses are not included in the calculation.
Conversely, if the prefix type is "Pool", the utilization is calculated as the sum of the total number of IP addresses within the pool's range. Prefixes are not included in the calculation.
If the prefix type is "Network":
- The utilization is calculated as the sum of the total address space of all child prefixes plus the total number of child IP addresses not covered by a child prefix.
- For IPv4 networks larger than /31, if neither the first (network) or last (broadcast) address is occupied by either a pool or an IP address, they are subtracted from the total size of the prefix.