Repository Reference

Templates

Templates for switch configurations.

In the base of this repository there should be one directory for each network operating system platform, like “eos”, “junos” or “iosxr”.

In each of these directories there needs to be a file called “mapping.yml”, this file defines what template files should be used for each device type. For example, in mapping.yml there might be a definition of templates for an access switch specified like this:

ACCESS:
    entrypoint: access.j2
    dependencies:
        - managed-full.j2

This indicates that the starting point for the template of access switches for this platform is deffined in the Jinja2 template file called “access.j2”. Additionally, this template file will depend on things defined in a file called “managed-full.j2”.

The template files themselves are written using the Jinja2 templating language. Variables that are exposed from CNaaS includes:

  • hostname: Short hostname of device

  • host: Short hostname of device (implicitly added by nornir-jinja2)

  • mgmt_ip: IPv4 management address (ex 192.168.0.10)

  • mgmt_ipif: IPv4 management address including prefix length (ex 192.168.0.10/24)

  • mgmt_prefixlen: Just the prefix length (ex 24)

  • mgmt_vlan_id: VLAN id for management (ex 10)

  • mgmt_gw: IPv4 address for the default gateway in the management network

  • uplinks: A list of uplink interfaces, each interface is a dictionary with these keys:

    • ifname: Name of the physical interface (ex Ethernet1)

  • access_auto: A list of access_auto interfacs. Using same keys as uplinks.

  • device_model: Device model string, same as “model” in the device API. Can be used if you need model specific configuration lines.

  • device_os_version: Device OS version string, same as “os_version” in the device API. Can be used if you need OS version specific configuration lines.

  • device_id: CNaaS-NMS internal ID number of the device

  • stack_members: CNaaS-NMS stack members if they are include. Each stackmember has a hardware id, and member number, priority is optional.

Additional variables available for distribution switches:

  • infra_ip: IPv4 infrastructure VRF address (ex 10.199.0.0)

  • infra_ipif: IPv4 infrastructure VRF address inc prefix (ex 10.199.0.0/32)

  • vrfs: A list of dictionaries with two keys: “name” and “rd” (rd as in Route Distinguisher). Populated from settings defined in routing.yml.

  • bgp_ipv4_peers: A list of dictionaries with the keys: “peer_hostname”, “peer_infra_lo”, “peer_ip” and “peer_asn”. Contains one entry per directly connected dist/core device, used to build an eBGP underlay for the fabric. Populated from the links database table.

  • bgp_evpn_peers: A list of dictionaries with the keys: “peer_hostname”, “peer_infra_lo”, “peer_asn”. Contains one entry per hostname specified in settings->evpn_peers. Used to build eBGP peering for EVPN between loopbacks.

  • mgmtdomains: A list of dictionaries with the keys: “ipv4_gw”, “vlan”, “description”, “esi_mac”. Populated from the mgmtdomains database table.

  • asn: A private unique Autonomous System number generated from the last two octets of the infra_lo IP address on the device.

All settings configured in the settings repository are also exposed to the templates.

settings

Settings are defined at different levels and inherited (possibly overridden) in several steps. For example, NTP servers might be defined in the “global” settings to impact the entire managed network, but then overridden for a specific device type that needs custom NTP servers. The inheritence is defined in these steps: Global -> Fabric -> Core/Dist/Access -> Group -> Device specific. The directory structure looks like this:

  • global

    • groups.yml: Definition of custom device groups

    • routing.yml: Definition of global routing settings like fabric underlay and VRFs

    • vxlans.yml: Definition of VXLAN/VLANs

    • base_system.yml: Base system settings

  • fabric (core+dist)

    • base_system.yml: Base system settings

  • core

    • base_system.yml: Base system settings

    • interfaces_<model>.yml: Model specific default interface settings

  • dist

    • base_system.yml: Base system settings

    • interfaces_<model>.yml: Model specific default interface settings

  • access:

    • base_system.yml: Base system settings

  • groups:

    • <group name>

      • base_system.yml

      • interfaces.yml

      • routing.yml

  • devices:

    • <hostname>

      • base_system.yml

      • interfaces.yml

      • routing.yml

groups.yml:

A device in CNaaS-NMS will be a member of exactly one primary group, and optionally any number of secandary groups. Primary groups can be used to configure settings per group. Secondary groups can be used to assign VXLAN memberships, select devices for synchronization or firmware upgrade etc.

