wktools Version 4 - Advanced Operations with "Configure Devices"   (c) 2003 - 2012 by Mathias Spoerr

Table of Contents

1. Scope

2. Use Cases

3. Separate configuration per device and Configuration HowTo

4. Multihop with a single configuration file

5. Reference

1. Scope

wktools can be used to automate simple and advanced config changes for Cisco devices. The executed commands may be different for each device and/or may be derived from device-specific information, like the running-configuration. Based on real-live examples this document describes the available options.

The commands are saved in files and wktools reads one file per device. The file may be the same for all devices. The examples show the used configuration for different use cases.

2. Use Cases

2.1. Collect information
The easiest and most used option is to collect information from devices and to store this information in files. Whenever a "show" command is sent to the remote device, the return data is saved. Therefore this option may be used to backup configurations.

Simple example for configuration backup:

   show running-config
   exit

It is very important to write out "show" in full. Otherwise the output will NOT be saved.

2.2. Config Templates
wktools provides templates which may be used to collect data for the built-in Parser tools. The template is used instead of the dedicated config file.

Available templates (configurable under ConfigFile Option):

• Inventory: Input for the "Device Information Parser" Tool -> "Inventory Parser"
• Interface: Input for the "Device Information Parser" Tool -> "Interface Parser"
• Mapper: Input for the Mapper Tool

2.3. Reset SNMP Community on all devices
The following config file sets the SNMP community on all devices to a new value:

   conf t
   snmp-server community abcd1234 rw 99
   end
   wr mem
   exit

2.4. Regular Expressions and Conditions
To do changes based on the active device configuration, Regular Expressions may be used. The following examples show three use cases with simple and advanced Regex usage. More information on Regular Expressions is available here.

2.4.1. Simple

   conf t
   int lo 999
   do show ip interface brief
   ip address 10.10.[rgx](?<=FastEthernet1/0            192\.168\.)[0-9]+[/rgx].1 255.255.255.0
   do show run | i hostname
   description *** [rgx](?<=hostname )\b\w*[/rgx] ***
   no shut
   end
   exit

Description:
The IP address on interface Loopback 99 should be set. The third octet should be the same as the third octet of the FastEthernet1/0 IP address. In addition, the hostname should be used as interface description.

Step 1: Read FastEthernet1/0's IP address: "do show ip interface brief"

Step 2: The regex is applied on the show command's return value. Important are the [rgx] und [/rgx] tags for regex definition. The regex is searching for "FastEthernet1/0 192.168." and returns all subsequent numbers until the first non-number is reached.
The regex is executed immediately.

Step 3: The same approach is used to configure the interface description: The regex after the show command is used to get the hostname.

2.4.2. Changing the TACACS Server IP address, but the shared secret should stay the same and may be different between the devices.
A new TACACS server is installed in this use case. All data is migrated from the old server, but the IP address has changed. The Tacacs shared secret is different for some device groups and therefore it must be re-used when changing the TACACS server IP address on the network devices.

The example shows the usage of Regular Expressions in conjunction with Conditions (!IFRETURN, !ELSERETURN, !EXIT). In addition the regex result is stored for later usage.

   sh run | i tacacs-server host 10.1.1.1
   !IFRETURN (?<=10.1.1.1 key )[0-9]*.[a-zA-Z0-9]+
   #[rgx](?<=10.1.1.1 key )[0-9]*.[a-zA-Z0-9]+[/rgx]
   !ELSERETURN
   !EXIT
   conf t
   aaa accounting commands 1 default start-stop group tacacs+
   aaa accounting commands 0 default start-stop group tacacs+
   tacacs-server host 10.1.1.2 key [rgxMem]0[/rgxMem]
   no tacacs-server host 10.1.1.1
   exit
   wr mem
   exit

Description:

Step 1: Read the current TACACS shared secret

Step 2: By using !IFRETURN in conjunction with regex, the return value is checked whether or not a TACACS configuration is available. [rgx] and [/rgx] tags are not needed in this case, because the remaining string after !IFRETURN is interpreted as Regular expression.

