wiki:NCGFiles

NCG produces a multitude of output files from a variety of input files. This page describes all those files, and how they are organized.

Output Files

Note: All filenames on this page are relative to the ~ncg/ietf75 directory.

configs/ directory

All generated files are kept in the configs/ directory.

configs/ap/ directory

The configs/ap/ directory contains all generated config files that relate to APs.

configs/ap/configs/ directory

The configs/ap/configs/ directory contains the generated config files for all APs.

configs/ap/router.db

The configs/ap/router.db file is the generated config file for using RANCID to manage the APs.

configs/rtr/ directory

The configs/rtr/ directory contains all generated config files that relate to routers.

configs/rtr/configs/ directory

The configs/rtr/configs/ directory contains the generated config files for all routers.

configs/rtr/router.db

The configs/rtr/router.db file is the generated config file for using RANCID to manage the routers.

configs/switch/ directory

The configs/switch/ directory contains all generated config files that relate to switches.

configs/switch/configs/ directory

The configs/switch/configs/ directory contains the generated config files for all switches.

configs/switch/router.db

The configs/switch/router.db file is the generated config file for using RANCID to manage the switches.

configs/dns/ directory

The configs/dns/ directory contains the generated config files for DNS.

configs/dns/dns.txt

The configs/dns/dns.txt file is the generated DNS forward-lookup data file, containing "A", "AAAA", and "CNAME" records.

configs/dns/in-addr.arpa.txt

The configs/dns/in-addr.arpa.txt file is the generated DNS reverse-lookup data file for IP addresses, containing "PTR" records in the "in-addr.arpa" domain.

configs/dns/ip6.arpa.txt

The configs/dns/ip6.arpa.txt file is the generated DNS reverse-lookup data file for IPv6 addresses, containing "PTR" records in the "ip6.arpa" domain.

Input Files

NCG relies on a large number of input files. They are listed here roughly in order of likelihood that you might need to edit them, rather than alphabetically.

Note: All filenames on this page are relative to the ~ncg/ietf75 directory.

The input files are of 3 types:

  • ncg files (which are typically named with the extension ".ncg") are used by NCG as templates for generating config files (or subsections of those files) for various network devices and services, using the Embedded Ruby (ERB) mechanism (which is sometimes also referred to as "eRuby"). See the ncg files documentation for complete details.
  • neto files describe various aspects of the network. Their names usually end in ".neto". See the neto file documentation for details about their syntax and content.
  • neto_table files also describe various aspects of the network, but in tabular (row/column) form, which is more convenient for some types of data (a list of VLANs with parameters for each, for example). Directives at the top of the file (or in a separate file) specify how to process each row of data in the file. The contents of any neto_table file could be expressed as a neto file; the neto_table format is a shortcut, because certain data is more naturally managed in tabular form. See the neto_table file documentation for details about their syntax and content.

