NCM device template commands

Device templates can define the following commands for a specific type of device. These commands specify what keystrokes or CLI commands NCM sends when it performs an action on that type of device. They can also be used to change NCM's default behavior. For example, you can change the text that identifies the password prompt or you can change the line feed characters that NCM sends by default.

These commands modify the interaction between NCM and your network devices. Ensure you fully understand what modifications will do before modifying a device in production using these commands.

In the XML editor, every device template command includes the following attributes:

• Command Name identifies the command.
• Value defines what that command does when it is executed.

Not all commands are supported on all devices.

Download commands

DownloadConfig

Use the DownloadConfig command to download a config directly using Telnet or SSH. The Value defines the CLI commands to display the config. When the device displays the configuration, NCM parses the information and downloads the config. Examples include:

<Command Name="DownloadConfig" Value="Show ${ConfigType}" />

<Command Name="DownloadConfig" Value="get config"/>

DownloadConfigIndirect

Use the DownloadConfigIndirect command to download the config indirectly using TFTP. The config is transferred from the device to the SolarWinds TFTP server and then downloaded. The Value defines the commands to transfer the config to the TFTP server. For example: 

<Command Name="DownloadConfigIndirect" Value="copy ${ConfigType} ${TransferProtocol}://${StorageAddress}/${StorageFilename}${CRLF}${StorageAddress}${CRLF}y${CRLF}"/>

DownloadConfigIndirectSCP

Use the DownloadConfigIndirectSCP command to download the config indirectly using SCP. The config is transferred from the device to the SCP server and then downloaded. The Value defines the commands to transfer the config to the SCP server.

<Command Name="DownloadConfigIndirectSCP" Value="${EnterConfigMode}${CRLF}save ${TransferProtocol}://${SCPServerUserName}@${StorageAddress}/${StorageFileName}${CRLF}${SCPServerPassword}${CRLF}${ExitConfigMode}"/>

ConfigType attribute for download commands

The ConfigType attribute identifies the config type (Running, Startup, Device Type, or a custom type). Include this attribute if different commands are issued for the same action depending on the config type. For example, Palo Alto devices can have a different DownloadConfigIndirectSCP command for each device type:

<Command Name="DownloadConfigIndirectSCP" ConfigType="Running" Value="${TransferProtocol} export configuration from running-config.xml to ${SCPServerUserName}@${SCPStorageAddress}:/${StorageFilename}${CRLF}yes${CRLF}${SCPServerPassword}"/>

<Command Name="DownloadConfigIndirectSCP" ConfigType="Device State" Value="${EnterConfigMode}${CRLF}save device-state${CRLF}exit${CRLF}${TransferProtocol} export device-state to ${SCPServerUserName}@${SCPStorageAddress}:/${StorageFilename}${CRLF}yes${CRLF}${SCPServerPassword} Regex="\[edit\]" "/>

Multiple commands with the same name and config type

If a device template contains multiple commands with the same name and the same config type, NCM uses the value for the first command listed. For example, if a device template contained the following entries, NCM would use the first value, Show ${ConfigType}:

<Command Name="DownloadConfig" ConfigType="Running" Value="Show ${ConfigType}"/>
<Command Name="DownloadConfig" ConfigType="Running" Value="display ${ConfigType}"/>

Commands with the same name, with and without a config type

If a command does not specify a config type, it is the default command used for all config types not explicitly specified. For example, if a device template contained the following entries, NCM would use the value Show ${ConfigType} for any config type other than Running:

<Command Name="DownloadConfig" ConfigType="Running" Value="Show running"/>
<Command Name="DownloadConfig" Value="Show ${ConfigType}"/>

Upload commands

UploadConfig

Use the UploadConfig command to upload the config directly to a device using Telnet or SSH. The Value defines the CLI commands to upload the config. For example:

<Command Name="UploadConfig" Value="${EnterConfigMode}${CRLF}${ConfigText}${CRLF}${ExitConfigMode}" />

