wiki:NCGHowTo

Introduction

This page provides a series of step-by-step instructions for using the NCG tool to make certain commonplace changes on the IETF network.

The overall usage of NCG for IETF is described on the NCG wiki page.

The input and output files for NCG for IETF are described in detail on the NCGFiles wiki page.

The NCG tool itself is described on the Netomata web site, and is documented in detail on the Netomata documentation pages.

Dealing with NCG

Access NCG

NCG is installed on host netomata.meeting.ietf.org, in directory ~ncg/ietf75/

  ssh login@netomata.meeting.ietf.org
  cd ~ncg/ietf75/

To obtain an account on the the netomata.meeting.ietf.org host, contact Brent Chapman <brent @ netomata.com> (mobile +1 650 279 1897).

Generate Configs

To generate configs, simply access the netomata.ietf.meeting.org host as described above, and do

  rake configs

Depending on the speed and load of the host, this can take 30 to 60 seconds, so please be patient.

Examine Generated Configs

The generated configs for all devices and services will be in the ~ncg/ietf75/configs directory.

  cd ~ncg/ietf75/configs

Compare Generated Configs to Baseline

A 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

  cd ~ncg/ietf75
  rake baseline_cmp

Update Baseline Configs

To update the set of "baseline" configs to match the most-recently-generated configs, do the following:

  cd ~ncg/ietf75
  rake baseline_accept

Basic Workflow for Making Changes

After making any changes, you need to

  1. Regenerate the config files.
  2. Compare your newly-generated files to the baseline configs to verify that you've got the changes you want.
  3. When you're happy with your changes, update the baseline files.
  cd ~ncg/ietf75
  rake configs
  rake baseline_cmp
  rake baseline_accept

Install NCG-Generated Configs on Devices

FIXME: describe how to use RANCID to install the generated configs

Examine NCG's Network Model

NCG operates in two phases:

  • First, it builds up an in-memory tree-structured model of the network, based on info provided through the various input files.
  • Second, it uses the information in that network model to generate configs for the various devices and services defined in the model.

When 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:

  • The list of keys in the model
  • The full contents (keys and data) of the model

Dump a List of Keys in NCG's Network Model

To dump a list of keys, do the following

  cd ~ncg/ietf75
  rake keys
  more ietf.keys

The resulting list of keys will be in file ietf.keys.

This 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.

Note 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.

Dump the Entire Contents of NCG's Network Model

To dump the entire contents (including values) of the NCG network model, do the following

  cd ~ncg/ietf75
  rake dump
  more ietf.dump

The resulting list of keys will be in file ietf.dump.

Note 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.

Make Changes Affecting the Entire Network

Prepare for a New Meeting

To prepare to generate config files for a new meeting, there are some steps you'll probably want to take:

  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.
  2. Update the snmp.communities file, which often has meeting-specific community strings defined in it.
  3. Update the users file, to list the users who should get access to all the devices.
  4. 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.

Add/Drop/Change? WiFi SSIDs

To 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.

Tip: If you're adding a new SSID, you probably also need to add a new VLAN for that SSID to use.

Add/Drop/Change? VLANs

To 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.

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.

Add/Drop/Change? a User

To 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).

Change the Enable/Root? Password

To 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.

Tip: To generate an MD5 hash for a particular password, use the openssl passwd -1 password command.

Change SNMP Settings

To change the network-wide SNMP settings, edit the snmp.* files.

Add/Drop/Change? SNMP Communities

To change the list of SNMP communites which are configured on all devices in the network, edit the snmp.communities file.

Add/Drop/Change? SNMP v3 Groups

To change the list of SNMP v3 groups which are configured on all devices in the network, edit the snmp.v3_groups file.

Add/Drop/Change? SNMP v3 Users

To change the list of SNMP v3 users which are configured on all devices in the network, edit the snmp.v3_users file.

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.

Add/Drop/Change? Devices

Add/Drop/Change? APs

To add an AP, or change or delete an existing one, edit the ap/devices file. The contents of the file are documented on the NCG wiki page (FIXME: replace with anchored link).

To 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.

To 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).

Add/Drop/Change? Switches

To 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 NCG wiki page (FIXME: replace with anchored link).

Then, 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.

To 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).

Add/Drop/Change? Switch Interface Types

To add, drop, or change the interface template for a particular type of interface, edit the switch/templates/interfaces/type.ncg file.

Add/Drop/Change? Switch Models

To 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).

Add/Drop/Change? a Router

To 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 NCG wiki page (FIXME: replace with anchored link).

Then, create (or change or delete, as appropriate) the following files:

  • rtr/name.interfaces -- lists the names, types, and other parameters for all of the interfaces on the router.
  • rtr/name.ethernet_interfaces -- lists the names, types, and other parameters (including particularly IP addresses) for all of the Ethernet interfaces on the router.
  • rtr/name.ethernet_interfaces -- lists the names, types, and other parameters (including particularly IP addresses) for all of the Ethernet interfaces on the router.
  • rtr/name.ipv6_tunnels -- lists the names, source and destination addresses, and other parameters for all of the IPv6 tunnel interfaces on the router.
  • rtr/name.static_routes -- lists the static routes to be established on the router.
  • rtr/name.bgp -- lists the BGP configuration section of the config for a Juniper router (to be included in the generated config verbatim).
  • rtr/name.policy_options -- lists the "policy-options" section of the config for a Juniper router (to be included in the generated config verbatim).

To 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).

Add/Drop/Change? Router Interface Types

To add, drop, or change the interface template for a particular type of interface, edit the rtr/templates/interfaces/type.ncg file.

Add/Drop/Change? Router Models

To 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).

Common Actions on Devices in General

Append to a Device Config

To 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).

Common Actions on APs

Disable an Interface or SSID on a Particular AP

To deactivate a particular interface on a particular device, edit the ap/override.active file.

Override Default Power Settings on a Particular AP/Interface

To change the power settings from the network-wide defaults for a particular interface on a particular device, edit the ap/override.power file.

Override Default Speed Settings on a Particular AP/Interface

To change the speed settings from the network-wide defaults for a particular interface on a particular device, edit the ap/override.speed file.

Change Settings on All APs

To 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).

Update PKI Parameters for a Particular Device

Cisco 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.

To 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).

Switches

Change Settings on All Switches

To 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).

To 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).

Update PKI Parameters for a Particular Switch

Cisco 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.

To 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).

Routers

Change Settings on All Routers

To 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).

To 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).

Drop/Add/Change? Interfaces on a Particular Router

To 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.

Drop/Add/Change? IPv6 Tunnels on a Particular Router

To 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.

Drop/Add/Change? Static Routes on a Particular Router

To 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.

Change BGP Configuration on a Particular Router

To 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).

Change Routing Policy Options on a Particular Router

To 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).

Last modified 8 years ago Last modified on 24 Jul 2009, 13:40:41