Analysis of a new device type

Does device allow multiple simultaneous Telnet or SSH client connections?

No: Document this fact for your users in <generalInfo>. Include <error> tags to catch errors reported by the device indicating contention over the login session.

Are there variations in the device prompt or response when logging in using local versus external authentication (such as TACACS or RADIUS)?

Yes: Add the appropriate conditional logic to the login sequence. Sometimes, external authentication introduces a different prompt or emits different success or failure messages, which you can handle using regular expressions and optional interactions.

Many factory-installed device types use regex="true" on login interactions and use the following regular expressions to match login prompt variations:

username: ([Uu]ser.*:|[Ll]ogin.*:)

password: [Pp]assword:

Does device support SSH2 in addition to Telnet?

Yes: Set the <supportsSsh2Access> tag to true. The <supportsTelnetAccess> tag defaults to true. Add conditional logic to the login sequence. A Telnet session typically prompts for a user name and a password, whereas an SSH session bypasses those prompts. If the SSH session does encounter those prompts, set <supportsInteractiveSshAuth> to true and implement handling of those prompts in the login sequence.

Is the device unresponsive until you type some control sequence?

Some devices expect you to type CTRL-Y or CTRL-D or asimilar sequence to get its attention before it prompts you to log in.

Yes: Include sending the attention-getting characters as first in the login sequence. Refer to Common concepts and XML elements for how to specify non-printable control characters in the command string.

Is a tty setting required by the SSH server (by default you do not set a pseudo tty since some devices cannot handle it)?

Try unsetting TERM in your UNIX environment before you attempt to connect with the SSH client to see whether this is the case.

Yes: Specify the TERM setting in the <sshPseudoTty> tag (for example, set it to vt100 or dumb or ansi).

Is a tty setting required by the Telnet server (by default you do not set a pseudo tty since some devices cannot handle it)?

Try unsetting TERM in your UNIX environment before you attempt to connect with the Telnet client to see whether this is the case.

Yes: Specify the TERM setting in the <telnetPseudoTty> tag (for example, set it to vt100 or dumb or ansi).

Is emergency serial console access to the device required?

If the device configuration is erroneously changed such that it can no longer be reached over the network, you can connect the device's console port to a terminal server. You can then treat this as an auxiliary interface to the device, ready for emergency use.

Yes: Perform the necessary cabling and configuration of the terminal server. Set the <supportsSerialTerminalServerManagement> tag to true, which allows devices of this type to use device security profiles with terminal server support enabled. Then add conditional interactions to the login sequence to the terminal server. From that point on, the normal user name and password prompting that you implemented for a Telnet connection should work.

The check to make to see if you are connected to a terminal server is:

Is it necessary to turn off pagination when you are connected to the device?

Pagination can complicate the device type logic (need to detect when something takes more than a page, output the next page command, and detect the last page, need to strip page sections out of capture outputs).

Yes: Include command to turn off pagination in the login sequence. Bypass this command during a Telnet/SSH Session or an SSH Proxy session, which is indicated by the existence of the terminalLogin property.

Is it necessary to turn off command line wrapping?

Some devices have a terminal width setting that causes long commands to wrap, where this wrapping is done through explicit output of control sequences. This can clutter up a transcript and can cause misinterpretation of what the device emits as output. (Some devices simply allow the Telnet or SSH client to handle word wrapping.)

Yes: Include command to disable terminal width, or to set it to as large as possible. Bypass this command during a Telnet/SSH Session or an SSH Proxy session, which is indicated by the existence of the terminalLogin property.

Is it necessary to turn off the printing of syslog messages while you are connected to the device?

Some devices echo syslog messages to the Telnet/SSH session you are logged in to, which can interfere with captured outputs and reading of prompts.

Yes: Include command to turn off syslog messages to the interactive session in the login sequence. Do this as early as possible, since syslog message can interfere with every interaction. Bypass this command during a Telnet/SSH Session or an SSH Proxy session, which is indicated by the existence of the terminalLogin property.

Is it necessary to turn off command line completion or auto-complete?

Many devices examine each character you type and tries to predict what command is being entered. This can cause excessive unreadable characters to accumulate in transcript, making the transcript difficult to read and thus complicate debugging.

Yes: If possible, turn off this feature as soon as the login sequence is completed. Bypass this command during a Telnet/SSH Session or an SSH Proxy session, which is indicated by the existence of the terminalLogin property.

What login modes are supported? What credentials are needed to log in (only a user name, only a password, both user name and password, none)?

The answers to these questions affect the login sequence (which prompts you need to handle, which interactions are required or optional).

What types of user accounts are supported?