Step 3: If !IFRETURN returns "true", the next line in the configuration is used - In the example the regex result is saved. This is done always when using the [rgx] and [/rgx] tags. The result is stored at position "0" in the regex memory when the tags are used the first time. Position "1" is used the second time...

Step 4: The line after !ELSERETURN is used in case !IFRETURN returns "false". !EXIT would delete the remaining commands and close the connection by sending "exit".

Step 5: If a TACACS configuration was found, the remaining commands are now executed. [rgxMem]0[/rgxMem] recalls the regex result stored at position "0" in the regex memory (Step 3).

Important Notes:

• There is no limitiation for the number of !IFRETURN/!ELSERETURN sequences.
• !IFRETURN may be used without !ELSERETURN.
• The supported sequence of !IFRETURN, !ELSERETURN is always as follows.

     Command
     !IFRETURN regex
     Command for !IFRETURN is TRUE (only 1 command is supported)
     !ELSERETURN
     Command for !IFRETURN is FALSE (only 1 command is supported)
     Remaining configuration
  

2.4.3. Insert a new Firewall ACE right before an existing ACE, which may have different ACE line numbers
This example is similar to the previous one. The goal is to look up the line number for a given ACE and insert a new ACE right before the existing one.

   conf t
   sh access-list acl-name | i udp object-group Clients object-group Server-1 object-group UDP-Ports
   !IFRETURN line \d\d
   access-list acl-name [rgx]line \d\d[/rgx] extended permit tcp object-group Clients object-group Server-1 object-group TCP-Ports
   !ELSERETURN 
   !ERROR ACE not found!
   no access-list acl-name extended permit udp object-group Clients object-group Server-1 object-group UDP-Ports
   access-list acl-name [rgxMem]0[/rgxMem] extended permit udp object-group Clients object-group Server-1 object-group UDP-Ports
   end
   wr mem
   exit

Description:

Step 1: Look up the needed ACE line number

Step 2: Check with !IFRETURN whether the return value is ok.

Step 3: If ok, configure the new ACE. Otherwise show an error message ("ACE not found!") and close the connection (!ERROR).

Step 4: Delete the original ACE and re-insert it at the previously saved position ([rgxMem]0[/rgxMem]).

2.4.4. Reconfigure all VLAN 60 switchports with VLAN 61 (Version 4.6.9.0 needed)
This example shows how to set a new VLAN 61 for all ports with the current VLAN 60. The Regex matches all ports named Nnx/y/z, where Nn is the port name and x/y/z is the port number.

	conf t
	do show int statu | i ( 60 )
	!RGXBLOCK ^[a-zA-Z]+[0-9]+\/[0-9]+\/[0-9]+
	int [regex]
	switchport access vlan 61
	description New VLAN
	exit
	!RGXBLOCK
	end
	wr mem
	exit

Description:

Step 1: Look up all ports set with VLAN 60 (do show int statu | i ( 60 ))

Step 2: Apply Regex to the return value: ^[a-zA-Z]+[0-9]+\/[0-9]+\/[0-9]+
The Regex matches all switchport names.

Step 3: Duplicate the commands between both !RGXBLOCK statements for each Regex match.

Step 4: Apply the configuration.

All steps are done during run-time

2.5. Separate configuration per device
Sometimes it is needed to use different configuration files for the devices. Examples: snmp-location, hostname or IP address configurations. A detailed Walk-through of the needed steps is available in section 3 of this document.

2.6. Multihop
Very often the network devices are only accessible via a network management device. In this case it is needed to connect to this device as a first step, keep the connection and do the configuration of the network devices from there.

It is possible to have many devices between the wktools client and the network devices to configure. With MultiHop wktools never closes any connection by it's own. Therefore the user ALWAYS needs to take care of closing the connections by sending "exit" when the configuration is done. The configuration file for the Connection Hosts should never contain "exit" to keep the connection open until the last device was configured.

A detailled example is available in section 4 of this document.

3. Separate configuration per device and Configuration HowTo

The goal is to generate the needed configuration files and send them to the devices. In this example the snmp-community is configured.

3.1. Generate the needed configurations with wktools ConfigMaker
To generate the needed configuration files wktools ConfigMaker may be used. The first step is the definition of a configuration template:

3.1.1. Template Definition

  conf t
  snmp-server location InventarNr: $inr;
  end
  wr
  exit

"$inr;" will be replaced by the associated value. Everything else is static in this example. Save this template as "conf.txt".

3.1.2. Data File
The data file contains the variables and associated values. The following file is used in this example:

   $ip;$inr
   10.10.255.208;123456781
   10.10.255.209;123456782
   10.10.255.210;123456783
   10.10.255.211;123456784
   10.10.255.212;123456785
   10.10.255.213;123456786
   10.10.255.216;123456787
   10.10.255.217;123456788
   10.10.255.227;123456789
   10.10.255.228;123456790
   10.10.255.233;123456791

The first line contains the variable names and the subsequent lines are for the values. The data file is saved as "data.csv".

3.1.3. ConfigMaker configuration

Needed Steps:

• 1: Data File: Select the previously defined "data.csv" file.
• 2: Config File: Select the previously defined "conf.txt" file.
• 3: Output Directory: Specify the directory where the result is stored.
• 4: Filename Variable: The value from this variable is used as filename for the generated config files.
• 5: Additional Separator: Specify the separator used in the data file. In this example it's ";"
• 6: Use Separator as Placeholder End: Whenever there is no space between variables and static text, the separator shall be used to separate between the variable and the text.
• 7: Modus: One file needs to be generated for each line.
• 8: Press the Start button and the config files will be generated.

Result:

3.2. Setup Configure Devices

3.2.1. Hostfile

The hostfile contains all IP addresses/DNS names of the devices to configure.

3.2.2. Config File options

The config File Option "Dynamic" is used. This means that wktools looks up the needed configuration files in the specified folder. There is one file per host needed, except the "Dynamic+Default" option is used. The filenames must match the entries in the Hostfile. The File Extension must be used when the filenames consist of more than the hostname/IP address.

Use the "Static File" option when the same configuration is used for all devices.

The output directory, where the result for 3.1 was stored, is used as "Dyn Config Folder".

3.2.3. Username/Password settings
Define the needed credentials to access the devices.

3.2.4. Connection and Output settings
SSH SingleHop is used in this example. This means that a direct connection is established for all devices. For Multihop see section 4.

The output settings are mandatory, although they are not needed in this case.

3.2.5. Generate DeviceGroup File =>
After pressing the "DeviceGroup Window Refresh" button, the settings are checked and the device-specific settings are summarized in the DeviceGroup window.

The config files are now correlated with the devices.

3.2.6. Verify the DeviceGroup table and select devices to be configured.
Verify if all settings are correct. Each cell is editable and more lines may be added (right-click on any line). Then select all devices which you want to configure.

The config file setting was filled in with the filenames found in the "Dyn Config Folder".

3.2.7. Start =>
With pressing the Start button, the config is pushed to the selected devices.

4. Multihop with a single configuration file

This example shows how to collect running configurations with the usage of Configure Devices - MultiHop.

4.1. Define the Hostfile

The hostfile contains all IP addresses/DNS names of the devices to configure. The first IP address is the Network Management Server IP from where all network devices are accessible.

4.2. Set Config File options
The configuration file is static in this scenario and it only contains two commands: "show run" to collect the configuration and "exit", which is very important in this case, because otherwise wktools will not step back to the Network Management server.

"cfg.txt" is the configuration file used for the network devices. The configuration file for the Network Management Server will be set later.

4.3. Username/Password settings
Define the needed credentials to access the devices.

4.4. Connection Settings
SSH MultiHop is used in this example. This tells wktools to only establish one SSH connection and to keep it open. The protocol must not be changed for any device - in other words, it must be the same for all devices. The protocol for the remainig devices is set with the "MultiHop command" option.

The "MultiHop command" option sets the command executed on the Network management server. The "$ip" variable is used as placeholder for the IP address which is then replaced on demand by the device IP.

4.5. Output Settings
Specify the filename option and directory to save the result.

With the "Show Output=Hostname" option the filenames will be derived from the device hostname. The "Output Directory" defines the folder where all show output files are saved.

