Templates for Netconf Provisioning
NorthStar Controller supports NETCONF provisioning for Juniper devices and Cisco IOS-XR devices. You can customize provisioning templates by modifying the templates provided in the /opt/northstar/netconfd/templates/ directory on the NorthStar server, or by creating new, customized templates.
For IOS-XR routers, NorthStar LSP Netconf-based provisioning has the same capabilities as NorthStar PCEP-based provisioning.
The syntax and semantics used in the template attributes are based on Jinja Templates, a template engine for Python. Help/support for using Jinja Templates is readily available online.
You can use customized templates for:
LSP Provisioning: make use of provisioning properties not directly supported by the NorthStar UI.
For example, you cannot specify a hop-limit in the Properties tab in the Provision LSP window. However, you can add hop-limit in the User Properties tab of the Provision LSP or Modify LSP window and then modify the appropriate provisioning template accordingly.
Service mapping: associate LSPs being provisioned with a VPN service.
When an LSP is created, it can be tagged with user properties that, when also defined in the Jinja template, cause the corresponding service mapping statement to be generated in the router configuration.
Example VPN services include:
Mapping P2P LSPs to circuit cross-connect (CCC) VPNs
Note:The CCC service must already exist in the network before you perform this type of service mapping.
Mapping P2MP LSPs to multicast VPNs (MVPNs)
Note:An MVPN routing instance must already exist before you perform this type of service mapping.
General Workflow for Modifying a Template
The following steps describe the general workflow for modifying a provided Jinja template and ensuring that the desired provisioning takes effect:
Decide on the user properties needed and their values.
Edit the appropriate Jinja template to include those properties.
Restart netconfd so the changes can take effect:
[root@system1 templates]# supervisorctl restart netconf: netconf:netconfd: stopped netconf:netconfd: started
Provision or modify the LSP using the web UI, and include the user properties and their values in the User Properties tab of the Provision LSP or Modify LSP window.
Verify the router configuration.
If you are configuring high availability (HA), execute steps 1 through 3 on the active and standby servers.
Overview of Netconf Provisioning Templates
There are two types of templates provided in the templates directory:
Encoding templates are for internal use only and should never be modified or deleted. All of these templates have “encoding” in their names (lsp-modify-encoding.hjson, for example).
Configuration templates are for transforming JSON document keys into device configuration statements. These templates are available for modification and to use as models for creating new templates. Currently, these templates all have “junos” in their names, (lsp-modify-junos.hjson, for example), although, as long as you use the .hjson suffix, you can name new templates according to your preference.
Template Requirements
Keep in mind the following template requirements:
If you create a new template, be sure the PCS user has Unix file permission to read it.
Template files are hjson documents, so their file names must have the .hjson suffix.
The Netconf daemon (NETCONFD) must be restarted for template changes to be applied:
[root@pcs-1 templates]# supervisorctl restart netconf netconf:netconf: stopped netconf:netconf: started
Text format is supported for device configuration statements. XML format is supported for modifying Cisco IOS XR devices.
When you upgrade a NorthStar build, the templates provided in the new build replace the ones that were provided with the original build. You can prevent loss of your template changes by backing up your templates to a different directory on the server before upgrading NorthStar, or by saving your modified files with different file names.
If you are configuring high availability (HA), execute steps 1 through 3 on the active and standby servers.
Template Structure
Each template has two types of attributes:
Routing-key attributes which describe the type of provisioning for which the template should be used. The value of routing-key is not fixed in NETCONFD, but the following keys are currently agreed upon between NETCONFD and ConfigServer for LSP provisioning:
rest_eventd_request_key
Use for adding a new LSP.
rest_eventd_update_key
Use for modifying an existing LSP.
rest_eventd_delete_key
Use for deleting an LSP
Device profile attributes that define the device to be provisioned when using the template.
You can use any device profile attributes (Administration > Device Profile) such as routerType (Vendor field in Device Profile), model, and so on. NETCONFD tries to match the attributes in the template with the attributes in the device profiles of the targeted devices.
User properties attributes that define such things as service mapping attributes.
User properties is a generic mechanism that allows you to “tag” LSPs with additional properties. One use of user properties is to tag an LSP with the vpn-name, source-ip, and group-ip that are related to the associated MVPN (for service mapping).
In the Jinja template, when those user properties are defined, a corresponding set of statements (related to service mapping) are also generated. The support in the REST body and the web UI is the same. In the REST body, you include the user properties under “userParameters”, while in the web UI, you include them in the User Properties tab of the Provision (or Modify) LSP window.
Table 1, Table 2, and Table 3 detail the supported JSON document keys for adding LSPs, modifying LSPs, deleting LSPs, and link modification.
Keys that do not “always exist” only exist conditionally. For example:
request[“logical-system”] is used to specify the logical-system name, so it only exists in the JSON document if the provisioning order is for logical-system devices.
request[“p2mp-name”] is used to specify the P2MP name, so it only exists in the JSON document if the provisioning order is for P2MP LSPs.
Key |
Value |
Always Exists |
Description |
|---|---|---|---|
request.name |
text |
yes |
LSP name |
request.from |
IPv4 address |
yes |
LSP source address |
request.to |
IPv4 address |
yes |
LSP destination address |
request['lsp-path-name'] |
text |
yes |
LSP path name |
request.bandwidth |
integer |
yes for adding no for modifying |
LSP path bandwidth |
request.metric |
integer |
no |
LSP metric |
request.type |
[primary |secondary |standby] |
yes |
LSP path type |
request['path-attributes']['ero'][’ipv4-address’] |
IPv4 address |
no |
LSP path hop |
request['path-attributes']['ero'][’loose'] |
[true] |
no |
LPS path loose flag |
request['path-attributes']['setup-priority'] |
[0-7] |
yes for adding no for modifying |
LSP path setup priority |
request['path-attributes']['reservation-priority'] |
[0-7] |
yes for adding no for modifying |
LSP path reservation priority |
request['logical-system'] |
text |
no |
LSP headend logical system name |
request['p2mp-name'] |
text |
no |
LSP P2MP group name |
request['select-manual'] |
[true] |
no |
LSP path manual selection |
request['user-properties'] |
text |
yes |
Additional properties as defined by user |
Key |
Value |
Always Exists |
Description |
|---|---|---|---|
request.name |
text |
yes |
LSP name |
request.from |
IPv4 address |
yes |
LSP source address |
request.to |
IPv4 address |
yes |
LSP destination address |
request['lsp-path-name'] |
text |
no |
LSP path name |
request.type |
[primary |secondary |standby] |
yes |
LSP path type |
request.delete |
[true] |
no |
Specifies whether the deletion order is for deleting the LSP (value of “true”) or the LSP path |
request['logical-system'] |
text |
no |
LSP headend logical system name |
request['user-properties'] |
text |
yes |
Additional properties as defined by user |
Key |
Value |
Always Exists |
Description |
|---|---|---|---|
request.new_interface.name |
text |
yes |
Interface name |
request.new_interface.isis1_metric |
integer |
no |
ISIS level 1 metric |
request.new_interface.isis2_metric |
integer |
no |
ISIS level 2 metric |
request.new_interface.ospf_metric |
integer |
no |
OSPF metric |
request.new_interface.ospf_area_id |
integer |
no |
OSPF area |
request.logical_system |
text |
no |
Router logical system name |
The pcs_provisioning_order_key order is currently used specifically for OSPF/ISIS metric modification.
Template Macros
Jinja Templates support macros for defining reusable functions. The NorthStar template directory includes the macros listed in Table 4.
Macro |
Function |
|---|---|
ifexist |
Generates a Junos configuration statement if the evaluated key in the JSON document exists. |
Ifnotzero |
Generates a Junos configuration statement if the evaluated key in the JSON document has a value that is not equal to zero. |
Ifnotnone |
Generates a Junos configuration statement if the evaluated key in the JSON document has any value. |
decodeuserprops |
Decodes the user defined properties in the JSON document. |
lsys |
Generates a configuration statement for Junos logical system. |
Jinja Template Examples for Service Mapping
In the following Jinja template snippet, the statements related to service mapping of the P2MP LSP to the multicast MVPN are provisioned with the LSP if the LSP has associated with it the “vpn-name” user property.
{% if request['user-properties'] and request['user-properties']['vpn-name'] is defined %}
routing-instances {
{{ request['user-properties']['vpn-name'] }} {
provider-tunnel {
selective {
group {{ request['user-properties']['group-ip'] }} {
source {{ request['user-properties']['source-ip'] }} {
rsvp-te {
static-lsp {{ request['p2mp-name'] }};
}
}
}
}
}
}
}
{% endif %}
In the following Jinja template snippet, the statement related to service mapping of the LSP to the CCC-VPN is provisioned with the LSP if the LSP has associated with it the “ccc-vpn-name” user property.
{% if request['user-properties'] and request['user-properties']['ccc-vpn-name'] is defined %}
protocols {
connections {
remote-interface-switch {{ request['user-properties']['ccc-vpn-name'] }} {
interface {{ request['user-properties']['ccc-interface'] }};
transmit-lsp {{ request['user-properties']['transmit-lsp'] }};
receive-lsp {{ request['user-properties']['receive-lsp'] }};
}
}
}
{% endif %}
Jinja Template Example for SR LSPs
The following is an example Jinja template snippet used for NETCONF-provisioned SR LSPs. If a binding SID value is specified, a binding SID SR LSP is provisioned. Without a binding SID specified, a regular non-binding SID SR LSP is provisioned.
{% if request['path-setup-type'] == "segment" %}
protocols {
source-packet-routing {
delete: segment-list {{request.name}};
delete: source-routing-path {{request.name}}/{{request.name}};
segment-list {{request.name}} {
{% for segment in request['path-attributes']['sr-ero'] %}
{% if segment['remote-ipv4-address'] %}
segment{{loop.index}} label {{segment.sid}} ip-address {{segment['remote-ipv4-address']}};
{% else %}
segment{{loop.index}} label {{segment.sid}};
{% endif %}
{% endfor %}
}
source-routing-path {{request.name}}/{{request.name}} {
to {{request.to}};
{{ macros.ifexistandnotzero('metric', request.metric) -}}
{{ macros.ifexistandnotzero('binding-sid', request['path-attributes']['binding-sid']) -}}
{{ request.type }} {
{{request.name}};
}
}
}
}