Changes between Initial Version and Version 1 of NCGFiles


Ignore:
Timestamp:
24 Jul 2009, 14:05:27 (9 years ago)
Author:
brent@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • NCGFiles

    v1 v1  
     1[wiki:NCG] produces a multitude of output files from a variety of input files.  This page describes all those files, and how they are organized.
     2
     3= Output Files =
     4
     5  '''Note:''' All filenames on this page are relative to the {{{~ncg/ietf75}}} directory.
     6
     7== configs/ directory ==
     8
     9All generated files are kept in the {{{configs/}}} directory.
     10
     11=== configs/ap/ directory ===
     12
     13The {{{configs/ap/}}} directory contains all generated config files that relate to APs.
     14
     15==== configs/ap/configs/ directory ====
     16
     17The {{{configs/ap/configs/}}} directory contains the generated config files for all APs.
     18
     19==== configs/ap/router.db ====
     20
     21The {{{configs/ap/router.db}}} file is the generated config file for using RANCID to manage the APs.
     22
     23=== configs/rtr/ directory ===
     24
     25The {{{configs/rtr/}}} directory contains all generated config files that relate to routers.
     26
     27==== configs/rtr/configs/ directory ====
     28
     29The {{{configs/rtr/configs/}}} directory contains the generated config files for all routers.
     30
     31==== configs/rtr/router.db ====
     32
     33The {{{configs/rtr/router.db}}} file is the generated config file for using RANCID to manage the routers.
     34
     35=== configs/switch/ directory ===
     36
     37The {{{configs/switch/}}} directory contains all generated config files that relate to switches.
     38
     39==== configs/switch/configs/ directory ====
     40
     41The {{{configs/switch/configs/}}} directory contains the generated config files for all switches.
     42
     43==== configs/switch/router.db ====
     44
     45The {{{configs/switch/router.db}}} file is the generated config file for using RANCID to manage the switches.
     46
     47=== configs/dns/ directory ===
     48
     49The {{{configs/dns/}}} directory contains the generated config files for DNS.
     50
     51==== configs/dns/dns.txt ====
     52
     53The {{{configs/dns/dns.txt}}} file is the generated DNS forward-lookup data file, containing "A", "AAAA", and "CNAME" records.
     54
     55==== configs/dns/in-addr.arpa.txt ====
     56
     57The {{{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.
     58
     59==== configs/dns/ip6.arpa.txt ====
     60
     61The {{{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.
     62
     63= Input Files =
     64
     65NCG 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.
     66
     67  '''Note:''' All filenames on this page are relative to the {{{~ncg/ietf75}}} directory.
     68
     69The input files are of 3 types:
     70 * [http://www.netomata.com/docs/formats/ncg 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 [http://www.netomata.com/docs/formats/ncg ncg files] documentation for complete details.
     71 * [http://www.netomata.com/docs/formats/neto neto files] describe various aspects of the network.  Their names usually end in ".neto".  See the [http://www.netomata.com/docs/formats/neto neto file] documentation for details about their syntax and content.
     72 * [http://www.netomata.com/docs/formats/neto_table 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 [http://www.netomata.com/docs/formats/neto_table neto_table file] documentation for details about their syntax and content. 
     73
     74  '''Note:''' Note that [http://www.netomata.com/docs/formats/neto_table 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:
     75 * 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.
     76 * 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.
     77 * 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).
     78 * Every data line must have the same number of fields as are listed in the name line (the one that begins with '%').
     79 * Comments begin with '#', and everything from there to the end of the line is ignored.
     80 * 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.
     81 * 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 [http://www.netomata.com/docs/formats/neto_table neto_table] docs for more information.
     82   * 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''."):
     83{{{
     84  < key filename
     85}}}
     86
     87
     88== ietf.neto ==
     89
     90The {{{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).
     91
     92== users ==
     93
     94The {{{users}}} table contains the login names, UIDs, and MD5 authentication hashes for all users who should have accounts on all devices. 
     95
     96== vlans ==
     97
     98The {{{vlans}}} file lists all of the VLANs used in the network.  For each VLAN, the following information is provided:
     99
     100 * id -- the VLAN number.
     101 * name -- a human-meaningful name for the VLAN.
     102 * 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.
     103 * 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.
     104 * 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".
     105 * 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".
     106
     107The {{{vlans}}} file is used with a variety of different header files, for different reasons; for example:
     108 * In {{{ietf.neto}}}, it is used with the {{{vlans.hdr}}} file to populate the {{{!vlans!...}}} part of the network description tree.
     109 * In {{{rtr/_rtr.neto}}}, it is used with the {{{rtr/_vlan_interfaces.hdr}}} to create VLAN interfaces for each VLAN on each router.
     110
     111== vlans.hdr ==
     112
     113The {{{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.
     114
     115== snmp.* ==
     116
     117These 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.
     118
     119=== snmp.communities ===
     120
     121The {{{snmp.communities}}} file lists the community names and modes (in Cisco nomenclature) that should be defined on each device.
     122
     123=== snmp.servers ===
     124
     125The {{{snmp.servers}}} file lists the SNMP servers that should be defined on each device, for SNMP traps to be sent to.
     126
     127=== snmp.v3_groups ===
     128
     129The {{{snmp.v3_groups}}} file lists the groups that should be defined on each device for SNMP v3.
     130
     131=== snmp.v3_users ===
     132
     133The {{{snmp.v3_users}}} file lists the users that should be defined on each device for SNMP v3.
     134
     135== functions.rb ==
     136
     137The {{{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:
     138  <% require "functions.rb" -%>
     139
     140== ap/ directory ==
     141
     142The {{{ap/}}} directory contains AP-specific data files and templates.
     143
     144=== ap/ap.neto ===
     145
     146The {{{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.
     147
     148=== ap/devices ===
     149
     150The {{{ap/devices}}} file is a '''neto_table''' file that lists the AP devices and info about each of them:
     151
     152 * name -- the short name of the AP
     153 * id -- a unique ID number for the AP.
     154   * It should be unique across all devices (APs, routers, and switches).
     155   * By convention, AP ''id'' numbers start at 100. 
     156   * No AP ''id'' should exceed 254, since one use of the ''id'' is to calculate the AP's IP address on the Management VLAN.
     157   * 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.
     158 * class -- the "class" of the device (i.e., "ap").
     159 * 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.
     160 * model -- the "model" of the device (i.e., "A1250").  This is used in working out which config file template to use.
     161 * location -- a string describing where the AP is installed (used to set the location reported by SNMP, among other things)
     162
     163The directives at the top of the {{{ap/devices}}} file establish a number of parameters for the device in the NCG network model:
     164
     165 * 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)
     166 * The device's name, ID, class, make, model, and location are set directly from data in the row for the device.
     167 * The device's "pki_file" filename is determined.  This file, if it exists, contains the PKI (Public Key Infrastructure) config lines for the device.
     168 * 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.
     169 * The location for the device's generated config file is established in the {{{configs/ap/configs}}} directory.
     170 * A "BVI1" interface is added to the device's interface spec. 
     171   * 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.
     172   * 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.
     173 * 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).
     174
     175=== ap/ssids ===
     176
     177The {{{ap/ssids}}} '''neto_table''' file lists the names and characteristics of the WiFi SSIDs that are created in the network.
     178 * ssid -- SSID of wifi network
     179 * vlan -- VLAN number for this SSID
     180 * wpa -- Is WPA enabled on this SSID?
     181 * mbssid -- Is mbssid enabled on this SSID?  (should be either "guest" or "none")
     182 * radio0 -- Is this SSID defined on Radio0?
     183   * NOTE: If an SSID is defined on a particular radio, it is assumed to be active on that radio as well. 
     184   * It can be deactivated through the {{{ap/override.active}}} file.
     185 * radio1 -- Is this SSID defined on Radio1? (see note above for "radio0" regarding activating/deactivating the SSID)
     186 * native -- Is this VLAN marked "native" on Radio and GigE interfaces?
     187
     188For each row in the file, the directives at the top of the file establish a number of entries in the NCG network model:
     189
     190 * An entry for the SSID is made in the main {{{!ssids}}} list in the model.
     191 * 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).
     192
     193=== ap/overrides.* ===
     194
     195The {{{ap/overrides.*}}} provide convenient ways to override various default parameters (active/inactive, power, and speed) for specific interfaces on specific devices.
     196
     197==== ap/overrides.active ====
     198
     199By 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.
     200
     201==== ap/overrides.power ====
     202
     203By 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.
     204
     205==== ap/overrides.speed ====
     206
     207By 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.
     208
     209=== ap/pki.d/ directory ===
     210
     211This 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.
     212
     213=== ap/append.d/ directory ===
     214
     215This 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.
     216
     217=== ap/templates/ directory ===
     218
     219The {{{ap/templates/}}} directory contains templates for the config files for various types of devices.
     220
     221==== ap/templates/cisco-ap.ncg ====
     222
     223The {{{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.
     224
     225==== ap/templates/interfaces/ directory ====
     226
     227The {{{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.
     228
     229== rtr/ directory ==
     230
     231The {{{rtr/}}} directory contains router-specific data files and templates.
     232
     233=== rtr/rtr.neto ===
     234
     235The {{{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.
     236
     237=== rtr/devices ===
     238
     239The {{{rtr/devices}}} file is a '''neto_table''' file that lists the routers and info about each of them:
     240
     241 * name -- the short name of the router.
     242 * id -- a unique ID number for the router.
     243   * It should be unique across all devices (APs, routers, and switches).
     244   * By convention, router ''id'' numbers start at 2. 
     245   * 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).
     246   * 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.
     247 * class -- the "class" of the device (i.e., "rtr").
     248 * 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.
     249 * model -- the "model" of the device (i.e., "M7100").  This is used in working out which config file template to use.
     250 * location -- a string describing where the router is installed (used to set the location reported by SNMP, among other things)
     251
     252The directives at the top of the {{{rtr/devices}}} file establish a number of parameters for the device in the NCG network model:
     253
     254 * The device's name, ID, class, make, model, and location are set directly from data in the row for the device.
     255 * 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).
     256
     257=== rtr/_rtr.neto ===
     258
     259The {{{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:
     260
     261 * Specify the filenames of the config template ({{{rtr/templates/}}}''make''-''model''{{{.ncg}}} and generated config file ({{{configs/rtr/configs/}}}''rtr_name'').
     262 * 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}}}).
     263 * 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).
     264 * 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}}}).
     265 * 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}}}).
     266 * 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}}}).
     267 * Add a loopback interface for the router, with appropriate IP and IPv6 addresses.
     268 * Specify the name of the file containing BGP configuration directives for the router.  This file is incorporated verbatim into the generated config file.
     269 * Specify the name of the file containing routing policy directives for the router.  This file is incorporated verbatim into the generated config file.
     270 * 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).
     271
     272=== rtr/*.interfaces and rtr/_interfaces.hdr ===
     273
     274{{{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.
     275
     276=== rtr/*.vlan_interfaces and rtr/_vlan_interfaces.hdr ===
     277
     278{{{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.
     279
     280=== rtr/*.ipv6_tunnels and rtr/_ipv6_tunnels.hdr ===
     281
     282{{{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.
     283
     284=== rtr/*.ethernet_interfaces and rtr/_ethernet_interfaces.hdr ===
     285
     286{{{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.
     287
     288=== rtr/*.static_routes and rtr/_static_routes.hdr ===
     289
     290{{{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.
     291
     292=== rtr/*.bgp ===
     293
     294Contains BGP configuration directives for the router.  This file is incorporated verbatim into the generated config file.
     295
     296=== rtr/*.policy_options ===
     297
     298Contains routing policy directives for the router.  This file is incorporated verbatim into the generated config file.
     299
     300=== rtr/append.d/ directory ===
     301
     302This 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.
     303
     304=== rtr/templates/ directory ===
     305
     306The {{{rtr/templates/}}} directory contains templates for the config files for various types of devices.
     307
     308==== rtr/templates/juniper.ncg ====
     309
     310The {{{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.
     311
     312==== rtr/templates/interfaces/ directory ====
     313
     314The {{{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.
     315
     316== switch/ directory ==
     317
     318The {{{switch/}}} directory contains switch-specific data files and templates.
     319
     320=== switch/switch.neto ===
     321
     322The {{{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.
     323
     324=== switch/devices ===
     325
     326The {{{switch/devices}}} file is a '''neto_table''' file that lists the switches and info about each of them:
     327
     328 * name -- the short name of the router.
     329 * id -- a unique ID number for the router.
     330   * It should be unique across all devices (APs, routers, and switches).
     331   * By convention, router ''id'' numbers start at 20 and are less than 100.
     332   * 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).
     333   * 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.
     334 * class -- the "class" of the device (i.e., "switch").
     335 * 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.
     336 * model -- the "model" of the device (i.e., "WS-3560-8PC-S").  This is used in working out which config file template to use.
     337 * location -- a string describing where the router is installed (used to set the location reported by SNMP, among other things)
     338
     339The directives at the top of the {{{switch/devices}}} file establish a number of parameters for the device in the NCG network model:
     340
     341 * The device's name, ID, class, make, model, and location are set directly from data in the row for the device.
     342 * 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).
     343
     344=== switch/_switch.neto ===
     345
     346The {{{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:
     347
     348 * Specify the filenames of the config template ({{{switch/templates/}}}''make''-''model''{{{.ncg}}} and generated config file ({{{configs/switch/configs/}}}''switch_name'').
     349 * Specify the device's "pki_file" filename.  This file, if it exists, contains the PKI (Public Key Infrastructure) config lines for the device.
     350 * 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}}}).
     351 * 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).
     352
     353=== switch/*.interfaces and switch/_interfaces.hdr ===
     354
     355{{{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.
     356
     357=== switch/SAMPLE/ directory ===
     358
     359The {{{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.
     360
     361=== switch/append.d/ directory ===
     362
     363This 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.
     364
     365=== switch/templates/ directory ===
     366
     367The {{{switch/templates/}}} directory contains templates for the config files for various types of devices.
     368
     369==== switch/templates/cisco.ncg ====
     370
     371The {{{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.
     372
     373==== switch/templates/interfaces/ directory ====
     374
     375The {{{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.
     376
     377== dns/ directory ==
     378
     379The {{{dns/}}} directory contains templates for generating DNS forward and reverse-lookup data files.
     380
     381=== dns/dns.neto ===
     382
     383The {{{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.
     384
     385=== dns/templates directory ===
     386
     387==== dns/templates/dns.ncg ====
     388
     389The {{{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.
     390
     391 * For nodes having a {{{dns_name}}} key:
     392   * If the node also has a {{{ip_address}}} key, an IP address record is generated:
     393{{{
     394  rtra-vlan1.meeting.ietf.org. IN A 130.129.1.2
     395}}}
     396   * If the node also has a {{{ipv6_address}}} key, an IPv6 address record is generated:
     397{{{
     398  rtra-vlan1.meeting.ietf.org. IN AAAA 2001:df8:0:1::2
     399}}}
     400 * For nodes having a {{{dns_cname}}} key:
     401   * If the node also has a {{{dns_name}}} key, a CNAME record is generated:
     402{{{
     403rtra.meeting.ietf.org. IN CNAME rtra-vlan1.meeting.ietf.org.
     404}}}
     405   * If the node does ''not'' have a {{{dns_cname}}} key, an error is raised.
     406
     407==== dns/templates/in-addr.arpa.ncg ====
     408
     409The {{{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:
     410
     411{{{
     412  2.1.129.130.in-addr.arpa. IN PTR rtra-vlan1.meeting.ietf.org.
     413}}}
     414
     415==== dns/templates/ip6.arpa.ncg ====
     416
     417The {{{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:
     418
     419{{{
     420  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.
     421}}}
     422
     423== rancid/ directory ==
     424
     425The {{{rancid/}}} directory contains templates for generating RANCID configuration files.
     426
     427=== rancid/templates/router.db.ncg ===
     428
     429The {{{rancid/templates/router.db.ncg}}} file is the template for generating RANCID {{{router.db}}} files.