More Automation in NCM: Usage of Variables and Custom Properties in Command Scripts and Config Change Templates

The purpose of this blog is to provide basic explanation of how variables and custom properties can be used in NCM scripts. Both of them enable network administrator to

replace hardcoded statements by node-dependent values
execute actions on many devices automatically, which means reducing the amount of tasks that must be performed manually

Examples of activities you may want to automate are

Using scripts
- Downloading configuration files
- Uploading configuration files
- Uploading IOS images
- Updating login banners
- Updating access control lists (ACLs)
Using config change templates

- Changing VLAN membership by device port
- Configuring device interfaces based on description
- Enabling IPSLA for VOIP implementations
- Managing NetFlow collection at the source devices

Custom properties enable you to attach additional information to your nodes to help you with e.g.

Organization – physical location of the device, its purpose / category, distinguishing between testing devices and those in production etc.
Bulk updates – create a custom property like ${NewIP}, populate with values and perform bulk update for all devices with one script.
Customer support (e.g. for MSPs) – support contact information per device, SLA type, contract number, etc.
Many other tasks where node-dependent information plays an important role.

Custom Properties Management

Custom properties must be first created using Custom Property Editor on your Orion server (Start -> All Programs -> SolarWinds Orion -> Grouping and Access Control -> Custom Property Editor).

You can either add some of the predefined properties, or build a property from scratch.

Then you need to populate the newly created properties with values.You can do it manually

or import the values from a file.

For more information, please watch http://www.solarwinds.com/resources/videos/video-tutorial-managing-custom-properties-in-orion-npm.html.

Command Scripts

With the appropriate use of variables, a single script can be executed on several different devices, without concern for syntax differences. Scripts are delivered one line at a time to the target devices.

Variables and Custom Properties within Scripts

Variables and custom properties always begin with a dollar sign and a curly brace (${) and end with a curly brace (}).

Example: The following script contains commands with variables to remove the public read-only community string.

${EnterConfigMode}                         enter configuration mode – device-dependent
no snmp-server community public RO         remove the community string – common for many devices
${ExitConfigMode}                          exit configuration mode
${SaveConfig}                              write configuration to memory
${Reboot}                                  reboot the device

The script is parsed in a different way for e.g. Cisco IOS devices and e.g. a Dell PowerConnect switch. Device-dependent variables like the above ${EnterConfigMode}, ${ExitConfigMode}, etc. are defined in device command templates (located in <Orion directory>\NCM\Device Types).

Custom properties, previously created and populated in the Custom Property Editor, can be referenced in the same way – for example ${City}, ${Department}, etc.

More details, together with the list of predefined variables that can be used in command scripts, can be found in Orion Network Configuration Manager Administrator Guide.

Config Change Templates

Config Change Templates are even more powerful than the scripts alone; they have the power of a programming language that enables you to create very sophisticated config change routines.

Most fundamentally, the framework for creating config change templates depends on the SolarWinds Information Service (SWIS), an API installed with NCM that interacts with inventory data in the NCM database. Any device that has not been inventoried in NCM cannot be targeted with a config change template. Each object in a device inventory is a SWIS entity that can be referenced in specific ways within scripts.

Variables within Templates

Variables in config change templates always begin with an at sign, e.g. @TargetPorts. Variables that you can use are given by the input parameters that you specified for your template. Example:

script ConfigureVLANmembershipCiscoIOS (
NCM.Nodes @ContextNode,
NCM.Interfaces[] @TargetPorts,
NCM.VLANs[] @VlansToRemove,
NCM.VLANs[] @VlanToAssign
)

In our example, the variables that you can use in the body of the template are @ContextNode, @TargetPorts, @VlansToRemove, and @VlanToAssign.

Note: Each template must have at least one parameter – the node. Other parameters are optional and depend on what you want to achieve with the template.

As the declaration suggests, variables @TargetPorts, @VlansToRemove, and @VlanToAssign are arrays; you can iterate through them:

