Important

   

Starting from version 8.9.03, BMC Network Automation is renamed to TrueSight Network Automation. This space contains information about TrueSight Network Automation 8.9.03 and the later service packs for 8.9. For earlier releases, see BMC Network Automation 8.9.

About substitution parameters

You can use substitution parameters in configuration templates, rules, and other areas to support reusability.

Substitution parameters syntax

The following table defines the substitution parameters that are available in TrueSight Network Automation:

Component

Substitution parameter description and usage

Device

Substitutes an attribute from the device inventory. The parameter is device inventory field name. For example, ${device.host} substitutes the Host Name/IP Address value assigned in the device inventory. Valid parameter values include:

  • access_port: Explicit TCP port for making connections
  • aux_access_port: Explicit auxiliary TCP port for making connections
  • aux_host: Auxiliary interface Host Name/IP Address
  • aux_nat: Auxiliary interface NAT Address
  • aux_password: Auxiliary interface DSP Login Password
  • aux_priv_password: Auxiliary interface DSP Privileged Password
  • aux_priv_user: Auxiliary interface DSP Privileged User Name
  • aux_user: Auxiliary interface DSP Login User Name
  • context_name: Security context name
  • external_id: External identification to communicate with Atrium Configuration Management Database (CMDB)
  • field_name: Any dynamic field name, for example, Description, Business Services, VRF
  • host: Host Name/IP Address
  • key: Database key of the device
  • name: Name
  • nat: NAT Address
  • password: DSP Login Password
  • priv_password: DSP Privileged Password
  • priv_user: DSP Privileged User Name
  • realm: Realm name
  • user: Device Security Profile (DSP) Login User Name

Usage: ${device.parameter}

Agent

Substitutes an attribute from the device agent. Valid parameter values include:

  • name: Agent name
  • localhostFullName: Resolves to the fully-qualified host name of the primary interface's agent platform, as reported by its underlying OS.
  • localhostAddress: Resolves to the local address of the primary interface's agent platform, as reported by its underlying OS.
  • localhostIpv4Address: Resolves to the address of the IPv4 device-facing NIC (if any) at the primary interface's agent which is used to communicate with the device.
  • localhostIpv4Mask: Resolves to the mask of the IPv4 device-facing NIC (if any) at the primary interface's agent which is used to communicate with the device.
  • localhostIpv6Address: Resolves to the address of the IPv6 device-facing NIC (if any) at the primary interface's agent which is used to communicate with the device.
  • localhostIpv6Mask: Resolves to the mask of the IPv6 device-facing NIC (if any) at the primary interface's agent which is used to communicate with the device.
  • localhostName: Resolves to the host name of the primary interface's agent platform, as reported by its underlying OS.
  • field_name: Any dynamic field name
  • aux_name: Auxiliary interface agent name
  • aux_localhostFullName: Resolves to the fully-qualified host name of the auxiliary interface's agent platform, as reported by its underlying OS.
  • aux_localhostAddress: Resolves to the local address of the auxiliary interface's agent platform, as reported by its underlying OS.
  • aux_localhostIpv4Address: Resolves to the address of the IPv4 device-facing NIC (if any) at the auxiliary interface's agent which is used to communicate with the device.
  • aux_localhostIpv4Mask: Resolves to the mask of the IPv4 device-facing NIC (if any) at the auxiliary interface's agent which is used to communicate with the device.
  • aux_localhostIpv6Address: Resolves to the address of the IPv6 device-facing NIC (if any) at the auxiliary interface's agent which is used to communicate with the device.
  • aux_localhostIpv6Mask: Resolves to the mask of the IPv6 device-facing NIC (if any) at the auxiliary interface's agent which is used to communicate with the device.
  • aux_localhostName: Resolves to the host name of the auxiliary interface's agent platform, as reported by its underlying OS.

    For information about how localhostFullName and localhostName are resolved, see Managing global substitution parameters. Agent substitution parameters are useful when configuring syslog. One template is used that substitutes the Agent's IP Address when configuring syslog on devices that it manages.

Usage: ${agent.parameter}

Label

Substitutes a localized label for a device attribute or section of attributes as those labels appear inside a TSNA Device Attributes configuration. Note that this is the label or name of the attribute, not its value for a particular device. Valid parameter values include:

  • accessMode: The label for the access mode attribute

  • address: The label for the hostname/IP address/URL attribute

  • agent: The label for the device agent attribute

  • auxiliaryInterface: The label for the auxiliary interface section

  • category: The label for the category attribute

  • created: The label for the creation date/time attribute

  • deviceType: The label for the device type attribute

  • dsp: The label for the device security profile attribute

  • externalId: The label for the imported external ID attribute

  • fileServer: The label for the remote image file server attribute

  • groups: The label for the static groups section

  • manager: The label for the manager attribute

  • model: The label for the model attribute

  • name: The label for the device name attribute

  • natAddress: The label for the NAT address attribute

  • online: The label for the online attribute

  • osImage: The label for the OS image attribute

  • primaryInterface: The label for the primary interface section

  • realm: The label for the realm attribute

  • securityContext: The label for the security context attribute

  • systemDynamicFields: The label for the system-assigned dynamic fields section

  • transferMode: The label for the transfer mode attribute

  • userDynamicFields: The label for the user-assigned dynamic fields section

  • vendor: The label for the vendor attribute

