A YANG Module for Entitlement Inventory

1.1. Scope of the Entitlement Model

The entitlement model aims to provide an inventory of entitlements. This includes the entitled holders and the capabilities to which they are entitled. Additionally, it offers information into the restrictions of the operation of the different assets (network entities and components). In general, this model seeks to address the following questions:¶

• What entitlements are administered/owned by the organization?¶

• How are entitlements restricted to some assets and holders?¶

• What entitlements are assigned or installed on each asset(s)?¶

• What constraints do the current entitlements impose on the assets' functionality?¶

• Does the entitlement impose any kind of global restrictions? What are they?¶

• What are the restrictions that each asset due to the entitlements it holds?¶

The model is designed with flexibility in mind, allowing for expansion through the utilization of tools provided by YANG.¶

The realm of entitlements and licensing is inherently complex, presenting challenges in creating a model that can comprehensively encompass all scenarios without ambiguity. While we attempt to address various situations through examples and use cases, we acknowledge that the model might not be able to cover all corner cases without ambiguity. In such cases, we recommend that implementations provide additional documentation to clarify those potential ambiguities. The current model does not aim to serve as a catalog of licenses. While it may accommodate basic scenarios, it does not aim to cover the full spectrum of license characteristics, which can vary significantly. Instead, our focus is on providing a general framework for describing relationships and answering the questions posed above.¶

With the aim of clarifying the model scope, here are some questions that our model does not attempt to answer:¶

• What are the implications of purchasing a specific entitlement?¶

• Which entitlement should I acquire to get a specific capability?¶

• Is license migration feasible?¶

• What capabilities will be allowed if I install an entitlement in a specific device?¶

• Features or restrictions that depend on each user. We are not covering this in the current version of this document, but it could be done if we expand the holders' identification.¶

This model focuses on the ability to use capabilities, not on access control mechanisms. For example, if a router cannot enable MPLS due to entitlement restrictions, it means the organization lacks the rights to use that capability—even if access to the device itself is available. This distinction is separate from, for instance, the ability of a specific user to configure MPLS due to access control limitations.¶

1.2. Pre-Provisioned vs. Discovered Entitlements

This model is not intended for automatic discovery of entitlements or capabilities through the network elements themselves. Instead, it assumes that entitlements and their associations are either:¶

• Provisioned in a license server or asset database;¶

• Installed on individual devices and reported through management interfaces; or¶

• Manually configured as part of an inventory process.¶

Future augmentations may explore capability discovery or telemetry driven models, but they are out of scope for the current version.¶

3.1. Capabilities

Capabilities are modeled by augmenting "network-element" in the "ietf-network-inventory" module in [BaseInventory] according to the following tree:¶

+--rw capabilities
   +--rw capability-class* [capability-class]
      +--rw capability-class                     identityref
      +--rw capability* [capability-id]
         +--rw capability-id                     string
         +--rw extended-capability-description?     string
         +--rw resource-description?             string
         +--rw resource-units?                   string
         +--rw resource-amount?                  int32
         +--rw supporting-entitlements
            +--rw entitlement* [entitlement-id]
            +--rw entitlement-id                 -> ../../../../../entitlements/entitlment/entitlement-id
            +--rw allowed?                       boolean
            +--rw in-use?                        boolean
            +--rw capability-restriction* [capability-restriction-id]
               +--rw capability-restriction-id   string
               +--rw component-id?               -> ../../../../../components/component/component-id
               +--rw description?                string
               +--rw resource-name?              string
               +--rw units?                      string
               +--rw max-value?                  int32
               +--rw current-value?              int32

For any given element, the capabilities list MAY include all potential capabilities advertised by the vendor, and MUST include those for which the network operator holds a valid entitlement—whether active or not.¶

The capabilities of an inventoried asset may be restricted based on the availability of proper entitlements. An entitlement manager might be interested in the capabilities available to be use on the assets, and the capabilities that are available. The model includes this information by means of the "supporting entitlements" list, that includes potential restrictions related to the status of the entitlement. This allows organizations to monitor entitlement usage and avoid misconfigurations or exceeding permitted capability limits.¶

3.2. Entitlements

As in the case of capabilities, entitlement modeling augments "network-element" in the ietf-network-inventory module in [BaseInventory] according to the following tree:¶

+--rw entitlements
   +--rw entitlement* [eid]
   +--rw eid                                  string
   +--rw product-id?                          string
   +--rw state?                               entitlement-state-t
   +--rw renewal-profile
   |  +--rw activation-date?                  yang:date-and-time
   |  +--rw expiration-date?                  yang:date-and-time
   +--rw restrictions
   |  +--rw restriction* [restriction-id]
   |  +--rw restriction-id                    string
   |  +--rw description?                      string
   |  +--rw units?                            string
   |  +--rw max-value?                        int32
   |  +--rw current-value?                    int32
   +--rw parent-entitlement-uid?              -> ../entitlement/eid
   +--rw entitlement-attachment
      +--rw universal-access?   boolean
      +--rw holders!
         |  +--rw organizations_names
         |  |  +--rw organizations*           string
         |  +--rw users_names
         |     +--rw users*                   string
         +--rw assets
            +--rw elements
               +--rw network-elements*        string
               +--rw components
                  +--rw component* [network-element component-id]
                     +--rw network-element    string
                     +--rw component-id       string