groups.yml contains a dictionary named “groups”, that contains a list of groups. Each group is defined as a dictionary with a single key named “group”, and that key contains a dictionary with two keys:

  • name: A string representing a name. No spaces.

  • regex: A Python style regex that matches on device hostnames.

  • group_priority: Optional integer value 0-100. Specifies which group should have the highest priority when determining the primary group for a device. Higher value means higher priority. Defaults to 0, value of 1 is reserved for builtin group DEFAULT.

There will always exist a group called DEFAULT with group_priority 1 even if it’s not specified in groups.yml.

All devices that matches the regex will be included in the group.

---
groups:
  - group:
      name: 'ALL'
      regex: '.*'
  - group:
      name: 'BORDER_DIST'
      regex: '(south-dist0[1-2]|north-dist0[1-2])'
  - group:
      name: 'DIST_EVEN'
      regex: '.*-dist[0-9][02468]'
  - group:
      name: 'DIST_ODD'
      regex: '.*-dist[0-9][13579]'
  - group:
      name: 'E1'
      regex: 'eosdist1$'
      group_priority: 100
  - group:
      name: 'E'
      regex: 'eosdist.*'
      group_priority: 99

routing.yml:

Can contain the following dictionaries with specified keys:

  • underlay:

    • infra_link_net: A /16 of IPv4 addresses that CNaaS-NMS can use to automatically assign addresses for infrastructure links from (ex /31 between dist-core).

    • infra_lo_net: A /16 of IPv4 addresses that CNaaS-NMS can use to automatically assign addresses for infrastructure loopback interfaces from.

    • mgmt_lo_net: A subnet for management loopbacks for dist/core devices.

    • bgp_asn: Optional BGP autonomous system number, useful for iBGP underlay.

  • evpn_peers:

    • hostname: A hostname of a CORE (or DIST) device from the device database. The other DIST switches participating in the VXLAN/EVPN fabric will establish eBGP connections to these devices. If an empty list is provided all CORE devices will be added as evpn_peers instead.

  • vrfs:

    • name: The name of the VRF. Should be one word (no spaces).

    • vrf_id: An integer between 1-65535. This ID can be used to generate unique VNI, RD and RT values for this VRF.

    • groups: A list of groups this VRF should be provisioned on.

    • import_route_targets: A list of strings containing extra route targets to import for route leaking (optional)

    • export_route_targets: A list of strings containing extra route targets to export for route leaking (optional)

    • import_policy: A string containing route policy/route map to define import behavior, useful in route leaking scenarios (optional)

    • export_policy: A string containing route policy/route map to define export behavior, useful in route leaking scenarios (optional)

  • extroute_static:

    • vrfs:

      • name: Name of the VRF

      • ipv4:

        • destination: IPv4 prefix

        • nexthop: IPv4 nexthop address

        • interface: Exiting interface (optional)

        • name: Name/description of route (optional, defaults to “undefined”)

        • cli_append_str: Custom configuration to append to this route (optional)

      • ipv6:

        • destination: IPv6 prefix

        • nexthop: IPv6 nexthop address

        • other options are the same as ipv4

  • extroute_ospfv3:

    • vrfs:

      • name: Name of the VRF

      • ipv4_redist_routefilter: Name of a route filter (route-map) that filters what should be redistributed into OSPF

      • ipv6_redist_routefilter: Name of a route filter (route-map) that filters what should be redistributed into OSPF

      • cli_append_str: Custom configuration to add for this VRF (optional)

  • extroute_bgp:

    • vrfs:

      • name: Name of the VRF

      • local_as: AS number that CNaaS NMS devices will present themselves as

      • cli_append_str: Custom configuration to append to BGP VRF config (optional)

      • neighbor_v4:

        • peer_as: AS number the remote peer

        • peer_ipv4: IPv4 address of peer

        • route_map_in: Route-map to filter incoming routes

        • route_map_out: Route-map to filter outgoing routes

        • ebgp_multihop: Configure eBGP multihop/TTL security, integer 1-255

        • bfd: Set to true to enable Bidirectional Forward Detection (BFD)

        • graceful_restart: Set to true to enable capability graceful restart

        • next_hop_self: Set to true to always advertise this router’s address as the BGP next hop

        • maximum_routes: Maximum routes to receive from peer, integer 0-4294967294

        • update_source: Specify local source interface for the BGP session

        • auth_string: String used to calculate MD5 hash for authentication (password)

        • description: Description of remote peer (optional, defaults to “undefined”)

        • cli_append_str: Custom configuration to append to this peer (optional)

      • neighbor_v6:

        • peer_ipv6: IPv6 address of peer

        • other options are the same as neighbor_v4

  • prefix_sets: Dictionary of {<name>, <entry>}:

    • mode: String, either “ipv4”, “ipv6” or “mixed”

    • prefixes: list of

      • prefix: String for ipv4 or ipv6 prefix, ex: 10.0.0.0/8

      • masklength_range: Optional string defining range of prefixes to match, ex: 24-32 or 32-32

  • routing_policies: Dictionary of {<name>, <entry>}:

    • statements: List of:

      • action: Action to perform on match, either “accept” or “reject”

      • conditions: List of:

        • match_type: String, ex “ipv4 prefix-set”

        • match_target: String, referring to prefix-set for example: “default-route”

