Changes between Initial Version and Version 1 of NCGHowTo


Ignore:
Timestamp:
24 Jul 2009, 13:40:41 (9 years ago)
Author:
brent@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • NCGHowTo

    v1 v1  
     1= Introduction =
     2
     3This page provides a series of step-by-step instructions for using the NCG tool to make certain commonplace changes on the IETF network.
     4
     5The overall usage of NCG for IETF is described on the [wiki:NCG] wiki page.
     6
     7The input and output files for NCG for IETF are described in detail on the [wiki:NCGFiles] wiki page.
     8
     9The NCG tool itself is described on the [http://www.netomata.com/products/ncg Netomata web site], and is documented in detail on the [http://www.netomata.com/docs Netomata documentation pages].
     10
     11= Dealing with NCG =
     12
     13== Access NCG ==
     14
     15NCG is installed on host netomata.meeting.ietf.org, in directory ~ncg/ietf75/
     16
     17{{{
     18  ssh login@netomata.meeting.ietf.org
     19  cd ~ncg/ietf75/
     20}}}
     21
     22To obtain an account on the the netomata.meeting.ietf.org host, contact Brent Chapman <brent @ netomata.com> (mobile +1 650 279 1897).
     23
     24== Generate Configs ==
     25
     26To generate configs, simply access the netomata.ietf.meeting.org host as described above, and do
     27
     28{{{
     29  rake configs
     30}}}
     31
     32Depending on the speed and load of the host, this can take 30 to 60 seconds, so please be patient.
     33
     34== Examine Generated Configs ==
     35
     36The generated configs for all devices and services will be in the {{{~ncg/ietf75/configs}}} directory.
     37
     38{{{
     39  cd ~ncg/ietf75/configs
     40}}}
     41
     42== Compare Generated Configs to Baseline ==
     43
     44A set of "baseline" configs (copies of last-known-good configs) is kept in the {{{~ncg/ietf75/baseline}}} directory, which has the same structure as the {{{~ncg/ietf75/configs}}} directory.  You can compare the most-recently-generated configs against the baseline configs by doing
     45
     46{{{
     47  cd ~ncg/ietf75
     48  rake baseline_cmp
     49}}}
     50
     51== Update Baseline Configs ==
     52
     53To update the set of "baseline" configs to match the most-recently-generated configs, do the following:
     54
     55{{{
     56  cd ~ncg/ietf75
     57  rake baseline_accept
     58}}}
     59
     60== Basic Workflow for Making Changes ==
     61
     62After making any changes, you need to
     63 1. Regenerate the config files.
     64 1. Compare your newly-generated files to the baseline configs to verify that you've got the changes you want. 
     65 1. When you're happy with your changes, update the baseline files.
     66
     67{{{
     68  cd ~ncg/ietf75
     69  rake configs
     70  rake baseline_cmp
     71  rake baseline_accept
     72}}}
     73
     74== Install NCG-Generated Configs on Devices ==
     75
     76FIXME: describe how to use RANCID to install the generated configs
     77
     78== Examine NCG's Network Model ==
     79
     80NCG operates in two phases:
     81
     82 * First, it builds up an in-memory tree-structured model of the network, based on info provided through the various input files.
     83 * Second, it uses the information in that network model to generate configs for the various devices and services defined in the model.
     84
     85When making changes to the configs, or troubleshooting problems, it is often useful to examine the model of the network that NCG has built up and is working from.  There are two things you can examine:
     86
     87 * The list of keys in the model
     88 * The full contents (keys and data) of the model
     89
     90=== Dump a List of Keys in NCG's Network Model ===
     91
     92To dump a list of keys, do the following
     93
     94{{{
     95  cd ~ncg/ietf75
     96  rake keys
     97  more ietf.keys
     98}}}
     99
     100The resulting list of keys will be in file {{{ietf.keys}}}.
     101
     102This is sort of like doing an {{{ls -R /}}} command on a UNIX system; you see the names of all the directories and files, but not the contents of files.
     103
     104Note that NCG does __not__ generate new configs when you dump the keys; the program completes the first phase (building the model of the network), dumps the list of keys, and then exits without attempting to generate new configs.
     105
     106=== Dump the Entire Contents of NCG's Network Model ===
     107
     108To dump the entire contents (including values) of the NCG network model, do the following
     109
     110{{{
     111  cd ~ncg/ietf75
     112  rake dump
     113  more ietf.dump
     114}}}
     115
     116The resulting list of keys will be in file {{{ietf.dump}}}.
     117
     118Note that NCG does __not__ generate new configs when you dump the model; the program completes the first phase (building the model of the network), dumps the model, and then exits without attempting to generate new configs.
     119
     120= Make Changes Affecting the Entire Network =
     121
     122== Prepare for a New Meeting ==
     123
     124To prepare to generate config files for a new meeting, there are some steps you'll probably want to take:
     125
     126 1. Examine the {{{ietf.neto}}} file, and update it as necessary.  In particular, you probably want to change the various MD5 authentication hashes (the strings beginning with {{{$1$}}}, which are used as login and enable passwords for various types of devices, and are generated with the {{{openssl passwd -1}}} ''password'' command) to something you know the cleartext for.
     127 1. Update the {{{snmp.communities}}} file, which often has meeting-specific community strings defined in it.
     128 1. Update the {{{users}}} file, to list the users who should get access to all the devices.
     129 1. Update the files in the {{{ap/}}}, {{{rtr/}}}, and {{{switch/}}} directories, to update the list of devices of each type and the various parameters and overrides for each device.
     130
     131== Add/Drop/Change !WiFi SSIDs ==
     132
     133To add a new !WiFi SSID, or change or drop an existing one, edit the {{{ap/ssids}}} file.  Comments in the file (after the processing directives, and just before the data lines) explain what each column is for. 
     134
     135  '''Tip: ''' If you're adding a new SSID, you probably also need to add a new VLAN for that SSID to use.
     136
     137== Add/Drop/Change VLANs ==
     138
     139To add a new VLAN, or change or drop an existing one, edit the {{{vlans}}} file.  Comments at the top of the file explain the columns in the file. 
     140
     141  '''Note:''' The {{{vlans}}} file does not have any processing directives ('@' lines, for example) at the beginning of it, because it is used in multiple ways, each with a separate header file full of processing directives for the data in the {{{vlans}}} file.  For example, it is used with the {{{vlans.hdr}}} file to populate the {{{!vlans!}}} part of the network model, and with the {{{rtr/_vlan_interfaces.hdr}}} file to define router interfaces for each VLAN.
     142
     143== Add/Drop/Change a User ==
     144
     145To add, drop, or change a user, edit the {{{users}}} file.  These users are given access to all devices, via appropriate statements in the device templates ("{{{username}}} ''name'' {{{privilege 15 secret 5}}} ''md5''" lines in Cisco configs, for example, or appropriate "{{{user}}} ''name'' {{{ { ... } }}}" stanzas in the "{{{login}}}" section of Juniper configs).
     146
     147== Change the Enable/Root Password ==
     148
     149To change the enable password (for Ciscos) or root password (for Junipers), edit the {{{ietf.neto}}} file, and update the {{{cisco!enable_secret}}} or {{{juniper!root_authentication}}} values as appropriate. 
     150
     151  '''Tip:''' To generate an MD5 hash for a particular password, use the {{{openssl passwd -1}}} ''password'' command.
     152
     153== Change SNMP Settings ==
     154
     155To change the network-wide SNMP settings, edit the {{{snmp.*}}} files.
     156
     157=== Add/Drop/Change SNMP Communities ===
     158
     159To change the list of SNMP communites which are configured on all devices in the network, edit the {{{snmp.communities}}} file.
     160
     161=== Add/Drop/Change SNMP v3 Groups ===
     162
     163To change the list of SNMP v3 groups which are configured on all devices in the network, edit the {{{snmp.v3_groups}}} file.
     164
     165=== Add/Drop/Change SNMP v3 Users ===
     166
     167To change the list of SNMP v3 users which are configured on all devices in the network, edit the {{{snmp.v3_users}}} file.
     168
     169  '''Note:''' Entries in the {{{snmp.v3_users}}} file have a "group" column, which should be the name of a group defined in the {{{snmp.v3_groups}}} file.
     170
     171= Add/Drop/Change Devices =
     172
     173== Add/Drop/Change APs ==
     174
     175To add an AP, or change or delete an existing one, edit the {{{ap/devices}}} file.  The contents of the file are documented on the [wiki:NCG] wiki page (FIXME: replace with anchored link).
     176
     177To change the power or speed settings from the network-wide defaults for a particular interface on a particular device, or to deactivate a particular interface on a particular device, edit the {{{ap/override.power}}}, {{{ap/override.speed}}}, or {{{ap/override.active}}} file as appropriate.
     178
     179To append arbitrary configuration commands to the end of a particular devices's config file (in order to make device-specific config changes that aren't provided for in other ways, for example), create a {{{ap/append.d/}}}''name'' file for the device (the filename should exactly match the ''name'' field for the device in the {{{ap/devices}}} file).
     180
     181== Add/Drop/Change Switches ==
     182
     183To add a switch, or change or delete an existing one, first edit the {{{switch/devices}}} file.  The contents of the file are documented on the [wiki:NCG] wiki page (FIXME: replace with anchored link).
     184
     185Then, create (or change or delete, as appropriate) a {{{switch/}}}''name''{{{.interfaces}}} file for the switch, listing the names, types, and other parameters for all of the interfaces on the switch.  To make it easier than starting from scratch, there are sample interface files for various models of switches in the {{{switch/SAMPLE}}} directory, which list the names of the interfaces that are standard on that model of switch.
     186
     187To append arbitrary configuration commands to the end of a particular devices's config file (in order to make device-specific config changes that aren't provided for in other ways, for example), create a {{{switch/append.d/}}}''name'' file for the device (the filename should exactly match the ''name'' field for the device in the {{{switch/devices}}} file).
     188
     189=== Add/Drop/Change Switch Interface Types ===
     190
     191To add, drop, or change the interface template for a particular ''type'' of interface, edit the {{{switch/templates/interfaces/}}}''type''{{{.ncg}}} file.
     192
     193=== Add/Drop/Change Switch Models ===
     194
     195To add, drop, or change the overall template for a particular ''make'' (i.e., "cisco") and ''model'' (i.e., "WS-C3560-8PC-S") of switch, edit the file {{{switch/templates/}}}''make''-''model''{{{.ncg}}}.  These files are often symlinks to a "master" template file for a particular manufacturer (for instance, {{{switch/template/cisco-WS-C3560-8PC-S.ncg}}} is a symlink to {{{switch/template/cisco.ncg}}}, as are the templates for many other Cisco models).
     196
     197== Add/Drop/Change a Router ==
     198
     199To add a router, or change or delete an existing one, first edit the {{{rtr/devices}}} file.  The contents of the file are documented on the [wiki:NCG] wiki page (FIXME: replace with anchored link).
     200
     201Then, create (or change or delete, as appropriate) the following files:
     202
     203 * {{{rtr/}}}''name''{{{.interfaces}}} -- lists the names, types, and other parameters for all of the interfaces on the router.
     204 * {{{rtr/}}}''name''{{{.ethernet_interfaces}}} -- lists the names, types, and other parameters (including particularly IP addresses) for all of the Ethernet interfaces on the router.
     205 * {{{rtr/}}}''name''{{{.ethernet_interfaces}}} -- lists the names, types, and other parameters (including particularly IP addresses) for all of the Ethernet interfaces on the router.
     206 * {{{rtr/}}}''name''{{{.ipv6_tunnels}}} -- lists the names, source and destination addresses, and other parameters for all of the IPv6 tunnel interfaces on the router.
     207 * {{{rtr/}}}''name''{{{.static_routes}}} -- lists the static routes to be established on the router.
     208 * {{{rtr/}}}''name''{{{.bgp}}} -- lists the BGP configuration section of the config for a Juniper router (to be included in the generated config verbatim).
     209 * {{{rtr/}}}''name''{{{.policy_options}}} -- lists the "policy-options" section of the config for a Juniper router (to be included in the generated config verbatim).
     210
     211To append arbitrary configuration commands to the end of a particular devices's config file (in order to make device-specific config changes that aren't provided for in other ways, for example), create a {{{rtr/append.d/}}}''name'' file for the device (the filename should exactly match the ''name'' field for the device in the {{{rtr/devices}}} file).
     212
     213=== Add/Drop/Change Router Interface Types ===
     214
     215To add, drop, or change the interface template for a particular ''type'' of interface, edit the {{{rtr/templates/interfaces/}}}''type''{{{.ncg}}} file.
     216
     217=== Add/Drop/Change Router Models ===
     218
     219To add, drop, or change the overall template for a particular ''make'' (i.e., "juniper") and ''model'' (i.e., "M7100") of router, edit the file {{{rtr/templates/}}}''make''-''model''{{{.ncg}}}.  These files are often symlinks to a "master" template file for a particular manufacturer (for instance, {{{rtr/template/juniper-M7100.ncg}}} is a symlink to {{{rtr/template/juniper.ncg}}}).
     220
     221= Common Actions on Devices in General =
     222
     223== Append to a Device Config ==
     224
     225To append arbitrary configuration commands to the end of a particular devices's config file (in order to make device-specific config changes that aren't provided for in other ways, for example), create a {{{{ap,rtr,switch}/append.d/}}}''name'' file for the device (the filename should exactly match the ''name'' field for the device in the {{{{ap,rtr,switch}/devices}}} file).
     226
     227== Common Actions on APs ==
     228
     229=== Disable an Interface or SSID on a Particular AP ===
     230
     231To deactivate a particular interface on a particular device, edit the {{{ap/override.active}}} file.
     232
     233=== Override Default Power Settings on a Particular AP/Interface ===
     234
     235To change the power settings from the network-wide defaults for a particular interface on a particular device, edit the {{{ap/override.power}}} file.
     236
     237=== Override Default Speed Settings on a Particular AP/Interface ===
     238
     239To change the speed settings from the network-wide defaults for a particular interface on a particular device, edit the {{{ap/override.speed}}} file.
     240
     241=== Change Settings on All APs ===
     242
     243To change settings on all APs, edit either the {{{ap/templates/ap.ncg}}} file (which is the master template for AP config files) or one of the {{{ap/templates/interfaces/*.ncg}}} files (which are the sub-templates for particular types of interfaces on the APs).
     244
     245=== Update PKI Parameters for a Particular Device ===
     246
     247Cisco devices auto-generate PKI (Public Key Infrastructure) parameters if they aren't included in the config file for the device.  Having the device regenerate the parameters every time it reboots, however, is a problem because it causes warnings and errors that the parameters have changed since the last time the device was accessed. 
     248
     249To prevent these warnings and errors, once a given device has auto-generated its PKI parameters, those parameters should be stored so that they can be reused when that device's config file is regenerated.  To do this, examing the running config on the device in question (via a "{{{show run}}}" command, for example), extract the "{{{crypto pki trustpoint TP-self-signed-}}}''number''" and "{{{crypto pki certificate chain TP-self-signed-}}}''number''" stanzas of the running config into a file named {{{ap/pki.d/}}}''name''{{{.pki}}} (where ''name'' is the name of the device exactly as it appears in the {{{ap/devices}}} file).
     250
     251== Switches ==
     252
     253=== Change Settings on All Switches ===
     254
     255To change settings on all switches, edit the overall template for a particular ''make'' (i.e., "cisco") and ''model'' (i.e., "WS-C3560-8PC-S") of switch, which is {{{switch/templates/}}}''make''-''model''{{{.ncg}}}.  These files are often symlinks to a "master" template file for a particular manufacturer (for instance, {{{switch/template/cisco-WS-C3560-8PC-S.ncg}}} is a symlink to {{{switch/template/cisco.ncg}}}).
     256
     257To change settings for a particular type of interface on all switches, edit the appropriate {{{switch/templates/interfaces/*.ncg}}} files (which are the sub-templates for particular types of interfaces on the switches).
     258
     259=== Update PKI Parameters for a Particular Switch ===
     260
     261Cisco devices auto-generate PKI (Public Key Infrastructure) parameters if they aren't included in the config file for the device.  Having the device regenerate the parameters every time it reboots, however, is a problem because it causes warnings and errors that the parameters have changed since the last time the device was accessed. 
     262
     263To prevent these warnings and errors, once a given device has auto-generated its PKI parameters, those parameters should be stored so that they can be reused when that device's config file is regenerated.  To do this, examing the running config on the device in question (via a "{{{show run}}}" command, for example), extract the "{{{crypto pki trustpoint TP-self-signed-}}}''number''" and "{{{crypto pki certificate chain TP-self-signed-}}}''number''" stanzas of the running config into a file named {{{switch/pki.d/}}}''name''{{{.pki}}} (where ''name'' is the name of the device exactly as it appears in the {{{switch/devices}}} file).
     264
     265== Routers ==
     266
     267=== Change Settings on All Routers ===
     268
     269To change settings on all routers, edit the overall template for a particular ''make'' (i.e., "juniper") and ''model'' (i.e., "M7100") of router, which is {{{rtr/templates/}}}''make''-''model''{{{.ncg}}}.  These files are often symlinks to a "master" template file for a particular manufacturer (for instance, {{{rtr/template/juniper-M7100.ncg}}} is a symlink to {{{rtr/template/juniper.ncg}}}).
     270
     271To change settings for a particular type of interface on all routers, edit the appropriate {{{rtr/templates/interfaces/*.ncg}}} files (which are the sub-templates for particular types of interfaces on the routers).
     272
     273=== Drop/Add/Change Interfaces on a Particular Router ===
     274
     275To change the interfaces on a particular router, edit the {{{rtr/}}}''name''{{{.interfaces}}} file, which lists the names, types, and other parameters for all of the interfaces on the router.
     276
     277=== Drop/Add/Change IPv6 Tunnels on a Particular Router ===
     278
     279To change the IPv6 tunnels on a particular router, edit the {{{rtr/}}}''name''{{{.ipv6_tunnels}}} file, which lists the names, source and destination addresses, and other parameters for all of the IPv6 tunnel interfaces on the router.
     280
     281=== Drop/Add/Change Static Routes on a Particular Router ===
     282
     283To change the static routes defined on a particular router, edit the {{{rtr/}}}''name''{{{.static_routes}}} file, which lists the static routes to be established on the router.
     284
     285=== Change BGP Configuration on a Particular Router ===
     286
     287To change the BGP configuration for a particular router, edit the {{{rtr/}}}''name''{{{.bgp}}} file, which lists the BGP configuration section of the config for a Juniper router (to be included in the generated config verbatim).
     288
     289=== Change Routing Policy Options on a Particular Router ===
     290
     291To change the routing policy options on a particular router, edit the {{{rtr/}}}''name''{{{.policy_options}}} file, which lists the "policy-options" section of the config for a Juniper router (to be included in the generated config verbatim).