Usage: ${label.parameter}

Global

Substitutes a globally defined parameter defined under the Admin tab. The parameter is the global parameter name (such as logServer1, ntpServer1, snmpROAcl). For example, ${global.logServer1} substitutes the logServer1 global parameter. You can assign a default value (for example, ${global.logServer1:10.1.1.56}.

Usage: ${global.parameter:default}

Template

Templates can be substituted into rules and templates. The parameter is the template name. A common use of template substitution is managing Access Control Lists (ACLs). For example, all ACLs require a common set of ACL entries. Define the common ACL entries in a template that is substituted into various ACL Rules.

Note: A template can include nested references to other templates, which the system recursively resolves, for up to 10 layers of nesting.

Usage: ${template.parameter}

Runtime

Substitutes a runtime parameter assigned by the user. The user is prompted to enter the runtime value for the parameter. You can assign a default value (for example, ${runtime.snmpcommunity:w0$y3p9}. If you use this option, the user is presented with a dialog box to enter a runtime value. You can specify up to 2000 characters in the value. 

Usage: ${runtime.parameter:default}

You can also assign a defined set of options. In this case, the user is presented with the list of options to a runtime value.

Usage: ${runtime.parameter:option1, option2, option3,...}

Runtime parameters should not be used in policy-based span actions unless default parameter values are assigned and are intended to be used.

Internal function

Executes an internal or user-defined function and substitutes the function's return value. One level of nested eval or exec inside an eval is permitted. Internal functions can be used to encrypt or update passwords or perform arithmetic operations.

Password encryption functions

The functions listed in this row return an encrypted password that matches a clear-text argument.

Where:

  • p1 is a clear-text password string
  • p2 is salt required for some encryption methods
  • p3 is encryption type

See Updating device passwords for how to use these internal functions for managing password changes.

Usage:

  • ${eval encrypt_cisco_vigenere_b64 p1 p2}
  • ${eval encrypt_gnu_md5_b64 p1 p2}
  • ${eval encrypt_gnu_extreme_md5_b64 p1 p2}
  • ${eval encrypt_md5_b64 p1}
  • ${eval encrypt_md5_hex p1}
  • ${eval encrypt_sha_hex p1}
  • NEW IN 8.9.04.001 ${eval encrpyt_cisco p3 p1 p2}
    where p3 can have the following values:
    • 4 – Specifies a SHA-256 encrypted secret string.
    • 5 – Specifies a message digest algorithm 5 (MD5) encrypted secret.
    • 8 – Specifies a Password-Based Key Derivation Function 2 (PBKDF2) with SHA-256 hashed secret.
    • 9 – Specifies an scrypt hashed secret.

Arithmetic functions

The following functions are defined to perform integer arithmetic:

  • add: Returns p1 + p2
  • subtract: Returns p1 - p2
  • multiply: Returns p1 + p2
  • divide: Returns p1 / p2
  • modulo: Returns p1 % p2
  • Where:

    p1, p2, ... are optional input parameters to the program or script. These input parameters can in turn be any substitution parameter, such as ${runtime.p1}, ${global.p2}, ${container.p3}, etc.

    All of the parameters for these arithmetic functions must resolve as integers.

Usage:

  • ${eval add p1 p2}
  • ${eval subtract p1 p2}
  • ${eval multiply p1 p2} 
  • ${eval divide p1 p2}
  • ${eval modulo p1 p2}

External program

Executes an external program and substitutes the program's return value.

Where:

  • program is the name of the program or script located in the endorsed directory (that is, BCAN_DATA/endorsed).
  • p1, p2, ... are optional input parameters to the program or script. These input parameters can in turn be any substitution parameter, such as ${runtime.p1}, ${global.p2}, ${container.p3}, etc.

Usage: ${exec program p1 p2 ...}

User-defined function

You can define your own functions. Use the following procedure to define a function:

  1. Create a Java class to implement a user-defined method.
  2. Specify the mapping of the function name and the implementation class in a property file named eval.properties, located in the BCAN_DATA directory. Create this file if it does not exist.
  3. Put the Java class into a .jar file, and then copy the .jar file to BCAN_DATA/endorsed folder.
  4. Restart the Tomcat server.

    Usage:

    To add two functions, toLowerCase and toUpperCase:* Create a class, say, com.mycompany.bbnaeval.MyStringFunctions.* Implement toLowerCase() and toUpperCase() methods. These methods needs to be public static.* Add the following lines to the eval.properties file:

    toLowerCase=com.mycompany.bbnaeval.MyStringFunctions
    toUpperCase=com.mycompany.bbnaeval.MyStringFunctions


Back to top

Pod substitution parameters

All pod-related substitution parameters have the basic form ${pod.parameter}. The string indicated by parameter can contain multiple components. See Pod substitution parameter syntax in the BMC Cloud Lifecycle Management on-line technical documentation.

Container substitution parameters

All container-related substitution parameters have the basic form ${container.parameter}. The string indicated by parameter can contain multiple components. See Container substitution parameter syntax in the BMC Cloud Lifecycle Management on-line technical documentation.

Back to top

Example parameter substitution

Examples are based on Cisco IOS CLI:

hostname ${device.host}
snmp-server community ${global.snmpROCommunity} RO ${global.snmpROAcl}
logging ${runtime.logServer1}
enable secret 5 ${eval encrypt_gnu_md5_b64 ${global.enablepw} ${trigger.1}
enable secret 8 ${eval encrypt_cisco 8 ${global.enablepw} ${trigger.1}
hostname ${exec assignHostName}

Back to top

Example Linux script execution

The following example demonstrates a simple script and how to use ${exec} to execute the script. ${exec} programs or script must be located in the BCAN_DATA/endorsed directory.

The script returns the value my_value.

  • Create the BCAN_DATA/endorsed/my_script.sh with the following lines:

    #!/bin/sh
    echo my_value
    
  • Invoke my_script.sh by using a ${exec} expression: 

    ${exec my_script.sh}

Note that the system examines exit code of your script. A zero exit code indicates success, while a non-zero indicates a failure. A failure is reported out in various ways, depending on the context of where this substitution parameter appears. The system might log an event, might log a warning message to the log file of the server, or might display an error message.

Back to top

Example Windows script execution

The following example demonstrates a simple script and how to use ${exec} to execute the script. ${exec} programs or script must be located in the BCAN_DATA\endorsed directory.

The script returns the value my_value.

  • Create the BCAN_DATA\endorsed\my_script.bat file with the following lines:

    @echo off
    echo my_value
  • Copy cmd.exe into the endorsed directory: 

    copy C:\windows\system32\cmd.exe BCAN_DATA\endorsed

  • Invoke my_script.bat by using a ${exec} expression: 

    ${exec cmd.exe /c my_script.bat}

Substitution parameters applicability

Substitution parameters can be used by the following components:

Component

Adhoc
templates

Templates

Rules

Configuration
Profiled
dynamic
fields

Configuration
Search Report

Custom
Actions

External
Script
Actions

External
links

Internal
Function

External
Program

Device

X

X

X

X

X

X

X

X

X

X

Agent

X

X

X

X

X

X

X

X

X

X

Label  XX      

Global

X

X

X

X

X

X

X

X

X

X

Template

X 1

X 1

X

 

X

X

Run-Time

 

X

X

X

X

X

Internal
Function

X

X

X

X

X

X 2

X 2

External
Program

XX

X

X

X

X 2

X 2

Pod

X

X

X

X

Container

X

X

X

X

Footnotes:

  1. TrueSight Network Automation allows 10 layers of nesting for template substitution parameters in templates.
  2. TrueSight Network Automation allows 1 layer of nesting for the following substitution parameter and component combinations:
    • Internal Function substitution parameters in Internal Functions.
    • Internal Function substitution parameters in External Programs.
    • External Programs substitution parameters in Internal Functions.
    • External Programs substitution parameters in External Programs.

Be cautious when using internal function or external program substitution parameters in CAP queries because they impact the performance of Snapshot and Refresh Device Status span actions.

Some factory installed templates (syslog) and rules reference global substitution parameters. Ensure you create and assign values to these global substitution parameters before using the factory installed templates and rules.

When referring to a Multi Select Menu type of dynamic field, the system replaces the substitution parameter with all values of the dynamic field in sorted order. Be cautious about referring to such dynamic fields because such a list of values might be invalid in context. For example, if you are editing a template, a device might not accept a comma-separated list of values in its command line. Follow these guidelines when referring to such a dynamic field:

  • If the text is inside something that carries a regular expression (such as the subject pattern in a rule), the system separates the values with the | (or) operation. For example: valueA|valueB|valueC. You must include parentheses around the substitution parameter in order for the or operation to have an effect. For example: (${device.myValueList}) is the correct way to refer to a Multi Select Menu dynamic field in a rule. Thus, referring to a Multi Select Menu dynamic field in a regular expression means you are searching for a match on one of its values.
  • If the text is inside a non-regular expression (such as the subject line in a rule), the multiple values are separated by a comma and a space. For example: valueA, valueB, valueC.

Back to top

Was this page helpful? Yes No Submitting... Thank you

Comments