routing.yml examples:

---
extroute_bgp:
  vrfs:
    - name: OUTSIDE
      local_as: 64667
      neighbor_v4:
        - peer_ipv4: 10.0.255.1
          peer_as: 64666
          route_map_in: fw-lab-in
          route_map_out: default-only-out
          description: "fw-lab"
          bfd: true
          graceful_restart: true
extroute_static:
  vrfs:
    - name: MGMT
      ipv4:
        - destination: 172.12.0.0/24
          nexthop: 10.0.254.1
          name: cnaas-mgmt
prefix_sets:
  "default":
    mode: "ipv4"
    prefixes:
      - prefix: 0.0.0.0/0
        masklength_range: 0
  "24_or_longer":
    mode: "ipv4"
    prefixes:
      - prefix: 0.0.0.0/0
        masklength_range: 24-32
  "v6default":
    mode: "ipv6"
    prefixes:
      - prefix: ::/0
  "all-ipv6":
    mode: "ipv6"
    prefixes:
      - prefix: ::/0
        masklength_range: 0-128
routing_policies:
  "allow_default":
    statements:
      - action: "accept"
        conditions:
          - match_type: "ipv4 prefix-set"
            match_target: "default"
  "allow_all_v6":
    statements:
      - action: "accept"
        conditions:
          - match_type: "ipv6 prefix-set"
            match_target: "all-ipv6"

vxlans.yml:

Contains a dictinary called “vxlans”, which in turn has one dictinoary per vxlan, vxlan name is the dictionary key and dictionaly values are:

  • vxlans: Dictionary of {<name>, <entry>}:

    • vni: VXLAN ID, 1-16777215

    • vrf: VRF name. Optional unless ipv4_gw is also specified.

    • vlan_id: VLAN ID, 1-4095

    • vlan_name: VLAN name, single word/no spaces, max 31 characters

    • ipv4_gw: IPv4 gateway address in CIDR notation, ex: 192.168.0.1/24. Optional.

    • ipv4_secondaries: List of IPv4 addresses in CIDR notation. Optional.

    • ipv6_gw: IPv6 address, ex: fe80::1. Optional.

    • dhcp_relays: DHCP relay address. Optional.

    • mtu: Define custom MTU. Optional.

    • acl_ipv4_in: Access control list to apply for ingress IPv4 traffic to routed interface. Optional.

    • acl_ipv4_out: Access control list to apply for egress IPv4 traffic from routed interface. Optional.

    • acl_ipv6_in: Access control list to apply for ingress IPv6 traffic to routed interface. Optional.

    • acl_ipv6_out: Access control list to apply for egress IPv6 traffic from routed interface. Optional.

    • cli_append_str: Optional. Custom configuration to append to this interface.

    • tags: List of custom strings to tag this VXLAN with. Optional.

    • groups: List of group names where this VXLAN/VLAN should be provisioned. If you select an access switch the parent dist switch should be automatically provisioned.

    • devices: List of device names where this VXLAN/VLAN should be provisioned. Optional.

interfaces.yml:

For dist and core devices interfaces are configured in YAML files. The interface configuration can either be done per device, or per device model. If there is a device specific folder under devices/ then the model interface settings will be ignored. Model specific YAML files should be named like the device model as listed in the devices API, but in all lower-case and with all whitespaces replaced with underscore (“_”).