foreach (@portItem in @TargetPorts)
{
CLI
{
…

Please note that @portItem is declared implicitly, i.e. when used for the first time.

Custom Properties within Templates

Custom properties are tied with nodes, and therefore can be referenced via the node parameter:

script BaseChangeTemplate (NCM.Nodes @ContextNode)
{
CLI
{
show @ContextNode.MyCustomProperty
}
}

Assuming we have created and filled in the AssetTag custom property for our devices, we can make use of e.g. it in the following way to change access lists:

script ChangeAccessList (NCM.Nodes @ContextNode)
{
string @myip = '10.10.'
@myip = @myip + @ContextNode.AssetTag         here we make the asset tag part of the IP address
@myip = @myip + '.32'                         finish building IP
CLI                                           commands within a CLI block are sent to the device
{
    configure terminal
    no access-list 112
    access-list 112 remark This is a test
    access-list 112 permit tcp @myip 0.0.0.31 host 123.234.123.234 eq 445       include the IP with asset tag info in the access list
}
}

For exhaustive information on config change templates, please see Orion Network Configuration Manager Administrator Guide.

Find more posts tagged with

custom_properties

scripting

Network Configuration Manager (NCM)

config_change_template

Comments

cvachovecj

An excellent illustration and practicle example can be found in by ">Goliath.

Thanks!

bene

Thank you for this article. It has been helpful as I delved into the world of config change templates. I did, however, run into what I consider to be a fairly annoying gotcha yesterday while working on a template. It appears that custom properties are all converted to nvarchar (i.e. text) when they are copied from the NPM database to the NCM database. In my example I was trying to do a mathmatical operation against a custom propertly that had been defined in NPM as INT(3). Sadly, because my custom property had been converted to nvarchar in the NCM database I received an error stating that you couldn't do match on a string. It seems odd to me that you get to very clearly define what type of data is going into a custom property but then that metadata gets whacked when it is copied to the NCM database. I'm hoping, somewhere down the road, that SolarWinds will either keep the data types as the info is copied from NPM to NCM or just let me access the NPM data directly.

cvachovecj

There are Config Change Templates shipped out of the box with NCM and we try to add a few more in every release. The other ones can be downloaded from thwack form another computer with Internet access and copied to the NCM server manually.

noobes

Hi maybe you can help me with this? Would appreciate it if you could have a look. Firstly let me say that I have the custom property fields of (a) Device_Location and (b) new_description populated, however every time I run the script instead of the contents of the new_description custom property being added to the description of the interface I am instead getting the literal value

"@node.new_description" so it reads... Description: @node.new_description?

Why can't my script find the custom property I am pointing it at?

Where can I find the API of whatever language is being used here, what language is it? I see some stuff similar to java and other languages such as if statements and for each loops. Where can I find an official resource to learn how to use these scripts to my advantage? Is this a proprietary language of Solarwinds?

script Change interface description ( NCM.Nodes @ContextNode )

{

foreach ( @node in @ContextNode )

{

if ( @node.DeviceLocation == 'tester' ) // If this field is populated perform CLI on Node

{

CLI

{

configure terminal

interface fastethernet 0/1

description @node.new_description

exit

write mem

}

When this wouldn't work I changed tack and declared a variable called @mydesc outside the method body and initialised its value as the custom property: new_description

after declaring string outside method......

script Change interface description ( NCM.Nodes @ContextNode )

{

string @mydesc = @ContextNode.new_description

CLI

{

configure terminal

interface fastethernet 0/1

description @mydesc

exit

write mem

}

Any help greatly appreciated

Jiri Cvachovec

Trabix

In section "Custom Properties within Templates" you mention:

Custom properties are tied with nodes, and therefore can be referenced via the node parameter.

I see that this works. But there are also Custom Properties which are tied with interfaces. Will this not work?

When I try to change an interface's Custom Property, I get the following:

Error:Variable @itf.Account could not be matched. Possible causes of this are:

1) It has not been declared.

2) You are referencing an entity property which does not exist.

3) You are missing a closing bracket in a prior native block.

script Configure_Interface (

NCM.Nodes @ContextNode,

NCM.Interfaces[] @PhysicalInterfaces,

string @Account

)

{

foreach (@itf in @PhysicalInterfaces)

{

CLI

{

show @itf.Account

}

noobes

Thanks for this I'll give it a go

cyates

Did you ever figure this out. I am trying to use interface custom properties as well

jemertz

My team is just getting started with Config Compliance and Remediation, and these templates look like a huge boon for that effort. Thank you so much! I've found the templates that were included by default, but there don't seem to be any for Cisco Nexus gear. Are these forthcoming, or is there someplace that I can find them? Or is the only option to create them myself?

sixmill

I'm very curious as to whether you found the correct format of calling these interface custom properties. Did it start working after another inventory job run?

tomg2

What functions and transformations are available or planned for variables? I would like to automate configuration that is a template but is custom to each individual node. Say I have three interfaces:

Node A:

gi0/0.1 10.1.1.0/24

gi0/0.2 10.1.2.0/24

gi0/0/3 10.1.3.0/24

Node B;

gi0/0.1 10.2.1.0/24

gi0/0.2 10.2.2.0/24

gi0/0.3 10.2.3.0/24

I would like to use these information to generate for example corresponding EIGRP network statements:

for Node A:

router eigrp 1

network 10.1.1.0 0.0.0.255

network 10.1.2.0 0.0.0.255

network 10.1.3.0 0.0.0.255

etc.

It seems that the only way to do this is to compute the network statements externally, store them temporarily as custom properties and execute the script off the custom properties.

Or maybe generate the entire configuration and store it in one custom property (with \n at the end of each line) and have a script that just executes this custom property.

Am I on the wrong track? What is the best way to accomplish this type of task? Thanks for any help.

andrew.t.144

In NCM, is it possible to use output from an ssh cli command to determine script behaviour?

For example, can I use the output of 'show version' to drive an 'if condition' within the same script? Or perhaps write to a node custom attribute?

I have 3000 devices that require an amendment to the snmp access list before I can even poll them to see what they are (I can only access them via ssh for the mooment). Some of the devices are nexus, which do not allow legacy access-list commands and assume extended ip access-lists (Don't accept the 'extended' command).

I suppose I could just add both config scenario's to the script, one of which will fail, but I was hoping to be a bit more scientific.

Any thoughts?

bps

I have the same question... have you got a answer here?

I need:

dir flash: | include @IOS-New ! if IOS exists one Flash do not update

exit

else

copy tftp://--server--/@IOS-New flash:@IOS-New

exit

!! then check if IOS is on the Flash

dir flash: | include @IOS-New

has anyone something like that?

jemertz

"I suppose I could just add both config scenario's to the script, one of which will fail, but I was hoping to be a bit more scientific."
I have done exactly what you suggested here, and it has worked fine. Include 2 (or 3 or 4) options, expecting all but one to fail depending on the device type.

For your situation, you can use the Device Templates. I believe you would create a new variable for what you want to do on each template, enter the lines in that variable, and when you run the script, you call the variable to run the appropriate lines for the device type. This normally works when the OID is different, such as Nexus vs Catalyst. You'd need SNMP to autodetect that, though you can manually assign the device template to use, and since you can only SSH right now, you would have to do that.

However, there are a lot of scenarios where conditionals would be incredibly helpful. One example I have is automatically generating new RSA keys of the largest size supported by the system. Some devices max out at 2048 and others at 4096. With a ? at the CLI, you can find out the range it accepts. Without that, you'd be wasting a few minutes per device generating a 2048 bit key, and then overwriting it with a 4096 bit key if the latter command is accepted.

bps

my Script looks somehow like that, the problem is, that I can not validate the "NCM.FlashFileName @FlashFiles".

The information is/sould be in the inventory of NCM (SolarWinds Information Service data entities), but how can i access this information in my script?

like -> if the iosfile that I would like to copy on to the flash is allready on the flash, do not start the copy process!

if (@FlashFiles contains @iosfile)

{}

regards Pascal

.CHANGE_TEMPLATE_DESCRIPTION

This is a base change template to act as a starting point for other templates.

.PLATFORM_DESCRIPTION

Replace with details of the device platform for which the template is being created.

.PARAMETER_LABEL @ContextNode

NCM Node

.PARAMETER_DESCRIPTION @ContextNode

The node the template will operate on. All templates require this by default. The target node is selected during the first part of the wizard so it will not be available for selection when defining values of variables.