4.6. Generate DeviceGroup File =>
After pressing the "DeviceGroup Window Refresh" button, the settings are checked and the device-specific settings are summarized in the DeviceGroup window.

4.7. Modify the DeviceGroup view and set the correct config file for the Network Management server.
Verify if all settings are correct. Each cell is editable and more lines may be added (right-click on any line). Then select all devices which you want to configure.

The first modification is the Config File for the first host (Network Management Server). This file may be empty and must not contain any command which would close the connection.
Number 2 is the used password for the device, and number 3 represents the command to connect to this device. In the example it contains the command and username.

4.8. Start =>
With pressing the Start button, the config is pushed to the selected devices.

5. Reference

This section has some more background information on Configure Devices.

5.1. Important notes

• "show" must be written out in full ALWAYS to save the return value to a file.
• Disable the "Show 2301" Advanced Option when you don't want to get error messages for unknown commands.
• Use the "Append" Output Option for appending new data to already existing files. When this option is unchecked, the file will always be overwritten.
• Use the "Hide Debug Output" button to only display the error messages and hide everything else in the output window.

5.2. Wait for "#" before executing the next command
This is the recommended option and means that a command is only sent after the prompt is received from the remote device. Under rare conditions it is needed to disable this setting, i.e. when configuring a banner. There are three ways to disable this setting:

#1: "Wait for Reply" under "Advanced Settings":

#2: !BEGINBLOCK and !ENDBLOCK config tags: When used in the configuration file, the "Wait for prompt" is only disabled for the commands in between the tags.

#3: !PARAGRAPH config tag: This is the best option, because all commands between two !PARAGRAPH tags are sent at once.

Be careful with disabling this setting! The whole wktools Send/Receive process relies very much on it.

5.3. Regular Expression Reference

The Perl Regex Syntax is used in wktools.

Use the Online Regular Expression Test Tool to test your Regular Expressions before using them.

5.4. Available Config Tags

	conf t
	do show int statu | i ( 60 )
	!RGXBLOCK ^[a-zA-Z]+[0-9]+\/[0-9]+\/[0-9]+
	int [rgx]
	switchport access vlan 61
	exit
	!RGXBLOCK
	end
	wr mem
	exit
		

!cmd-prefix CMD: 
show running-config

5.5. DeviceGroup File
Normally the DeviceGroup file is generated by wktools. Optionally it may be created by the user. This is very helpful when many fields are different between hosts.

Sample File:

wktoolsDgVer=3;
x;netmgmt.test.com;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.208;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.209;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.210;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.211;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.212;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.213;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.216;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.217;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.227;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.228;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;
x;10.10.255.233;testuser;testpassword;testpassword;D:\temp\wktools test\wkn\cfg.txt;SSH;;None;ssh -l netmgr $ip;;;

The first line always needs to be set to "wktoolsDgVer=3;".

Columns:

• 1: Represents the Checkbox: "x" means checked, keep it empty for unchecked
• 2: IP Address or Hostname
• 3: Username
• 4: Login Password
• 5: Enable Password
• 6: Config File; The following reserved names may be used to reference to a pre-defined Template:
  • Mapper: Mapper Template
  • Inventory: Inventory Template
  • Interface: Interface Template
  • ERROR!: Config file not found
• 7: Protocol (case sensitive):
  • COM1: Com Port #1
  • COMx: Com Port; The Port itself is set with the "Port" option.
  • Telnet (TCP 23)
  • SSH (TCP 22)
  • HTTP (TCP 80)
  • HTTPS (TCP 443)
• 8: Port: The Standard Port is used when empty; Used for all Protocols, except for COM1
• 9: Terminalserver Connection: Only used when the Connection Host is a Terminal Server and the device is connected via Serial Console
• 10: Multihop Command: This command is used to connect to the remote devices from the Network Management Server (only relevant with MultiHop)
• 11: Remark: User definable Remark; Not used by wktools
• 12: Remark2: User definable Remark; Not used by wktools

wktools Version 4 - Advanced Operations with "Configure Devices"   (c) 2003 - 2012 by Mathias Spoerr