UploadConfigIndirect

Use the UploadConfigIndirect command to upload the config indirectly using TFTP. The config is transferred to the SolarWinds TFTP server and then uploaded to a device. The Value defines the commands to transfer the config to the TFTP server. For example:

<Command Name="UploadConfigIndirect" Value="copy ${TransferProtocol}://${StorageAddress}/${StorageFilename} ${ConfigType} vrf management${CRLF}${CRLF}" />

UploadConfigIndirectSCP

Use the UploadConfigIndirectSCP command to upload the config indirectly using SCP. The config is transferred to the SCP server and then uploaded to a device. The Value defines the commands to transfer the config to the SCP server. For example:

<Command Name="UploadConfigIndirectSCP" Value="copy ${TransferProtocol}://${SCPServerUserName}@${SCPStorageAddress}/${StorageFilename} ${ConfigType} vrf management${CRLF}${SCPServerPassword}" />

ConfigType attribute for upload commands

The ConfigType attribute identifies the config type (Running, Startup, Device Type, or a custom type). Include this attribute if different commands are issued for the same action depending on the config type. For example, Palo Alto devices can have a different UploadConfigIndirectSCP command for each device type:

<Command Name="UploadConfigIndirectSCP" ConfigType="Running" Value="${TransferProtocol} import configuration from ${SCPServerUserName}@${SCPStorageAddress}:/${StorageFilename}${CRLF}yes${CRLF}${SCPServerPassword}${CRLF}${EnterConfigMode}${CRLF}load config from ${StorageFilename}${CRLF}commit${CRLF}exit"/>

<Command Name="UploadConfigIndirectSCP" ConfigType="Device State" Value="${TransferProtocol} import device-state from ${SCPServerUserName}@${SCPStorageAddress}:/${StorageFilename}${CRLF}yes${CRLF}${SCPServerPassword}${CRLF}${EnterConfigMode}${CRLF}load device-state${CRLF}commit${CRLF}exit"/>

For more information, see Multiple commands with the same name and config type and Commands with the same name

Commands to perform other actions

<configType> commands

Include a command for each config type (default or custom) that you manage on the device. The Name of the command specifies the config type (for example, Running, Startup, Device State, or a custom config type). The Value indicates the commands to specify that config type on the device. For example:

<Command Name="Startup" Value="saved-configuration"/>
<Command Name="Running" Value="current-configuration"/>

If the config is in XML and you want to maintain the formatting, use the Format attribute to specify XML:

<Command Name="Running" Value="running" Format="XML" />

Use the IsBinary attribute to identify a binary config:

<Command Name="Device State" Value="Device State" IsBinary="true" />

Disconnect

The Value of this command defines the commands used to terminate the session when the operation is complete. The following example would issue the command exit:

<Command Name="Disconnect" Value="exit"/>

EnterConfigMode

The Value of this command defines the commands used to enter the configuration mode of a device. The following example would issue the command config terminal:

<Command Name="EnterConfigMode" Value="config terminal"/>

ExitConfigMode

The Value of this command defines the commands used to exit the configuration mode of a device. The following example would issue the command end:

<Command Name="ExitConfigMode" Value="end"/>

PreCommand

Use pre-commands for devices that require input before prompting for credentials, and for devices that prompt for interaction after an action is performed. The Value attribute specifies the action to take when a device has not responded for more than three seconds (by default) and, optionally, when the device sends a specific prompt (such as Press Any Key).

For example, when you connect to a certain type of router, you must press Enter to wake up the connection before you are asked for a password. The following example sends a carriage return and line feed combination after a three second delay:

<Command Name="PreCommand" Value="${CRLF}"/>

The following example presses Ctrl+Y when the device does not respond for three seconds:

<Command Name="PreCommand" Value="${CTRL+Y}"/>

Use the Delay attribute to add a number of seconds to the default delay of three seconds. For example, the following command presses Ctrl+Y when the device does not respond for five seconds (the default three plus two added by the Delay attribute):