What credentials are required to enter privileged (or enable) mode (only a user name, only a password, both user name and password, none)?

The software must typically be logged into privileged mode to copy configuration files back and forth. Can you log in and be dumped right into enable mode? Can you go to enable mode with no user name or password? Can you go to enable mode with only a password? Can you go to enable mode with a user name and password? The answers to these questions affect how complex the login sequence becomes.

Bypass going into privileged mode during a Telnet/SSH Session or an SSH Proxy session, which is indicated by the existence of the terminalLogin property. Except go ahead and do it for a privileged SSH Proxy session, indicated by the existence of the terminalPrivLogin property.

Is the command prompt static or varying? Can the command prompt be customized via some CLI command? Will the command prompt you see be the same for every device or can it be customized per device? Is there some minimal string (like a “>” or “#”) that will always be there?

For example, some devices have a command number in the prompt, so the prompt changes on each command. Some have a prompt that changes based on whether or not there are unsaved changes.

The answers to these questions affect if and when the prompt is captured during device interactions. The prompt can serve as a synchronization mechanism, so you know the device is sitting at a point where a command can be entered. If the prompt is static, capture it during the login sequence and use the captured value as a keyword. If it varies in a predictable way, you might be able to use a regular expression for matching the variable parts of it.

What are the appropriate command(s) to show the operating system version, hardware model, and startup location information (where applicable)?

Include the commands in the discover-core sequence, with <capture> tags to parse out the version, model, and other information. See Common concepts and XML elements to understand how discovered properties are propagated into the system.

Yes: Include capturing that name when capturing disc.imageName.

No: Include the <imageNamePrefix> element to assign an identifying prefix to the discovered operating system image version number.

Can the device report its available file transfer modes?

When multiple file transfer modes are supported, some devices show them in the supported syntax for its copy commands (such as copy ?). This can be used to auto-discover the file transfer mode.

Yes: Include conditional logic to discover the file transfer mode when the discoverTransferMode property is set to true (indicating the user has set the file transfer mode to auto). Test for whether or not FTP and SCP are supported and populate the disc.supportsFtp and/or disc.supportsScp properties with a value of true. If the device always supports a particular transfer mode, set the property to true without running any test command.

What configuration settings can be extracted from the device? Can changes be made to these settings?

Determine whether the settings can be considered to be the active or running settings, the stored or startup settings, or some other type of settings. For running and startup, use the existing trails to define your <supportedConfigurationTrailDeclarations> section. If you have other settings, define a new configuration trail adapter (see Developing-a-configuration-trail-adapter) and use it to populate <supportedConfigurationTrailDeclarations>. Include the <backupCommandGuid> to support taking snapshots; include the <mergeCommandGuid> or <restoreCommandGuid> to support deploy actions.

If there is the notion of a running or active configuration, and you can make changes to it, include the <defaultMergeCommandGuid> element, to define the command to execute when Deploy to Active action is run on a template. If there is the notion of a startup or stored configuration, include the <defaultRestoreCommandGuid> element, to define the command to execute when a Deploy to Stored action is run on a template.

Are scp, ftp, and tftp copy operations supported?

Yes: Add the appropriate conditional logic to the copy commands, and set the <supportsScpTransfer>, <supportsFtpTransfer>, and <supportsTftpTransfer> flags accordingly (scp/ftp default to false, tftp defaults to true). Then implement the logic in <deviceCommand> elements to perform the file transfers for snapshot and deploy actions. When sending ftp or scp passwords, be sure to flag the command as sensitive, to mask the password from view in the transcripts.

No: If the device does not support any file transfer copy operations, then you must test if the device can show its configuration data to the screen.

Can the current configuration contents be displayed to the screen?

Yes: Add support for tunneled snapshot. Set the <supportsTunneledTransfer> tag to true. Include the <supportsTunneled> tag set to true in the <deviceCommand> that performs the snapshot. In the <deviceCommand> associated with the trail's <backupCommandGuid>, include capturing the settings to the fileContents property, containing the text that makes up the configuration. Use conditional logic if file transfer can also be used to capture the same settings:

Is the configuration large or the network path to the device slow?

Yes: Any interaction that takes a snapshot or deploys a configuration might timeout before the file transfer is done, or before the configuration finishes coming out to the screen. Use the Timeout for Script File Transfers system parameter setting as the timeout. On each <interaction> that transfers a file or captures a configuration from command output, include this attribute:

Does the configuration expose sensitive data, such as passwords in the clear or SNMP community strings?

Yes: Include the sensitive command lines in the <sensitiveLines> element. This masks the matching data to users who lack the sensitive data right. It also masks the data in the device interaction transcript, in case a tunneled snapshot causes the transcript to contain a configuration.

When were the earliest version of compatible tftp/ftp/scp commands introduced into the device's command set?

Refer to the device documentation for this.

Include conditional logic to skip using the unsupported transfer mode depending on the discovered version. Include the minVersion attribute on the <deviceCommand> tag, or use an <assert> tag that tests the version (to combine with other checks). The disc.version property must be populated prior to making this check:

Is there any contention over filesystem resources if there is another concurrent telnet or ssh connection while you are performing a copy operations?

Some devices lock their files while they are being actively modified, so if another user tries to access or modify it at the same time, the device reports an error.

Yes: Add appropriate error retry logic to the copy commands. Add the retry="true" attribute to the <error> tag to retry the entire enclosing <deviceCommand> once, after a short pause (to allow time for the resource to free up); this pause is defined by the deviceCommandRetrySleepSeconds property in the global.properties.imported file. No error is reported if the second attempt is successful.

Does the device support deploying templates (partial running configurations)?

Some devices accept only complete configurations as inputs and lose any settings not included in the input. Losing settings can be incredibly disruptive; the device can become inaccessible, if it basically is reverted to its factory defaults.

This is termed overwrite logic, where the current configuration is completely replaced by the new configuration (whether or not that new configuration is complete). Alternately, overlay logic replaces just the supplied bits and leaves unspecified bits unchanged.

No: Add a note to the <generalInfo> to inform users that only complete configurations are to be deployed. Investigate if partial configurations may be deployed in tunneled mode, where a different set of commands can be run to push individual settings, thus providing an overlay mode. If so, add the <supportsTunnelMergeForConfigurationFile> tag set to false, to prevent invalid syntax from being used in tunneled mode.

Does the device automatically reboot after a Deploy to Active or Deploy to Stored action?

Yes: Use the disconnect attribute in the deployment commands. Also, set the rebootsAfterRestore element to true if appropriate, if the device reboots during a Deploy to Stored.

How does the device respond when you provide incorrect address or path information while performing copy operations?

Include these common error paths in the copy commands.

Is configuration parsing error feedback provided by the device during a Deploy to Active or Deploy to Stored action?

Some devices can check the syntax of the commands in a file before deploying it; some can report syntax errors as it is being deployed.

Yes: Include the <syntaxErrors> element that lists the syntax errors the device can report; these errors will be checked in all file transfer modes. In a tunneled deploy, include the <syntaxErrorCheck> element to set a property when one of the <syntaxErrors> is matched; include a <break> to exit the <loop> on such an error and when user requested that we stop on error:

Is it possible to change the prompt during a Deploy to Active action? If the prompt is changed, your captured old prompt will no longer work.

Yes: If you are planning on relying on a captured prompt property in composing your XML interactions, then you have to be careful to recapture the prompt after the deploy has completed, in case it is changed as a side effect.

Does the device support the notion of unsaved changes and does it support saving them as a distinct command?

Yes: Implement the commit sequence, to run the command and answer any prompts (such as, Are you sure and the like).

Are there variations in the device responses when there are unsaved configuration changes while attempting to perform a reboot or logout operation?

Yes: Add the appropriate conditional logic to those commands, and set the <promptsUnsavedChanges> tag to true. In the reboot sequence, use the property saveChoice to determine if user asked to commit or discard unsaved changes. This property is not available during a logout.

If the prompt sequence is variable, use disconnect="sometimes" if an interaction can immediately run the reboot or can emit a prompt. If a reboot command or answer to a prompt goes off and does the reboot, use disconnect="always".

Does the device ask any other questions during a logout (such as, Are you sure)? Does the device have multiple levels of login resulting in multiple levels of logout?

Some devices that have a privileged mode have an exit process where the first exit takes you back to unprivileged mode, requiring a second exit to complete logging out.

Yes: Include answering all questions and exiting from all login levels. The goal is for the logout sequence to end the interactive session as cleanly as possible, so that no lingering sessions remain open in the device (eventually gobbling up all the available sessions until no new logins are possible). The system runs the logout sequence even when errors have occurred, to avoid this common issue.

Does the device warn you about unsaved changes while logging out?

Yes: Include conditional logic during the logout to answer such prompts. Use disconnect="sometimes" if a command could log out or could emit an extra prompt. Best practice is not to save unsaved changes while logging out.

Does the device reboot within the time specified in the Timeout for Re-Establishing Connections After a Reboot system parameter (Admin > System Parameter)?

No: Increase the value of the system parameter.

Is it possible to connect too early, via Telnet or SSH, after the device reboots?

Some devices allow connection attempts before all of their internal services are fully ready, which can cause the attempt to fail even though the socket connection succeeds. You probably will not be able to detect this until you actually use the software to reboot the device.

Yes: Use the <securitySleepSeconds> tag to introduce an additional pause to work around this problem.

Does the configuration file contain anything that varies each time the file is copied (such as a timestamp)?

Yes: Add these to the <commentLines> tag or <commentBlocks> tag as a regular expression. Use the scope attribute if needed to limit which trails the comment applies to. The goal is for consecutive snapshots do cause a discrepancy (running versus trusted running or startup versus trusted startup).

What are the comment indicators (usually a character at the beginning of a line, such as “!” or “#”)?

Add to the <commentLines> tag to ignore comments. Even if comments do not change much, comments are styled differently in the side-by-side difference reports, which can aid users in navigating the reports.

Does the configuration file contain lines or blocks that the device randomly reorders from one snapshot or reboot to the next?

These lines or blocks introduce discrepancies based solely on ordering differences, not content differences. The shifts are usually caused by editing, so they are not easy to find.

Yes: Add these lines or blocks to the <sortedCommands> tag, as either a single line command, a block command, or a negated list command. Add only the commands whose order is not meaningful or significant because the system stores these commands or blocks in sorted order. Any future deployment of the configuration will deploy the commands in sorted order. Do not add commands such as, access list permit or deny commands because the order is significant and making them sorted causes the system to maintain incorrect configuration data.

Does the configuration file contain any lines whose parameters are randomly reordered from one snapshot or reboot to the next?

These lines introduce discrepancies based solely on ordering differences, not content differences. The shifts are usually caused by editing, so they are not easy to find.

Yes: Add these lines to the <sortedParameters> tag. Add only the parameters whose order is not meaningful or significant because the system alters the command line to store the parameters in sorted order. Any future deployment of the configuration will deploy the parameters in the sorted order.

Does the configuration file contain independent single command lines that are constantly being re-ordered? That is, does the order of the configuration lines (which are not organized as blocks) never matter at all and does the device re-order them frequently?

Yes: Set the <sortEntireConfig> tag to true. The system sorts the entire configuration file and store all of the command lines in sorted order. Any future deployment of the configuration will deploy the commands in sorted order.

Does the device support a config or edit mode for making changes line by line?

No: To support syntax scan, the device must have some way to make configurations changes by typing in a command at a time.

Does the device emit any help text? Is the help text different for complete versus incomplete commands?

Type in a junk command, then a question mark. Most devices display help text. Note what the device does on junk and on good commands (complete and incomplete). Ideally, when a command is good and complete, the help tells you to enter return or CR; this is the text whose absence says there is a syntax error.

If you do not get help that is different for complete versus incomplete commands, then you cannot support syntax scan. The help string goes into the syntax scan interaction's help attribute setting.

What does the device do after the ‘?’ and the help – does it erase the line? Does it echo the command up to the question mark? Does the device support CTRL-U to erase a line?

This information is used by the syntax scan interaction's useCtrlU flag setting.

Does the device support blocks? Does the prompt change whenever you enter a block? What command exits a block?

Block support requires Smart Merge support, so this is not user-extensible, and thus syntax scan cannot be implemented properly.

Quirk: When lineErasure is set to last, usually things work fine when you send a command, then the ?, and then the CTRL-U (all in a single write operation). But sometimes this doesn't work for devices expecting a more human-like behavior (where it expects input at human typing speed, not computer speed).

Fix: Set the lineErasure attribute to first. The software then sends CTRL-U, then the command, then the ?. Some devices like that better. If that still fails, try the value separate. It might also be helpful to increase stutterMilliSeconds to slow down the rate at which the command string is sent to the device.

Quirk: A large volume of text emitted when the ? is typed causes the syntax scan to report spurious syntax errors.

Fix: Add a <pauseSeconds> to the syntax scan interaction. Without a pause, the software might not read all of the text; if the indicator for a good command is at the bottom, the software might not get it and will think every command is bad. If you see partial data reads, then add a value for <pauseSeconds>.

Quirk: Running syntax scan on a script containing a banner change reports spurious syntax errors.

Some devices use a CTRL-C character to delimit the start and end of a banner. They also interpret CTRL-C as a request to exit config mode.

Fix: Use the replaceCtrlCWith attribute to replace the CTRL-C with something else that does not interrupt config mode (such as a slash).

Fix: Add a <blockEntryError> tag to the syntax scan interaction. This tag defines an error that causes the block header line to be treated as a syntax error, and the subcommands will not be checked. The string you enter as a value here depends on whether the syntax scan interaction has regex="true" or not. You can enter the value as a regular expression when regex="true"; otherwise you must quote the exact string.

What are the SNMP OID reported by the device?

Use a management tool such as Entuity Network Analytics or HP NNM, or use the vendor MIB to determine the SNMP OID for this device. The right OID is usually found in the sysObjectID of the system MIB. If multiple models from this vendor are supported by this device type, they usually have different OIDs.

Enter each unique SNMP OID value as a dotted string value in the <snmpOids> tag.

Refer to the device documentation to determine what range of image versions support an interface compatible with all the commands that you will be using to control the device.

Add minVersion attribute to the <deviceCommand> tags to run the command for all versions at or after the specified version. Add <assert> or <condition> tests when you need to verify a maximum version number:

What models of device are supported?

Fill in <supportedModelInfo>.

What operating system versions are supported?

Fill in <supportedOsVersionInfo>.

Are there any rules governing the format and content of templates that users can deploy?

Fill in <templateFormattingInfo> with the detailed instructions. Refer to Common concepts and XML elements for how to format the value inside this element.

Are there any warnings or quirks that users need to be aware of?

Fill in <generalInfo>, in the header or in the relevant <deviceCommand>. Refer to Common concepts and XML elements for how to format the value inside this element.

Does the device emit a syslog message indicating a configuration change has been made, suitable for triggering the Auto Archive policy? Does this syslog message identify the user who made the change?

Set <supportsSyslogAutoArchiveTriggerInfo> to true. Also ensure that the keyword named Change Detected (under Admin > Keywords) matches the text of the change-reporting syslog message. If the message includes a user name, put parentheses in the regular expression around where the name appears so the system can parse this out.

Does the device include encrypted passwords in its configuration?

Fill in <passwordEncryptionFunctionInfo> if there is an ${exec} or ${eval} function that performs the applicable type of encryption. You can use the factory-installed functions or you can develop your own. This informs users how they can write rules that check if a password is set to the right value.

Is there a command that displays the device's main serial number?

Yes: Include another <deviceType> element with <extension> set to true that includes a <deviceCommand> implementing the Get System Serial Number custom action.

Is the device able to run a ping for testing its network connectivity?

Yes: Include another <deviceType> element with <extension> set to true that includes a <deviceCommand> implementing the Ping or Ping With VRF custom action.

Is the device able to run a traceroute for testing it network connectivity?

Yes: Include another <deviceType> element with <extension> set to true that includes a <deviceCommand> implementing the Traceroute  or Traceroute With VRF custom action.

Does the device support a show command, where inner components or statistics can be displayed?

Yes: Include another <deviceType> element with <extension> set to true that includes a <deviceCommand> implementing the Show Text custom action.

Can the current operating system image be extracted into a file, and can this file be copied off the device using TFTP, FTP, or SCP?

Yes: Ensure that image file properties are discovered during the discover-core device command. Implement the discover-image-details device command to discover additional image related information. This can be an empty shell if you plan to support only an image snapshot (no deploy). Then, implement the snapshot OS image device command, with conditional logic for the different file transfer modes.

Can you deploy an image onto different filesystems or partitions within the device?

Yes: Include <supportedFileSystems> containing the names of the filesystems or partitions the device will accept in its deploy command.

Can you download and install a new image using a single command?

No: If the image installation process is at all complicated, it cannot be supported. For example, if you have to coordinate between active and standby modules, or install multiple parts in a sequenced way, this normally requires the development of Java code in a custom loader class, which is not user-extensible.

Yes: Implement the deploy OS image device command with conditional logic for the different file transfer modes. Include <imageLoaderClassName> with value of:

(The "non-recovering" part of the name means the device itself ensures that the current image stays installed if some error occurs while trying to install a new image. This loader class does not perform old image recovery of of its own.)

Does a new image file need to fit onto the device's file system before it can be successfully downloaded to it and installed?

Yes: In the discover-image-details device command, code the discovery of the target image filesystem total, used, and free space. If you discover these properties, the system uses them to check that the new image file will fit. See Common concepts and XML elements for the names of the properties involved in this check.

This checks assumes that the device will delete its current image and the new image can use its space. If instead the new image file must fit into the current free space, include <imageMustFitInFreeSpace> set to true.

Does the device reboot automatically?

Yes: Include disconnect="always" on the interaction that installs the image.

Yes: The Timeout for Image File Transfers value in the Admin > System Parameters might need to be increased to accommodate the file size and the network path.

Include a note in the <generalInfo> warning about the requirement to set this timeout high enough.

For the <interaction> that performs the file transfer, use timeoutSeconds="%maxBinaryTransferDurationSeconds%"  to set the response timeout to the system parameter value.