Modeling channelized subinterfaces as child interfaces #11920

New Issue

adam · 2025-12-29T21:51:31+01:00

adam commented

2025-12-29 21:51:31 +01:00

Originally created by @jeremystretch on GitHub (Dec 12, 2025).

NetBox version

v4.4.8

Feature type

Data model extension

Proposed functionality

This FR aims to tackle the challenge of better modeling channelized subinterfaces in NetBox. It was prompted by work on FR #20788, but addresses a long-standing limitation in the data model. It is the solution for improved cable tracing provided under #20788 for the upcoming v4.5 release that unlocks this proposed work.

1. Add a `channels` integer field on the Interface model

This field will indicate the number of channels available on the parent interface. channels will be null for non-channelized interfaces.

Crucially, the cable tracing logic will need to be updated to reflect this new arrangement: A cable terminating to a channelized interface should effect path traces originating from and terminating at each of is channelized subinterfaces.

2. Add a `channel_id` integer field on the Interface model

In conjunction with the parent foreign key already present, this field will indicate the numeric channel on a parent interface to which a subinterface is bound.

Only one layer of channelization is to be permitted: An interface cannot have both channels and channel_id defined.

3. Introduce a "Channel" interface type (optional)

This new generic "channel" interface type may be introduced specifically to identify channelized subinterfaces. I believe this may be helpful as a guardrail to prevent errant configurations, as we can validate the assigned type of an interface against the channel_id field, and it avoids contention between the parent and child interface types.

However, if we find that there's sufficient value in retaining the explicit declaration of a subinterface's type (e.g. directly defining a 40GE channel as 10GBASE-SR) rather than inferring the type from a parent interface, we may opt to skip this element of the proposal. In this event, we would need to loosen the current restriction of assigning physical interface types to a parent, permitting it only where channelization is in use.

TBD

One potential issue for consideration is the handling of channelized interfaces which "consume" the parent interface. For instance, IIRC on some Junos platforms the original 40GE interface et-0/0/0 may be replaced in the configuration by four 10GE interfaces (xe-0/0/0 through xe-0/0/3). In this scenario, it's not clear how the parent interface would be accurately modeled.

Use case

As we've long held, a channelized interface is a physical subinterface which is dependent to some degree upon the characteristics of a parent interface. A very common example is a channelized 40GE interface which is broken out to 4x10GE channels, each terminating to an independent 10GE interface on the far end, with each channel utilizing a discrete fiber pair within e.g. an 8- or 12-strand MPO fiber cable. An example cable is show below.

The subinterfaces manifest on the network device as either four independent 10GE interfaces (e.g. xe-0/0/0 through xe-0/0/3) or as four numbered channels on a common parent (e.g. Eth1/1:1 through Eth1/1:4). It's crucial to recognize that these are not virtual interfaces: Each subinterface is physically bound to an underlying medium, and the number of subinterfaces therefore is fixed.

The current recommended practice for modeling channelized subinterfaces is to simply model each interface independently, and create a separate cable termination for each. While this generally suffices, it presents two complications:

It does not convey a dependency of the subinterface on its parent (which typically is not modeled).
Showing multiple cable terminations (one per subinterface) is inaccurate (or at best confusing) as there is only a single connector shared by all the subinterfaces.

Database changes

Add nullable channels and channel_id PositiveSmallIntegerFields on dcim.Interface.

External dependencies

N/A

Originally created by @jeremystretch on GitHub (Dec 12, 2025). ### NetBox version v4.4.8 ### Feature type Data model extension ### Proposed functionality This FR aims to tackle the challenge of better modeling channelized subinterfaces in NetBox. It was prompted by work on FR #20788, but addresses a long-standing limitation in the data model. It is the solution for improved cable tracing provided under #20788 for the upcoming v4.5 release that unlocks this proposed work. #### 1. Add a `channels` integer field on the Interface model This field will indicate the number of channels available on the parent interface. `channels` will be null for non-channelized interfaces. Crucially, the cable tracing logic will need to be updated to reflect this new arrangement: A cable terminating to a channelized interface should effect path traces originating from and terminating at each of is channelized subinterfaces. #### 2. Add a `channel_id` integer field on the Interface model In conjunction with the `parent` foreign key already present, this field will indicate the numeric channel on a parent interface to which a subinterface is bound. Only one layer of channelization is to be permitted: An interface cannot have both `channels` and `channel_id` defined. #### 3. Introduce a "Channel" interface type (optional) This new generic "channel" interface type may be introduced specifically to identify channelized subinterfaces. I believe this may be helpful as a guardrail to prevent errant configurations, as we can validate the assigned type of an interface against the `channel_id` field, and it avoids contention between the parent and child interface types. However, if we find that there's sufficient value in retaining the explicit declaration of a subinterface's type (e.g. directly defining a 40GE channel as 10GBASE-SR) rather than inferring the type from a parent interface, we may opt to skip this element of the proposal. In this event, we would need to loosen the current restriction of assigning physical interface types to a parent, permitting it only where channelization is in use. #### TBD One potential issue for consideration is the handling of channelized interfaces which "consume" the parent interface. For instance, IIRC on some Junos platforms the original 40GE interface `et-0/0/0` may be replaced in the configuration by four 10GE interfaces (`xe-0/0/0` through `xe-0/0/3`). In this scenario, it's not clear how the parent interface would be accurately modeled. ### Use case As we've long held, a channelized interface is a _physical_ subinterface which is dependent to some degree upon the characteristics of a parent interface. A very common example is a channelized 40GE interface which is broken out to 4x10GE channels, each terminating to an independent 10GE interface on the far end, with each channel utilizing a discrete fiber pair within e.g. an 8- or 12-strand MPO fiber cable. An example cable is show below. ![Image](https://github.com/user-attachments/assets/459081d8-a1ce-4c66-a02d-99b5e36b7206) The subinterfaces manifest on the network device as either four independent 10GE interfaces (e.g. `xe-0/0/0` through `xe-0/0/3`) or as four numbered channels on a common parent (e.g. `Eth1/1:1` through `Eth1/1:4`). It's crucial to recognize that these are _not_ virtual interfaces: Each subinterface is physically bound to an underlying medium, and the number of subinterfaces therefore is fixed. The current recommended practice for modeling channelized subinterfaces is to simply model each interface independently, and create a separate cable termination for each. While this generally suffices, it presents two complications: 1. It does not convey a dependency of the subinterface on its parent (which typically is not modeled). 2. Showing multiple cable terminations (one per subinterface) is inaccurate (or at best confusing) as there is only a single connector shared by all the subinterfaces. ### Database changes Add nullable `channels` and `channel_id` PositiveSmallIntegerFields on dcim.Interface. ### External dependencies N/A