Note: Note that neto_table files (such as the vlans file, described below) are very sensitive to spaces and tabs. In general, you need to follow the following rules:

  • Fields are separated by one or more tabs (not spaces). Multiple tabs can be used so that the columns line up neatly in an editor.
  • Since multiple consecutive tabs constitute a single field separator, if you want a field to be "undefined" for a particular row, you need to use a single dash ("-") for that field. ncg will recognize this and treat it specially.
  • Fields (columns) are named in the line that begins with '%', at the top of the file. Just like in data lines, field names are separated by one or more tabs (not spaces).
  • Every data line must have the same number of fields as are listed in the name line (the one that begins with '%').
  • Comments begin with '#', and everything from there to the end of the line is ignored.
  • Long rows can be split over multiple lines by putting a backslash ('\') at the end of each intermediate line. All rules (i.e., fields are separated by one or more consecutive tabs) still apply.
  • Lines at the top of the file that begin with '+', '@', and '<' are directives that tell ncg what to do with each row of data in the file. See the neto_table docs for more information.
    • The '<' lines are a new feature recently added to the pre-release version of ncg that we're using, and haven't made it into the main documentation yet. Basically, they are of the following form (which basically says: "for each line of data, in the context of key, process the file filename."):
        < key filename
      

ietf.neto

The ietf.neto file is the top-level file describing the network. It first sets a number of basic parameters describing the network (base IP and IPv6 addresses, DNS domain name and server addresses, addresses of the servers for various services); some of these parameters are set directly, and others indirectly via "table" directives. Then, files describing the various network devices are included by reference (the "include" lines near the end of the file).

users

The users table contains the login names, UIDs, and MD5 authentication hashes for all users who should have accounts on all devices.

vlans

The vlans file lists all of the VLANs used in the network. For each VLAN, the following information is provided:

  • id -- the VLAN number.
  • name -- a human-meaningful name for the VLAN.
  • ip -- the IP network/netmask (in the form "nnn.nnn.nnn.nnn/bits") for this VLAN. Should be "-" if IP should not be used on this VLAN.
  • ipv6 -- the IPv6 network/netmask (in the form "xxxx:xxxx::/bits") for this VLAN. Should be "-" if IPv6 should not be used on this VLAN.
  • vrrp -- specifies whether the routers should provide a default gateway address (xxx.xxx.xxx.1) on the VLAN via VRRP. Anything that begins with a "y" (upper or lower case) means yes; anything else means "no".
  • bootp -- specifies whether the routers should be configured for bootp-helper and DHCP-relay on this VLAN. Anything that begins with a "y" (upper or lower case) means yes; anything else means "no".

The vlans file is used with a variety of different header files, for different reasons; for example:

  • In ietf.neto, it is used with the vlans.hdr file to populate the !vlans!... part of the network description tree.
  • In rtr/_rtr.neto, it is used with the rtr/_vlan_interfaces.hdr to create VLAN interfaces for each VLAN on each router.

vlans.hdr

The vlans.hdr file is used in the ietf.neto file in conjunction with the vlans file to populate the !vlans!... part of the network description tree.

snmp.*

These files are tables which populate various parameters for SNMP. These parameters are then used, in turn, to generate the SNMP sections of the config files for various network devices.

snmp.communities

The snmp.communities file lists the community names and modes (in Cisco nomenclature) that should be defined on each device.

snmp.servers

The snmp.servers file lists the SNMP servers that should be defined on each device, for SNMP traps to be sent to.

snmp.v3_groups

The snmp.v3_groups file lists the groups that should be defined on each device for SNMP v3.

snmp.v3_users

The snmp.v3_users file lists the users that should be defined on each device for SNMP v3.

functions.rb

The functions.rb file contains various utility functions (methods) written in Ruby, for use by templates (.ncg files). Each main template file (i.e., ap/templates/ap.ncg, rtr/templates/juniper.ncg, and switch/templates/cisco.ncg) has the following line near the top, to pull in these utility functions:

<% require "functions.rb" -%>

ap/ directory

The ap/ directory contains AP-specific data files and templates.

ap/ap.neto

The ap/ap.neto file is the main file that specifies what to do with all the other files in the ap/ directory. This is the file that is referenced in the top-level ietf.neto file.

ap/devices

The ap/devices file is a neto_table file that lists the AP devices and info about each of them:

  • name -- the short name of the AP
  • id -- a unique ID number for the AP.
    • It should be unique across all devices (APs, routers, and switches).
    • By convention, AP id numbers start at 100.
    • No AP id should exceed 254, since one use of the id is to calculate the AP's IP address on the Management VLAN.
    • Therefore, as currently implemented, there can be a maximum of 154 APs (numbered "100" to "253") on the network. If the "AP id numbers start at 100" convention is relaxed, there could be a total of 253 APs, routers, and switches on the network; to grow beyond that, the IP address space allocated to the Management VLAN would need to be bigger than the current /24.
  • class -- the "class" of the device (i.e., "ap").
  • make -- the "make" of the device (i.e., "cisco"). This is used in working out which config file template to use, and in generating the RANCID router.db file.
  • model -- the "model" of the device (i.e., "A1250"). This is used in working out which config file template to use.
  • location -- a string describing where the AP is installed (used to set the location reported by SNMP, among other things)

The directives at the top of the ap/devices file establish a number of parameters for the device in the NCG network model:

  • The device's entry in the model starts with a template of all the radio and VLAN interfaces on the device, which is generated from data in the ap/ssids file (described below)
  • The device's name, ID, class, make, model, and location are set directly from data in the row for the device.
  • The device's "pki_file" filename is determined. This file, if it exists, contains the PKI (Public Key Infrastructure) config lines for the device.
  • The device's config template ("ncg_template") is determined from the device's make and model as ap/templates/<i>make</i>-<i>model</i>.ncg file.
  • The location for the device's generated config file is established in the configs/ap/configs directory.
  • A "BVI1" interface is added to the device's interface spec.
    • This must be done here, rather than via the !templates!devices!ap template (which is created from the ap/ssids table), because this interface is assigned an IP address based on this particular device's id number.
    • In addition to the IP address and netmask assigned to this interface, a dns_name is defined for the device, which will cause appropriate DNS forward and reverse data records to be generated mapping this device's name to its management (BVI1, on VLAN1) IP address and vice versa.
  • Finally, the device is added to the !services!rancid part of the network model, so that it will be added to the appropriate router.db file for RANCID (in this case, the configs/ap/router.db file).

ap/ssids

The ap/ssids neto_table file lists the names and characteristics of the WiFi? SSIDs that are created in the network.

  • ssid -- SSID of wifi network
  • vlan -- VLAN number for this SSID
  • wpa -- Is WPA enabled on this SSID?
  • mbssid -- Is mbssid enabled on this SSID? (should be either "guest" or "none")
  • radio0 -- Is this SSID defined on Radio0?
    • NOTE: If an SSID is defined on a particular radio, it is assumed to be active on that radio as well.
    • It can be deactivated through the ap/override.active file.
  • radio1 -- Is this SSID defined on Radio1? (see note above for "radio0" regarding activating/deactivating the SSID)
  • native -- Is this VLAN marked "native" on Radio and GigE interfaces?

For each row in the file, the directives at the top of the file establish a number of entries in the NCG network model:

  • An entry for the SSID is made in the main !ssids list in the model.
  • Interfaces on both Radio0 and Radio1 are added to a template (which, in turn, is used by directives in the ap/devices file to pre-populate the interfaces!... section of each AP's entry in the model).

ap/overrides.*

The ap/overrides.* provide convenient ways to override various default parameters (active/inactive, power, and speed) for specific interfaces on specific devices.

ap/overrides.active

By default, every defined interface and SSID is active on every AP. The ap/overrides.active file gives an easy way to override that default setting for particular interfaces on particular APs.

ap/overrides.power

By default, every defined SSID on every AP uses a power setting that is established in the ap/ap.neto file. The ap/overrides.power file gives an easy way to override that default for particular interfaces on particular APs.

ap/overrides.speed

By default, every defined SSID on every AP uses a speed setting that is established in the ap/templates/interfaces/*.ncg file for that particular interface. The ap/overrides.speed file gives an easy way to override that default for particular interfaces on particular APs.

ap/pki.d/ directory

This directory contains optional per-device files with PKI (Public Key Infrastructure) parameters for the named device. For a device named apXXX, if a file named ap/pki.d/apXXX.pki exists, then it is incorporated into the generated config file for the apXXX device.

ap/append.d/ directory

This directory contains optional per-device files with lines to be added to the end of the generated config file for the named device. For a device named apXXX, if a file named ap/append.d/apXXX exists, then it is appended to the generated config file for the apXXX device. These files are run through the ERB processor just like all other template files, so they can contain embedded Ruby directives as well as plain text.

ap/templates/ directory

The ap/templates/ directory contains templates for the config files for various types of devices.

ap/templates/cisco-ap.ncg

The ap/templates/cisco-ap.ncg file is the generic config file template for a Cisco AP. Templates for a particular model might simply be a symlink to this file (i.e., as ap/templates/cisco-A1250.ncg is), or might start as a copy of this file.

ap/templates/interfaces/ directory

The ap/templates/interfaces/ directory contains template fragments for particular types of interfaces. These are referred to by ncg_template keys in interface defintions; see the areas where interfaces are defined in the ap/ap.neto, ap/ssids, and ap/devices files, for example.

rtr/ directory

The rtr/ directory contains router-specific data files and templates.

rtr/rtr.neto

The rtr/rtr.neto file is the main file that specifies what to do with all the other files in the rtr/ directory. This is the file that is referenced in the top-level ietf.neto file.

rtr/devices

The rtr/devices file is a neto_table file that lists the routers and info about each of them:

  • name -- the short name of the router.
  • id -- a unique ID number for the router.
    • It should be unique across all devices (APs, routers, and switches).
    • By convention, router id numbers start at 2.
    • No router id should exceed 254, since one use of the id is to calculate the router's IP address on various VLANs (particularly the Management VLAN).
    • Therefore, as currently implemented, there can be a maximum total of 253 APs, routers, and switches on the network; to grow beyond that, the IP address space allocated to the Management VLAN would need to be bigger than the current /24.
  • class -- the "class" of the device (i.e., "rtr").
  • make -- the "make" of the device (i.e., "juniper"). This is used in working out which config file template to use, and in generating the RANCID router.db file.
  • model -- the "model" of the device (i.e., "M7100"). This is used in working out which config file template to use.
  • location -- a string describing where the router is installed (used to set the location reported by SNMP, among other things)

The directives at the top of the rtr/devices file establish a number of parameters for the device in the NCG network model:

  • The device's name, ID, class, make, model, and location are set directly from data in the row for the device.
  • The _rtr.neto file is processed in the context of this device (see below for a description of the rtr/_rtr.neto file and what it does).

rtr/_rtr.neto

The rtr/_rtr.neto file is what does most of the work of setting up the info for a particular router in the NCG network model. It is invoked in the context of each data line in the rtr/devices file, to set up various NCG network model entries for the device listed on that line:

  • Specify the filenames of the config template (rtr/templates/make-model.ncg and generated config file (configs/rtr/configs/rtr_name).
  • Add all the basic interfaces for the router (via a neto_table made by combining the generic rtr/_interfaces.hdr file with a device-specific file named rtr_name.interfaces).
  • Add all the VLAN interfaces for the router (via a neto_table made by combining the generic rtr/_vlan_interfaces.hdr file with the top-level vlans file).
  • Add all the IPv6 tunnel interfaces for the router (via a neto_table made by combining the generic rtr/_ipv6_tunnels.hdr file with a device-specific file named rtr_name.ipv6_tunnels).
  • Add IP addresses for certain Ethernet interfaces for the router (via a neto_table made by combining the generic rtr/_ethernet_interfaces.hdr file with a device-specific file named rtr_name.ethernet_interfaces).
  • Add static routes for the router (via a neto_table made by combining the generic rtr/_static_routes.hdr file with a device-specific file named rtr_name.static_routes).
  • Add a loopback interface for the router, with appropriate IP and IPv6 addresses.
  • Specify the name of the file containing BGP configuration directives for the router. This file is incorporated verbatim into the generated config file.
  • Specify the name of the file containing routing policy directives for the router. This file is incorporated verbatim into the generated config file.
  • Add the device to the !services!rancid part of the network model, so that it will be added to the appropriate router.db file for RANCID (in this case, the configs/rtr/router.db file).

rtr/*.interfaces and rtr/_interfaces.hdr

rtr/rtr_name.interfaces is a device-specific file that lists all the basic interfaces for a particular router. The rtr/_rtr.neto file uses it in conjunction with the generic rtr/_interfaces.hdr file to add all these interfaces to the NCG network model.

rtr/*.vlan_interfaces and rtr/_vlan_interfaces.hdr

rtr/rtr_name.vlan_interfaces is a device-specific file that lists all the VLAN interfaces for a particular router. The rtr/_rtr.neto file uses it in conjunction with the generic rtr/_vlan_interfaces.hdr file to add all these interfaces to the NCG network model.

rtr/*.ipv6_tunnels and rtr/_ipv6_tunnels.hdr

rtr/rtr_name.ipv6_tunnels is a device-specific file that lists all the IPv6 tunnels for a particular router. The rtr/_rtr.neto file uses it in conjunction with the generic rtr/_ipv6_tunnels.hdr file to add all these interfaces to the NCG network model.

rtr/*.ethernet_interfaces and rtr/_ethernet_interfaces.hdr

rtr/rtr_name.ethernet_interfaces is a device-specific file that lists all the Ethernet interfaces with IP addresses for a particular router. The rtr/_rtr.neto file uses it in conjunction with the generic rtr/_ethernet_interfaces.hdr file to add the IP address info for these interfaces to the NCG network model.

rtr/*.static_routes and rtr/_static_routes.hdr

rtr/rtr_name.static_routes is a device-specific file that lists all the static routes for a particular router. The rtr/_rtr.neto file uses it in conjunction with the generic rtr/_static_routes.hdr file to add those static routes to the NCG network model.

rtr/*.bgp

Contains BGP configuration directives for the router. This file is incorporated verbatim into the generated config file.

rtr/*.policy_options

Contains routing policy directives for the router. This file is incorporated verbatim into the generated config file.

rtr/append.d/ directory

This directory contains optional per-device files with lines to be added to the end of the generated config file for the named device. For a device named rtrX, if a file named rtr/append.d/rtrX exists, then it is appended to the generated config file for the rtrX device. These files are run through the ERB processor just like all other template files, so they can contain embedded Ruby directives as well as plain text.

rtr/templates/ directory

The rtr/templates/ directory contains templates for the config files for various types of devices.

rtr/templates/juniper.ncg

The rtr/templates/juniper.ncg file is the generic config file template for a Juniper router. Templates for a particular model might simply be a symlink to this file (i.e., as rtr/templates/juniper-M7100.ncg is), or might start as a copy of this file.

rtr/templates/interfaces/ directory

The rtr/templates/interfaces/ directory contains template fragments for particular types of interfaces. These are referred to by ncg_template keys in interface defintions; see the areas where interfaces are defined in the rtr/_*.hdr files, for example.

switch/ directory

The switch/ directory contains switch-specific data files and templates.

switch/switch.neto

The switch/switch.neto file is the main file that specifies what to do with all the other files in the switch/ directory. This is the file that is referenced in the top-level ietf.neto file.

switch/devices

The switch/devices file is a neto_table file that lists the switches and info about each of them:

  • name -- the short name of the router.
  • id -- a unique ID number for the router.
    • It should be unique across all devices (APs, routers, and switches).
    • By convention, router id numbers start at 20 and are less than 100.
    • No switch id should exceed 254, since one use of the id is to calculate the switch's IP address on various VLANs (particularly the Management VLAN).
    • Therefore, as currently implemented, there can be a maximum total of 253 APs, routers, and switches on the network; to grow beyond that, the IP address space allocated to the Management VLAN would need to be bigger than the current /24.
  • class -- the "class" of the device (i.e., "switch").
  • make -- the "make" of the device (i.e., "cisco"). This is used in working out which config file template to use, and in generating the RANCID router.db file.
  • model -- the "model" of the device (i.e., "WS-3560-8PC-S"). This is used in working out which config file template to use.
  • location -- a string describing where the router is installed (used to set the location reported by SNMP, among other things)

The directives at the top of the switch/devices file establish a number of parameters for the device in the NCG network model:

  • The device's name, ID, class, make, model, and location are set directly from data in the row for the device.
  • The _switch.neto file is processed in the context of this device (see below for a description of the switch/_switch.neto file and what it does).

switch/_switch.neto

The switch/_switch.neto file is what does most of the work of setting up the info for a particular switch in the NCG network model. It is invoked in the context of each data line in the switch/devices file, to set up various NCG network model entries for the device listed on that line:

  • Specify the filenames of the config template (switch/templates/make-model.ncg and generated config file (configs/switch/configs/switch_name).
  • Specify the device's "pki_file" filename. This file, if it exists, contains the PKI (Public Key Infrastructure) config lines for the device.
  • Add all the interfaces for the switch (via a neto_table made by combining the generic switch/_interfaces.hdr file with a device-specific file named switch_name.interfaces).
  • Add the device to the !services!rancid part of the network model, so that it will be added to the appropriate router.db file for RANCID (in this case, the configs/switch/router.db file).

switch/*.interfaces and switch/_interfaces.hdr

switch/switch_name.interfaces is a device-specific file that lists all the basic interfaces for a particular switch. The switch/_switch.neto file uses it in conjunction with the generic switch/_interfaces.hdr file to add all these interfaces to the NCG network model.

switch/SAMPLE/ directory

The switch/SAMPLE/ directory contains sample *.interfaces files for particular models of Cisco switches. These list all the interfaces that are standard on that model, and can be a handy starting point for creating the *.interfaces file for a particular switch.

switch/append.d/ directory

This directory contains optional per-device files with lines to be added to the end of the generated config file for the named device. For a device named switchX, if a file named switch/append.d/switchX exists, then it is appended to the generated config file for the switchX device. These files are run through the ERB processor just like all other template files, so they can contain embedded Ruby directives as well as plain text.

switch/templates/ directory

The switch/templates/ directory contains templates for the config files for various types of devices.

switch/templates/cisco.ncg

The switch/templates/cisco.ncg file is the generic config file template for a Cisco switch. Templates for a particular model might simply be a symlink to this file (i.e., as switch/templates/cisco-WS-C3560-8PC-S.ncg is), or might start as a copy of this file.

switch/templates/interfaces/ directory

The switch/templates/interfaces/ directory contains template fragments for particular types of interfaces. These are referred to by ncg_template keys in interface defintions; see the areas where interfaces are defined in switch/*.interfaces file via the switch/_interfaces.hdr files, for example.

dns/ directory

The dns/ directory contains templates for generating DNS forward and reverse-lookup data files.

dns/dns.neto

The dns/dns.neto file is the main file that specifies what to do with all the other files in the dns/ directory. This is the file that is referenced in the top-level ietf.neto file.

dns/templates directory

dns/templates/dns.ncg

The dns/templates/dns.ncg file is the template for DNS forward-lookup data files. It works by examining the entire NCG model of the network for nodes that have dns_name and dns_cname keys.

  • For nodes having a dns_name key:
    • If the node also has a ip_address key, an IP address record is generated:
        rtra-vlan1.meeting.ietf.org. IN A 130.129.1.2
      
    • If the node also has a ipv6_address key, an IPv6 address record is generated:
        rtra-vlan1.meeting.ietf.org. IN AAAA 2001:df8:0:1::2
      
  • For nodes having a dns_cname key:
    • If the node also has a dns_name key, a CNAME record is generated:
      rtra.meeting.ietf.org. IN CNAME rtra-vlan1.meeting.ietf.org.
      
    • If the node does not have a dns_cname key, an error is raised.

dns/templates/in-addr.arpa.ncg

The dns/templates/in-addr.arpa.ncg file is the template for DNS IP reverse-lookup data files. It works by examining the entire NCG model of the network for nodes that have both dns_name and ip_address keys, and generating appropriate DNS reverse lookup records for them:

  2.1.129.130.in-addr.arpa. IN PTR rtra-vlan1.meeting.ietf.org.

dns/templates/ip6.arpa.ncg

The dns/ip6.arpa.ncg file is the template for DNS IPv6 reverse-lookup data files. It works by examining the entire NCG model of the network for nodes that have both dns_name and ipv6_address keys, and generating appropriate DNS reverse lookup records for them:

  2.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.0.0.0.0.0.0.0.8.f.d.0.1.0.0.2.ip6.arpa. IN PTR rtra-vlan1.meeting.ietf.org.

rancid/ directory

The rancid/ directory contains templates for generating RANCID configuration files.

rancid/templates/router.db.ncg

The rancid/templates/router.db.ncg file is the template for generating RANCID router.db files.

Last modified 8 years ago Last modified on 24 Jul 2009, 14:05:27