<Command Name="PreCommand" Value="${CTRL+Y}" Delay="2"/>

Use the RegEx attribute to respond to a specific prompt. For example, the following command presses Ctrl+Y when the device does not respond for four seconds and the last data received is Press Any Key:

<Command Name="PreCommand" Value="${CTRL+Y}" Delay="1" RegEx="Press Any Key"/>

Reboot

The Reboot command identifies the commands and keystrokes required to reboot the device. For example:

<Command Name="Reboot" Value="reload${CRLF}Yes"/>

RebootAt

The RebootAt command identifies the commands and keystrokes required to reboot the device at a specified time. Use the available date and time variables to assign the date and time. For example:

<Command Name="RebootAt" Value="reload at ${HH}:${NN}${CRLF}Yes"/>

RESET

The RESET command identifies the commands and keystrokes required to turn off paging. NCM attempts to run this command after it has logged in to the device, detected the enable prompt, and determined that the device is ready to accept commands. For example:

<Command Name="RESET" Value="terminal width 0${CRLF}terminal length 0"/>

Some devices, such as VPN concentrators, might require a null value for the RESET command to function properly. If you receive an Out of Range error, change the value of the RESET command from 0 to blank. For example:

<Command Name="RESET" Value=""/>

You can also use the RESET command if a device's command mode prompt changes after the execution of a specific command. For example, some devices require you to switch user context before executing a command, resulting in a different command prompt. To handle this type of prompt changing, include the MenuBased command to specify the template logic should run in CLI mode, followed by the RESET command:

<Command Name="MenuBased" Value="false"/>
<Command Name="RESET" Value="switchContextCommand" RegEx="newPrompt"/>

The Value attribute identifies the command that changes the command mode prompt, and the RegEx attribute specifies the new prompt. For example:

<Command Name="RESET" Value="run /util bash" RegEx="#"/>

SaveConfig

The SaveConfig command identifies the commands and keystrokes required to write the configuration to the device's memory. For example:

<Command Name="SaveConfig" Value="write memory"/>

Version

The Version command identifies the commands and keystrokes required to display the software version of the device. For example:

<Command Name="Version" Value="show version"/>

Commands that specify custom prompts or change the default behavior

AllocatePty

If your device does not support pseudoterminal device pairs, use the following command to prevent Telnet from attempting to negotiate a pseudoterminal setup:

<Command Name="AllocatePty" Value="false"/>

CommandCharKey

By default, NCM sends the following characters after each command to simulate pressing Enter:

• After pre-commands, NCM sends CRLF.
• After commands sent using SSH, NCM sends CR.
• After commands sent using Telnet, NCM sends CRLF.

For devices that require different characters, include this command to override the defaults.

<Command Name="CommandCharKey" Value="xx"/>

The Value is one of the following:

• CR - NCM sends CR after each pre-command and command.
• CRLF - NCM sends CRLF after each pre-command and command.
• None - NCM does not send any characters after pre-commands, and it sends the default characters after each command.

ConfigStartsFromRegex

Use this command to exclude echo and specify the start of the configuration:

<Command Name="ConfigStartsFromRegex" Value="startOfConfig" />

The Value is a regular expression that identifies the start of the config. For example:

<Command Name="ConfigStartsFromRegex" Value="&lt;\S+&gt;" />

If a device template includes the command above and a device returns the following:

echo 1
echo 2
<Config>
...
</Config>

NCM saves this as the configuration:

<Config>
...
</Config>

CustomMorePromptBehaviour

If NCM needs to send a CRLF to the device immediately when a More prompt is detected, add the following line to the top of the device command template:

<Command Name="CustomMorePromptBehaviour" Value="True"/>

CustomPasswordPrompt

By default, NCM recognizes the password prompt when it includes the words password or passcode and ends with a colon (:). Include this command for devices that use password prompts that NCM does not recognize: 

<Command Name="CustomPasswordPrompt" Value="passwordPrompt"/>