adam added the type: feature status: under review complexity: medium netbox needs milestone labels 2025-12-29 21:51:31 +01:00

adam commented

2025-12-29 21:51:32 +01:00

@sleepinggenius2 commented on GitHub (Dec 15, 2025):

While breakouts are one use case for channelization, the other places we see this frequently are in SONET, OTN, ROADM, and RF equipment. For SONET and OTN your "channels" are timeslots and may use multiple values for a single service, which are typically contiguous, but may be interleaved in some OTN schemes. For ROADM and RF, your "channels" are frequency slots and may be inverse-multiplexed to support a higher capacity service. For fixed grids, these values could be represented by integers corresponding to, for example, common ITU numbering. For flex grids and most RF applications though, an integer channel number may not be as intuitive and would ideally be defined by a center frequency and width or start and end frequencies. It seems to me that all of these scenarios could be handled by allowing the channels field to be a positive big integer type and channel_id to be changed to channel_ids and support an array of positive big integer ranges. This would allow for both the simple breakout use case, as well as more complex scenarios requiring multiple channel values, and would allow for RF (including optical) applications to standardize on frequency values, which can be represented as an integral number of hertz. This would even allow for flex grid applications to be documented using start and end frequencies.

In order to better support this approach and to make things less error prone, I would additionally propose a way to define channelization schemes, which could be referenced in place of the channels field. This would allow for assigning a name and description (optional) to the scheme, the start and end channels, and the unit (optional) for displaying the channels in. This way you could set the start and end frequencies for your grid and display the channel values in Hz, ideally humanized to k, M, G, T, if possible.

For SONET and OTN, you can have multiple layers of channelization (multiplexing), so a child interface may also be a parent for other child interfaces. Just something to consider when writing validation logic.

For item 3, I can see a use case for a new Channel type, but would also be interested in being able to properly document the correct interface type. After the introduction of the new interface types in v4.4.1, we have been looking into using custom validators to make sure that the interfaces on either end of a cable path are compatible with each other and the type of cable selected, so that would be our use case for being able to correctly document the type.

@sleepinggenius2 commented on GitHub (Dec 15, 2025): While breakouts are one use case for channelization, the other places we see this frequently are in SONET, OTN, ROADM, and RF equipment. For SONET and OTN your "channels" are timeslots and may use multiple values for a single service, which are typically contiguous, but may be interleaved in some OTN schemes. For ROADM and RF, your "channels" are frequency slots and may be inverse-multiplexed to support a higher capacity service. For fixed grids, these values could be represented by integers corresponding to, for example, common ITU numbering. For flex grids and most RF applications though, an integer channel number may not be as intuitive and would ideally be defined by a center frequency and width or start and end frequencies. It seems to me that all of these scenarios could be handled by allowing the `channels` field to be a positive big integer type and `channel_id` to be changed to `channel_ids` and support an array of positive big integer ranges. This would allow for both the simple breakout use case, as well as more complex scenarios requiring multiple channel values, and would allow for RF (including optical) applications to standardize on frequency values, which can be represented as an integral number of hertz. This would even allow for flex grid applications to be documented using start and end frequencies. In order to better support this approach and to make things less error prone, I would additionally propose a way to define channelization schemes, which could be referenced in place of the `channels` field. This would allow for assigning a name and description (optional) to the scheme, the start and end channels, and the unit (optional) for displaying the channels in. This way you could set the start and end frequencies for your grid and display the channel values in Hz, ideally humanized to k, M, G, T, if possible. For SONET and OTN, you can have multiple layers of channelization (multiplexing), so a child interface may also be a parent for other child interfaces. Just something to consider when writing validation logic. For item 3, I can see a use case for a new Channel type, but would also be interested in being able to properly document the correct interface type. After the introduction of the new interface types in v4.4.1, we have been looking into using custom validators to make sure that the interfaces on either end of a cable path are compatible with each other and the type of cable selected, so that would be our use case for being able to correctly document the type.

Sign in to join this conversation.

Branches Tags

main

update-changelog-comments-docs

feature-removal-issue-type

20911-dropdown

20239-plugin-menu-classes-mutable-state

21097-graphql-id-lookups

feature

fix_module_substitution

20923-dcim-templates

20044-elevation-stuck-lightmode

feature-ip-prefix-link

v4.5-beta1-release

20068-import-moduletype-attrs

20766-fix-german-translation-code-literals

20378-del-script

7604-filter-modifiers-v3

circuit-swap

12318-case-insensitive-uniqueness

20637-improve-device-q-filter

20660-script-load

19724-graphql

20614-update-ruff

14884-script

02496-max-page

19720-macaddress-interface-generic-relation

19408-circuit-terminations-export-templates

20203-openapi-check

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/netbox#11920

Modeling channelized subinterfaces as child interfaces #11920