Entitlements and assets are linked in the model in two ways. Entitlements might be attached to assets, and assets include (or have installed) entitlements. The former way addresses the case of a license server, while the latter considers an entitlement directly associated with the network element. An entitlement that is not included by any asset means that it is not being used.¶

Entitlements may be listed in multiple assets. For instance, a license server, functioning as an asset, might list an entitlement, while the network element entitled by that license might also list it. Proper identification of entitlements is imperative to ensure consistency across systems, enabling monitoring systems to recognize when multiple assets list the same entitlement. Furthermore, there are cases where an authorized asset might not be aware of the covering license. Consider the scenario of a site license, wherein any device under the site may utilize a feature without explicit knowledge of the covering license. In such cases, asset awareness relies on management controls or a service license capable of listing it.¶

3.3. Entitlement Attachment

The "entitlement" container holds a container called "entitlement-attachment" which relates how the entitlement is operationally linked to holders or assets. Note that there is a difference between an entitlement being attached to an asset and an entitlement being installed in the asset. In the former, the license was explicitly associated with one or more assets. Some licenses actually can be open but have a limited number of installation. Other licenses might be openly constrained to a geographic location. We are not dealing with these complex cases now, but the container can be expanded for this in the future.¶

The model accommodates listing entitlements acquired by the organization but not yet applied or utilized by any actor/asset. For these pending entitlements, logistical constraints may arise in informing their existence, as there must be at least one element exporting the model that is aware of their existence.¶

Some entitlements are inherently associated with a holder, such as organization or a user. For example, a software license might be directly attached to a user. Also, the use of a network device might come with a basic license provided solely to an organization. Some entitlements could be assigned to a more abstract description of holders, such as people under a jurisdiction or a geographical area. The model contains basic information about this, but it can be extended in the future to be more descriptive.¶

While attachment is optional, the model should be capable of expressing attachment in various scenarios. The model can be expanded to list to which assets an entitlement is aimed for, when this link is more vague, such as a site license (e.g., assets located in a specific site), or more open licenses (e.g., free software for all users subscribed to a streaming platform).¶

It is important to note that the current model does not provide information on whether an entitlement can be reassigned to other devices (e.g., fixed or floating license). Such scenarios fall under the "what if" category, which is not covered by this model.¶

3.4. Model Definition

TBP¶

3.5. Read-Only vs. Read-Write Model Segmentation

Not all elements in the entitlement model are expected to be configurable. The current YANG tree uses rw extensively for structural convenience. However, in many real-world use cases, entitlement and capability data will be read-only from the device or management system perspective.¶

Data can be classified as follows:¶

• Read-only (ro): Installed entitlements, current-value/max-value, expiration timestamps, holder details.¶

• Read-write (rw): Static description of capabilities and manually registered licenses.¶

Future revisions may refactor the model to more accurately reflect configuration vs. operational state using config false statements.¶

4.1. MPLS Capability License on a Network OS

An operator installs a software license (entitlement) enabling MPLS routing on a NOS. The license is attached to a specific device and activates the "mpls-routing" capability class.¶

json
"entitlement": {
  "eid": "mpls-license-001",
  "product-id": "mpls-software-lic-v2",
  "renewal-profile": {
    "activation-date": "2025-01-01T00:00:00Z",
    "expiration-date": "2026-01-01T00:00:00Z"
  },
  "entitlement-attachment": {
    "holders": {
      "organizations_names": {
        "organizations": ["ACME Corp"]
      },
      "assets": {
        "elements": {
          "network-elements": ["router-5"]
        }
      }
    }
  }
}

"capability": {
  "capability-id": "mpls-routing",
  "capability-class": "routing",
  "supporting-entitlements": {
    "entitlement": [
      {
        "entitlement-id": "mpls-license-001",
        "allowed": true,
        "in-use": true
      }
    ]
  }
}

4.2. Bandwidth Upgrade via License

A vendor-N device uses a capacity license to expand throughput.¶

json
"entitlement": {
  "eid": "vendorN-bw-10g",
  "product-id": "vendorN-bw-upgrade",
  "restrictions": {
    "restriction": [
      {
        "restriction-id": "cap",
        "description": "Bandwidth cap",
        "units": "Gbps",
        "max-value": 10,
        "current-value": 6
      }
    ]
  }
}

"capability": {
  "capability-id": "bw-capability",
  "resource-description": "Licensed bandwidth",
  "resource-units": "Gbps",
  "resource-amount": 10,
  "supporting-entitlements": {
    "entitlement": [
      {
        "entitlement-id": "vendorN-bw-10g",
        "allowed": true,
        "in-use": true
      }
    ]
  }
}

4.3. Floating License Managed by License Server

A shared entitlement is held by a license server and consumed dynamically by multiple switches.¶

json
"entitlement": {
  "eid": "shared-switch-license-1",
  "entitlement-attachment": {
    "universal-access": true,
    "holders": {
      "organizations_names": {
        "organizations": ["NTT"]
      }
    },
    "assets": {
      "elements": {
        "network-elements": ["switch-1", "switch-2", "switch-3"]
      }
    }
  }
}

This entitlement may be tracked across devices using a license server asset that records usage or seat count (future extension).¶

7.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

7.2. Informative References

[BaseInventory]

Yu, C., Belotti, S., Bouquier, J., Peruzzini, F., and P. Bedard, "A Base YANG Data Model for Network Inventory", Work in Progress, Internet-Draft, draft-ietf-ivy-network-inventory-yang-07, 7 July 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-ivy-network-inventory-yang-07>.