Keys for interfaces.yml or interfaces_<model>.yml:

  • interfaces: List of dicctionaries with keys:

    • name: Interface name, like “Ethernet1”. Can also be an interface range like “Ethernet[1-4]”.

    • ifclass: Interface class, one of: downlink, fabric, custom, port_template_*

    • config: Optional. Raw CLI config used in case “custom” ifclass was selected

  • Additional interface options for port_template type:

    • untagged_vlan: Optional. Numeric VLAN ID for untagged frames.

    • tagged_vlan_list: Optional. List of allowed numeric VLAN IDs for tagged frames.

    • description: Optional. Description for the interface, this should be a string 0-64 characters.

    • enabled: Optional. Set the administrative state of the interface. Defaults to true if not set.

    • aggregate_id: Optional. Identifier for configuring LACP etc. Integer value. Special value -1 means configure MLAG and use ID based on indexnum.

    • tags: Optional list of strings, custom user defined tags to apply.

    • vrf: Optional VRF instance, must be specified if IP adress is specified

    • ipv4_address: Optional IPv4 address for the interface

    • ipv6_address: Optional IPv6 address for the interface

    • mtu: Optional integer specifying MTU size

    • acl_ipv4_in: Access control list to apply for ingress IPv4 traffic to interface. Optional.

    • acl_ipv4_out: Access control list to apply for egress IPv4 traffic from interface. Optional.

    • acl_ipv6_in: Access control list to apply for ingress IPv6 traffic to interface. Optional.

    • acl_ipv6_out: Access control list to apply for egress IPv6 traffic from interface. Optional.

    • cli_append_str: Optional. Custom configuration to append to this interface.

The “downlink” ifclass is used on DIST devices to specify that this interface is used to connect access devices. The “fabric” ifclass is used to specify that this interface is used to connect DIST or CORE devices with each other to form the switch (vxlan) fabric. Linknet data will only be configured on interfaces specified as “fabric”. If no linknet data is available in the database then the fabric interface will be configured for ZTP of DIST/CORE devices by providing DHCP (relay) access. “port_template_*” is used to specify a user defined port template. This can then be used to apply some site-specific configuration via Jinja templates. For example specify “port_template_hypervisor” and build a corresponding Jinja template by matching on that ifclass.

base_system.yml:

Contains base system settings like:

  • ntp_servers: List of

    • host: IP address or hostname of NTP server

  • snmp_servers: List of

    • host: IP address or hostname of SNMP trap target

    • port: Port number. Optional

  • dns_servers: List of

    • host: IP address to DNS server

  • syslog_servers: List of

    • host: IP address or hostname to syslog server

    • port: Port number. Optional

  • flow_collectors: List of

    • host: IP address or hostname to flow collector

    • port: Port number. Optional

  • dhcp_relays: List of

    • host: IP address or hostname to DHCP relay

  • users: List of

    • username: Username string

    • ssh_key: SSH public key string. Optional

    • uid: UserID number. Optional

    • password_hash_arista: Hashed password string for Arista devices. Optional

    • password_hash_cisco: Hashed password string for Cisco devices. Optional

    • password_hash_juniper: Hashed password string for Juniper devices. Optional

    • permission_arista: String to specify user access level for Arista, ex “privilege 15 role network-admin”. Optional

    • permission_cisco: String to specify user access level for Cisco, ex “privilege 15”. Optional

    • permission_juniper: String to specify user access level for Juniper, ex “superuser”. Optional

    • groups: A list of device groups that this user should be provisioned on

  • internal_vlans:

    • vlan_low: Low end of internal VLAN range

    • vlan_high: High end of internal VLAN range

    • allocation_order: Allocation order, default “ascending”

  • dot1x_fail_vlan: Numeric ID of authentication fail VLAN

  • dot1x_multi_host: Allow multiple clients behind a dot1x authenticated port. Default false

  • poe_reboot_maintain: Maintain POE supply during reboot of the switch. Default false

  • organization_name: Free format string describing organization name

  • domain_name: DNS domain (suffix)

Example of base_system.yml:

---
ntp_servers:
  - host: 10.255.0.1
  - host: 10.255.0.2
snmp_servers:
  - host: 10.255.0.11
dns_servers:
  - host: 10.255.0.1
  - host: 10.255.0.2
syslog_servers:
  - host: 10.255.0.21
  - host: 10.255.0.22
flow_collectors:
  - host: 10.255.0.30
    port: 6343
dhcp_relays:
  - host: 10.255.1.1
  - host: 10.255.1.2
internal_vlans:
  vlan_id_low: 3006
  vlan_id_high: 4094
dot1x_fail_vlan: 13

internal_vlans can optionally be specified if you want to manually define the range of internal VLANs on L3 switches. You can also specify the option “allocation_order” under internal_vlans which is a custom string that defaults to “ascending”. If internal_vlans is specified then a collision check will be performed for any defined vlan_ids in vxlans settings.

etc

Configuration files for system daemons

Directory structure:

  • dhcpd/

    • dhcpd.conf: Used for ZTP DHCPd