The Value is a regular expression that identifies the custom password prompt. For example, the following identifies key: as the password prompt.

<Command Name="CustomPasswordPrompt" Value="key:"/>

CustomQuestionPrompt

If a device sends a question prompt that NCM does not recognize, use this command to identify the question prompt:

<Command Name="CustomQuestionPrompt" Value="promptText" />

The Value is a regular expression that matches the prompt text. For example:

<Command Name="CustomQuestionPrompt" Value="please confirm" />

When you include a CustomQuestionPrompt command, NCM's default prompt detection is disabled. Therefore, you can use a CustomQuestionPrompt command for situations where you don't want NCM to detect a question prompt by mistake. For example, a Huawei device sends a line similar to the following before the config and waits for Enter to continue:

<cr>|ont<K>|port<K>|section<K>|service-port<K>|simple<K>||<K> }:

With its default prompt detection logic, NCM mistakenly identifies this line as a question prompt and attempts to send the next command. To prevent this, specify any custom question prompt to disable the default prompt detection logic, and also include a pre-command to press Enter:

<Command Name="CustomQuestionPrompt" Value="/?" />
<Command Name="PreCommand" Value="${ENTER}" />

CustomUserNamePrompt

Use this command if the device has a non-default user name prompt that NCM does not recognize:

<Command Name="CustomUserNamePrompt" Value="userNamePrompt"/>

The Value attribute is a regular expression that identifies the user name prompt. For example:

<Command Name="CustomUserNamePrompt" Value="Name:"/>

EnableCommand

If NCM must enter a command to provide a higher level of access on a device but that command is not Enable, use this command to specify the command to use:

<Command Name="EnableCommand" Value="commandForHigherAccess"/>

For example:

<Command Name="EnableCommand" Value="super"/>

EnableIdentifier

If a device does not return the # character at the end of a prompt to indicate enable mode, use this command to identify the prompt that it uses:

<Command Name="EnableCommand" Value="promptUsedInEnableMode"/>

For example: 

<Command Name="EnableIdentifier" Value="(enable)"/>

EnterCLI

Use this command to specify the keystrokes required to enter CLI mode on a menu-based device. NCM sends these commands after it receives the VirtualPrompt command:

<Command Name="EnterCLI" Value="keystrokesToEnterCliMode" Delay="milliseconds" RegEx=""/>

The Value defines the keystrokes that NCM sends. The Delay attribute specifies the number of milliseconds to pause between keystrokes. The RegEx attribute should always be empty.

<Command Name="EnterCLI" Value="${Downarrow}${Downarrow}${CRLF}" Delay="300" RegEx=""/>

FreezeLoginForPreCommand

Use this command to send all pre-commands to a device before starting the login process.

For example, if a device prompts for credentials twice, the following pre-commands send the first pair of credentials.

<Command Name="FreezeLoginForPreCommand" Value="True" />
<Command Name="PreCommand" Value="userName" />
<Command Name="PreCommand" Value="password" />

The commands above can also be used when NCM is unable to read the login prompts on a device.

FreezeLoginForPreCommand cannot be used with SSH.

LineBreakChar

By default, NCM uses CRLF to identify line breaks. For devices that use different characters, use this command to specify what characters NCM should use when uploading a config: 

<Command Name="LineBreakChar" Value="lineBreakCharacters"/>

The Value is one of the following:

• LF
• CRLF
• CR

For example: 

<Command Name="LineBreakChar" Value="LF"/>

MenuBased

Use this command to specify whether the device is menu- or CLI-based. Valid values are true (for menu-based devices) or false (for CLI-based devices). For example:

<Command Name="MenuBased" Value="true"/>

If a device is menu-based and you can switch it to CLI from the menu, use the VirtualPrompt and EnterCLI commands to do so.

MenuDrivenConfigStart

For menu-based devices, use this command if you need to declare a value after which the transmitted data is considered the requested config. In the following example from the Cisco VPN Concentrator device template, the Value is ##########. The information sent after the ten hash signs is saved as the requested configuration file.

