ns4 - Configuration Management Tool
Posted by Chris Mason on Thursday, April 29, 2010
Overview
ns4 is a configuration management tool that can be used to backup CLI-based devices automatically. It was originally designed for Cisco routers and switches to save the running configuration to a file on a daily basis, but as it adopts a cartridge based design, it allows the user to define new cartridges to backup any device they want! If a device/node has the ability to login through a CLI then ns4 can do anything the user wants as it is not dependent on ns4 supporting a specific device unlike RANCID.
ns4 doesn't just support the automated backup of configurations, the real power is through its ability to run scripts on devices/nodes on an adhoc basis. ns4 uses the power of Perl to allow you to manipulate the outputs of commands using regular expressions within scripts. You could fetch the inventory of your entire network (or limit it to specific devices using tags) to a single file by just issuing a single command through ns4!
Downloads
Tutorial
The following section will give a brief overview of how to use ns4. This section should not be used as an alternative to the User Guide as that contains much more information. I know when I download software, the last thing I want to do is read through a 40 page manual to find out how to use the tool to evaluate it. I am going to skip some of the fundamentals that can be found within the User Guide and concentrate on what is required to get a setup working that will allow you to connect to a Cisco router.
Before we begin there are a couple of prerequisite Perl modules that need to be installed before ns4 will run. These modules can be found at your local CPAN mirror and they are:
Once we have the mandatory Perl modules installed there are two files we need to create before we can start using ns4 - these are '/etc/ns4/cartridges.yaml' and '/etc/ns4/ns4.yaml'. The 'cartridges.yaml' file is where we store our cartridges which explain how to login to a node. The second file is 'ns4.yaml' where we define the nodes we want to connect to with information about the node, like addresses, usernames and passwords. The format of these configuration files is written in a markup language called YAML (YAML Ain't Markup Language).
---
cartridge:
id: 'cisco'
pre: 'terminal length 0'
prompt:
expect:
- {value: '^.*[Node].*>\s*', send: 'enable'}
- {value: 'Password:', send: '[C:Enable]'}
value: '^.*[Node].*#\s'
/etc/ns4/cartridges.yaml
To explain this briefly; the above is a cartridge with an id of 'cisco'. The 'pre' element controls what we send once we have logged in and the command is used to disable the terminal pager. We have to define the prompt that we expect to see to determine we have logged into the node which is defined as '^.*[Node].*#\s*'. The 'expect' element controls what we send if we see different prompts - in the above cartridge it will allow us to enter 'enable' mode if we don't get a prompt with a '#' at the end.
---
container:
node:
- {id: 'PE01', address: '10.254.0.1'}
- {id: 'PE02', address: '10.254.0.2'}
- {id: 'PE03', address: '10.254.0.3'}
- {id: 'PE04', address: '10.254.0.4'}
- {id: 'PE05', address: '10.254.0.5'}
options:
cartridge: 'cisco'
proxy: 'myproxy'
username: 'guest'
password: {encoding: 'base64', value: 'Y2lzY28='}
method: 'telnet [host]'
proxy:
id: 'myproxy'
address: '192.168.0.254'
method: 'ssh -p [port], -l[user], [host]'
username: 'guest'
password: {encoding: 'base64', value: 'Y2lzY28='}
prompt: '\$\s*$'
/etc/ns4/ns4.yaml
I am hoping that most of what is above is pretty self-explanatory, but I will explain a couple of the elements. The 'method' element is used to define what is run on the system to connect to the proxy/node. If 'telnet' or 'ssh' isn't pathed then you can prepend the path to the 'method' element. In the above example we are connecting to a series of nodes through the proxy 'myproxy'. The connection to myproxy will be spawned on the machine that you are running ns4 on, so the 'method' element would point to the 'ssh' binary on the local machine. The password fields support encoding, which is optional but in the example above we have used 'base64'. The 'prompt' element on the proxy refers to the prompt that you expect to see on the proxy to know you have connected successfully - we match a line with a '$' at the end.
Once we have setup those important files we can start using ns4. The ns4 binary within the distribution needs to be copied into your 'bin' directory and you need to ensure it has 'o+rw' permissions at a minimum. If we execute ns4 without any parameters then we will get the usage screen:
ns4 v4.2.3
Configuration Management Tool
by Chris Mason <chris@noodles.org.uk>
Usage: ns4 <criteria> <action> [options]
Criteria:
-a all nodes
or -n 're' node pattern
or -N 'file' node list file
or/and -t 're'@ tag pattern
Actions:
-r ['type'] node summary report
where 'type' is:
'byproxy' group by proxy (default)
'bytag' group by tag
'raw' raw output
'detail' detailed output
or -d default (run commands from config)
or -c 'x[,...],y' command = 'x', output file = 'y'
or -l 'x,y' list file = 'x', output file = 'y'
or -s 'x[,a=x,...]' script file = 'x', variables (a=x, etc)
Options:
-C 'file' alternative configuration file
-R 'file' alternative cartridges file
-f ['file'] create failed node list file
-A enable alerting of failures
-V output version information
-v@ verbosity level
Examples
Now we know how to configure ns4 with a simple configuration we are going to look into a couple of useful commands to demonstrate the true power of ns4. For detailed information on scripts then please see the user guide as this topic is more detailed than this tutorial.
$ns4 -a -r
There are multiple different criteria parameters which can be used to specify what nodes to select, but for simplicity we are going to be using the '-a' criteria parameter which will select all nodes. The '-r' parameter will output a report of all the nodes which match that criteria. If, like we have done, specify the '-a' criteria then you will get a report of all the nodes defined within the configuration file:
ns4 v4.2.3 Configuration Management Tool by Chris Mason <chris@noodles.org.uk> [Proxy: myproxy] (nodes = 5) [Tags: None] - PE01 .. 10.254.0.1 / - PE02 .. 10.254.0.2 / - PE03 .. 10.254.0.3 / - PE04 .. 10.254.0.4 / - PE05 .. 10.254.0.5 / Total Nodes: 5
The above report will take the information from the configuration file and group the nodes into a certain criteria (default is by proxy). You may also use a different report output format by passing a parameter to the '-r' argument.
$ns4 -a -c 'show running-config,[Node].[Date].txt'
This command will allow you to fetch a copy of the running-configuration from every node within the configuration and save the output to dynamically named files based on the node name and the current date.
$ns4 -a -c 'show running-config,config.[Date].txt'
This is a slight variation on the above command, but we have skipped the '[Node]' element from the filename so the filename will equate to the same name for all nodes. In this scenario we append the output from multiple nodes to a single file. The output from each node has a header applied so you can distinguish one node from another within the file.
$ns4 -a -c 'show running-config,show inventory,[Node].[Date].txt'
This is a slight variation on the above command, but this shows how we support multiple commands when using the '-c' parameter. You can put as many commands as you want on the condition that the last element is the filename.
$ns4 -a -l 'commands.txt,[Node].[Date].txt'
The above command will use a file which contains a list of commands to run - one command on each line. All the output from these commands will be outputted to a dynamically name filename based on the node name and date. This syntax is very useful if you are doing an upgrade on a node and you wish to capture the output from a series of commands to a single file to use in comparison before and after the upgrade.