<Command Name="MenuDrivenConfigStart" Value="##########"/>

More

If paging is not turned off on a device, the configuration could be split into multiple pages and NCM must send a Space to go to the next page. In most cases, the More prompt is automatically recognized. If not, include the More command to identify the More prompt used by the device.

<Command Name="More" Value="unrecognizedMorePrompt"/>

For example:

<Command Name="More" Value="-Press Any Key For More-"/>

Do not specify this command unless you are experiencing issues with paging.

MorePromptKey

By default, NCM sends a Space in response to a More prompt. For devices that require a different response, use this command to specify what keystroke should be sent.

<Command Name="MorePromptKey" Value="responseToMorePrompt"/>

For example, use the following command for devices that require pressing Enter in response to a More prompt:

<Command Name="MorePromptKey" Value="${Enter}"/>

PromptIgnoreSequences

On some devices, the command mode prompt changes after certain script lines are executed. For example, on Huawei devices, after sys is sent, the command prompt changes from <prompt> to [prompt]. For these devices, use this command to define the sequences of characters to be ignored during prompt comparison:

<Command Name="PromptIgnoreSequences" Value="charactersToIgnore"/>

The Value specifies the characters to ignore. Multiple characters are separated with this macro: ${;}. For example, the following command specifies that parentheses () and square brackets [] should be ignored during prompt comparison:

<Command Name="PromptIgnoreSequences" Value="[${;}]${;})${;}("/>

If you include this command, be careful not to specify characters that, if ignored, would cause NCM to match other data sent by the device to the command prompt.

UseExactPromptMatch

When a config contains the command mode prompt as part of the config text, by default NCM stops capturing the config at that point and the downloaded config is incomplete. To prevent this, use the following command to cause NCM to detect the command mode prompt only if it appears on a separate line with no additional data:

<Command Name="UseExactPromptMatch" Value="true" />

UseMultipleDownloadCommands

By default, for direct transfers, NCM captures the output from only the first command in the DownloadConfig value. If you need to capture the output from other commands to download a config from a device, set UseMultipleDownloadCommands to True:

<Command Name="UseMultipleDownloadCommands" Value="True" />
<Command Name="DownloadConfig" Value="command1${CRLF}command2${CRLF}command3" />

For example:

<Command Name="UseMultipleDownloadCommands" Value="True" />
<Command Name="DownloadConfig" ConfigType="Running" Value="set cli op-command-xml-output on${CRLF}show config running"/>

You can also use UseMultipleDownloadCommands with a Cisco ASA device to download both the running and startup configs from the same context with only one device template. To do this:

1. Create a custom config type for each type of config in each context (for example, Context1Running and Context1Startup).
2. In your device template, include commands to switch into each context and download the config for each config type you created.
3. In the DownloadConfig command: 
   • Enter ${ConfigType} as the Value.
   • Specify the command prompt symbol as the RegEx attribute (for example, #, >, or ]).

For example: 

<Command Name="Context1Running" Value="changeto context Context1${CRLF}show running" />
<Command Name="Context1Startup" Value="changeto context Context1${CRLF}show startup" />
<Command Name="DownloadConfig" Value="${ConfigType}" RegEx="#" />
<Command Name="UseMultipleDownloadCommands" Value="True" />

UseVirtualPromptForCommands

By default, the VirtualPrompt value is used only to recognize a nonstandard command mode prompt during the login stage. However, some devices change the command mode prompt frequently, especially during script execution. This causes NCM to execute scripts slowly. For these devices, you can include UseVirtualPromptForCommands to specify that NCM should use the VirtualPrompt value during the entire NCM session.

This command is useful when it is not possible to use PromptIgnoreSequences to define all possible character sequences in the command prompt, but the prompt always includes a common string. You can specify that common string as the VirtualPrompt value.

For example, during script execution, a device's command prompt changes after each command:

[Prompt#]
[Prompt#-Interface1]
[Prompt#-Interface2]

The common string is Prompt#, so the device template would include the following commands:

<Command Name="UseVirtualPromptForCommands" Value="True"/>
<Command Name="VirtualPrompt" Value="Prompt#"/>
<Command Name="MenuBased" Value="false"/>

If you include this command, be careful not to specify a VirtualPrompt value that would cause NCM to match other data sent by the device to the command prompt.

VirtualPrompt

When the device does not have a standard command mode prompt that ends in > or #, use this command to identify the command prompt used to designate that the device is ready for commands to be sent. Include the MenuBased command to specify whether the template logic should run in CLI mode:

<Command Name="MenuBased" Value="trueOrFalse"/>
<Command Name="VirtualPrompt" Value="nonstandardPrompt"/>

The Value attribute is a string or regular expression that identifies the prompt that NCM should receive before sending commands. CLI-based example: 

<Command Name="MenuBased" Value="false"/>
<Command Name="VirtualPrompt" Value="(enable)"/>

Menu-based example:

<Command Name="MenuBased" Value="true"/>
<Command Name="VirtualPrompt" Value="Welcome"/>

VirtualEnablePrompt

Use the VirtualEnablePrompt command to search the device's entire response for a string or regular expression that identifies the enable prompt. This command is often used with menu-based devices, allowing you to locate a specific phrase returned by the device. If you use the VirtualEnablePrompt command, also include the MenuBased to specify whether the template logic should run in CLI mode. For example: 

<Command Name="MenuBased" Value="true"/>
<Command Name="VirtualEnablePrompt" Value="device_edge#"/>

Commands to specify the SSH encryption algorithms used for the device

If you want to specify what SSH encryption algorithms NCM uses when communicating with a device (instead of using the default values), you can include the following commands:

• KeyExchangeList: The list of key exchange algorithms.
• KeySignatureList: The list of key signature algorithms.
• EncryptionList: The list of encryption algorithms.
• HMacList: The list of digest algorithms.

Each command is followed by a comma-separated list of values, as shown in the examples below.

The values that you specify must be supported by the devices that use the device template, and they must be supported by NCM. For information about supported algorithms, see Supported algorithms and ciphers for SSH communications.

How device templates work with the default settings

By default, NCM uses algorithms specified by Advanced Configuration settings with the same names as these commands. Values in a device template override the Advanced Configuration settings. If you include a command with at least one value in a device template, NCM uses that value for the associated devices and ignores all values in Advanced Configuration settings.

If you add some but not all commands to a device template, NCM uses the values in the device template for the specified commands and the default values for the unspecified commands. For example, if you enter only <Command Name="HMacList" Value="none" /> in a device template, NCM uses Value="none" for HMacList and the default values for all other settings.

Examples

<Command Name="KeyExchangeList" Value="diffie-hellman-group14-sha256,diffie-hellman-group-exchange-sha256,diffie-hellman-group-exchange-sha1,diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,ecdh-sha2-nistp256,ecdh-sha2-nistp384,ext-info-c" />

<Command Name="KeySignatureList" Value="rsa-sha2-512,rsa-sha2-256,ssh-ed25519,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ssh-rsa,ssh-dss" />

<Command Name="EncryptionList" Value="aes128-ctr,aes128-cbc,aes128-gcm@openssh.com,3des-cbc,blowfish-cbc,aes192-ctr,aes192-cbc,aes192-gcm@openssh.com,aes256-ctr,aes256-cbc,aes256-gcm@openssh.com,chacha20-poly1305@openssh.com,rijndael-cbc@lysator.liu.se" />

<Command Name="HMacList" Value="hmac-sha2-256-etm@openssh.com,hmac-sha2-256,hmac-sha2-512-etm@openssh.com,hmac-sha1-etm@openssh.com,hmac-sha2-512,hmac-sha1,hmac-sha1-96,hmac-md5,none" />