Important

   

Starting version 8.9.03, BMC Network Automation is renamed to TrueSight Network Automation. This space contains information about BMC Network Automation 8.9.02 and previous versions. For TrueSight Network Automation 8.9.03 and later releases, see the TrueSight Network Automation documentation.

Analysis of a new device type

When adding support for a new type of device, analysis of the device's capabilities is a necessary prerequisite. You must determine whether the device is suitable for integration into BMC Network Automation and decide how fully it can be supported. For example, it might be possible to extract configuration data out of the device, but not push any changes into it. You might also choose to implement only what is easy to do, for example, skipping deploy operations for expediency. Many factory-installed device types are snapshot-only.

A few questions to answer first are: How does a user access the device? Is the device CLI based (using Telnet or SSH to get to a command line)? Does it run a web server for browser-based control? Does it have an HTTP-based web services API? Does it only support a proprietary API? Does it only accept SNMP requests?

If the device is CLI based, then use the following analysis sections. If the device is HTTP based, most of the content is still applicable, but then refer to factory-installed device type adapters for examples. If there is only SNMP or a proprietary API, then the device type might not be supportable. In that case, contact BMC Customer Support for professional services.

Login analysis

AnalysisResult

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:

<condition test="-EXISTS- managedBySerial">

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?

Devices typically have privileged and unprivileged user accounts that grant certain access upon login. If you can define an unprivileged account and the device has no command to switch to privileged, then you need to try all the rest of the commands (snapshot, reboot, and so on) as an unprivileged user to identify the necessary error tags. If you leave these error tags out, some interactions might mistakenly succeed if the normal response also comes out (for example, the prompt).

Ensure that the system is at the right privilege level to execute all of its commands by the end of the login sequence.

If it is possible for users to be granted selected privileges and you craft a user for BMC Network Automation to use, be sure to include the appropriate <error> tags in all other interactions to catch when BMC Network Automation is logged in under the wrong user account. You should also consider running some test command during the login sequence that ensures the right privileges are granted.

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.

Back to top

Discovery analysis

AnalysisResult

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.

Does the device display its operating system version with a distinctive name?

Some devices display a version number and do not show or do not have a commonly used name for the native operating system. BMC Network Automation lists all discovered operating systems by vendor, so it is desirable to be able to tell them apart by using unique names per device type.

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.

Back to top

Snapshot/Deploy analysis

AnalysisResult
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:

<condition test="%transferMode% -EQ- tunneled">

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:

timeoutSeconds="%defaultResponseTimeoutSeconds% -PLUS- %maxTextTransferDurationSeconds%"

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:

<deviceCommand minVersion="2.4">

<assert test="(%disc.version% -GE- 2.4) -AND- (-EXISTS- %cmd.someProperty%)" onFailure="abort">

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.

During a snapshot, does the device accept arbitrary filenames as the destination of the file copy request?

BMC Network Automation uses its own temporary files, whose name is given to the device in the file copy command. Some devices can copy only to a fixed filename of its own creation, with some way to extract that name (such as after the copy is completed).

No: Include the population of property filenameUsedByDevice containing the exact name of the file being transferred. BMC Network Automation device agent then looks for a file by this name in its transfer directory.

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:

<break condition="(-EXISTS- stopTunnelingOnSyntaxErrors) -AND- (-EXISTS- syntaxErrorOccurred)"/>

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.

Back to top

Commit/Reboot/Logout analysis

AnalysisResult
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.

Back to top

Discrepancy analysis

AnalysisResult

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.

Back to top

Syntax scan analysis

The basic idea of syntax scan is that BMC Network Automation enters commands in config mode, one command at a time, and interacts with the device like a user would to check if the command is good or not, without executing the command.

When a command doesn't work right in a syntax scan, try the same command interactively. Often the device reports an error for a perfectly good command, or it does not report any error for an obviously bad command. There is no workaround for such device misbehavior. Syntax scan can only be as good as the underlying device CLI.

If the configuration is block-oriented, you cannot implement syntax scan yourself. Accurate syntax scanning for a block-oriented device requires Smart Merge support, which is not user-extensible. Contact BMC for professional services.

AnalysisResult
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).

Quirk: When there is command blocking and the device already supports Smart Merge, BMC Network Automation checks the syntax of the block header line, and if that has no error, BMC Network Automation enters the block, checks the subcommands, and exits the block. Sometimes, the block header syntax check passes but entering the block emits an error. Spurious syntax errors are reported on the block's subcommands.

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.

Back to top

Import analysis

AnalysisResult

What are the SNMP OID reported by the device?

Use a management tool such as Entuity 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.

Back to top

Version analysis

AnalysisResult

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:

<deviceCommand minVersion="2.4">

<assert test="%disc.version% -LT- 4.3" onFailure="abort">

Back to top

Documentation analysis

It is important to let your users know what your new device type can do and any warnings or quirks about how it works. Fill in the Info tags to populate the Device Adapter Capabilities report more completely.

AnalysisResult
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.

Back to top

Custom action analysis

It is useful for a new type of device to support the following factory-installed custom actions. Support is optional, based on your evaluation of how useful these are for the new type of device. Also, there are more factory-installed custom actions you may wish to support; go to Admin > Device Adapters to review them.

You can use the Device Adapter Capabilities report or view the custom action adapter to obtain the GUID for the custom action.

AnalysisResult
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.

Back to top

OS image management analysis

Operating system image management covers the ability to extract the current operating system image file (the Snapshot OS Image action) or to install a new operating system image file (the Deploy OS Image action) or both. Supporting Snapshot OS Image means you can populate the images into the OS Image library for use in deploying them to other similar devices or reverting to an old version (even if you do this manually; you can still store the images in the database and pull them out for manual install). Supporting Deploy OS Image means you can perform software upgrades in response to bugs and vulnerabilities in the binaries, with the system doing configuration change tracking (so you can restore an old configuration if you have to push back to an old operating system).

Taking an image snapshot requires that the device support extracting its current operating system image as a file and copying that file using TFTP, FTP, or SCP.

Deploying an image requires that the device supports a simple installation process. Many modern devices support installation of a new operating system image via a single command, that file-transfers the new image, verifies it contains a complete and compatible binary, installs the image, propagates it internally to all its modules, clears away the old image, and (optionally) reboots. If your device has such a one-step command, then you can implement the Deploy OS image function in your device type adapter. If your device does not support such a simple procedure, then you cannot add support for image deployment; contact BMC for professional services.

Note also that testing and debugging image deployment XML code requires that you have a test device and at least two images (to alternate between them). You should have the device console port connected and be prepared for a failed deployment to leave your device in a trashed state (such as with no image at all or with an image that is incompatible or not even a binary file). Be prepared with your vendor's manual recovery procedures.

AnalysisResult
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:

com.bmc.bcan.engine.network.devices.SimpleNonrecoveringImageLoader

(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.
Are the operating system image files large (over 20MB) or is the network path between the device and the BMC Network Automation device agent slow or both?

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.

Back to top

Recommended development procedure

When developing a device type, there are many parts to be implemented. The following is a recommendation for the order you should follow to develop in small additive increments that you can test as you go. At each step, import the adapter to validate it, then test the action execution against the device. Carefully examine the transcript for errors that you are not catching or the passwords that you are not masking.

  1. Vendor and new trail definitions.
  2. Skeletal <deviceType> with header filled in, including SNMP OIDs.
  3. Fill in supported OS versions and models.
  4. Login: basic login using Telnet and SSH modes.
  5. Logout: clean exit of the session, leaving no open session behind.
  6. Login: all login scenarios, Telnet and SSH modes; user name/password errors include retry="true".
  7. Discover core: discover model and OS image; discover auto transfer mode. Make sure that OS version includes a prefix (can hardcode it or can be part of discovered strings).
  8. Snapshot running configuration: tunneled and file-transferred; identify configProcessors, commentLines, commentBlocks.
  9. Snapshot startup configuration.
  10. Snapshot other trails.
  11. Enumerate sensitiveLines.
  12. Commit.
  13. Reboot.
  14. Telnet/SSH session; add conditional logic to login to skip changing terminal settings and going to privileged mode.
  15. SSH proxy session, privileges and non-privileged modes.
  16. Common custom actions (get system serial number, ping, traceroute, show text).
  17. Deploy to running (active) configuration: tunneled and file-transferred; identify syntaxErrors and templateFormattingInfo.
  18. Deploy to startup (stored) configuration.
  19. Deploy of other trails.
  20. ARP and MAC trail custom actions.
  21. Other custom actions.
  22. Syntax scan.
  23. OS image snapshot, plus discover image core if needed.
  24. OS image deploy and any supporting commands (delete image, verify image, etc).

Back to top

Test plan

Use this test plan as a starting point; customize to test what is appropriate to your specific device.

  1. Device creation
    • Verify correct data and options in the device edit window. Check access modes and transfer modes allowed.
    • Verify correct values and formatting in the device adapter view and the device adapter capabilities report.
    • Verify device of the new device type can be created using device import.
  2. Login
    • Verify successful login to device with device set to Auto, Telnet, and SSH2 (or other applicable modes).
    • Verify successful login to device with no user name/password, no user name, no password, user name/password, privileged password, no privileged password, privileged user name/password.
    • Verify failed login with incorrect user name/password for Telnet and SSH2.
    • Verify failures detected if login as an under-privileged user or role.
    • Verify failures detected if device has maximum users logged in and can accept no more.
    • Verify that transcripts do not expose any passwords in clear text.
    • Verify the connection to console via terminal server.
  3. Discover core
    • Verify image name, model, and version are properly discovered and displayed in the Device View/Edit windows.
    • Verify the Admin > OS Images list; new image with its prefix should be distinctive among all the other images.
    • Test auto discovery for transfer mode.
  4. Snapshot running and startup configurations
    • Verify successful snapshot with ssh2/auto, ssh2/tftp, ssh2/ftp, ssh2/scp, ssh2/tunneled.
    • Verify successful snapshot with telnet/auto, telnet/tftp, telnet/ftp, telnet/scp, telnet/tunneled.
    • Verify failed snapshot – change tftp directory in Device Agent.
    • Verify failed snapshot – stop tftp service.
    • Verify failed snapshot – change ftp directory in Device Agent.
    • Verify failed snapshot – change ftp username or password.
    • Verify failed snapshot – change scp directory in Device Agent.
    • Verify failed snapshot – change scp username or password.
    • Verify failed snapshot – Edit Device with bogus NAT address.
    • Verify that transcript is readable and exposes no passwords.
    • Verify that configuration display is clean and readable.
    • Verify that consecutive snapshots don't produce changed configurations or discrepancies.
    • Verify that snapshot via file transfer and snapshot via tunneled mode produce the same output.
  5. Snapshot of other trails
    • Verify successful snapshot with tftp, ftp, scp, tunnel.
    • Verify failed snapshot – change tftp directory in Device Agent.
    • Verify failed snapshot – stop tftp service.
    • Verify failed snapshot – change ftp directory in Device Agent.
    • Verify failed snapshot – change ftp username or password.
    • Verify failed snapshot – change scp directory in Device Agent.
    • Verify failed snapshot – change scp username or password.
    • Verify failed snapshot – Edit Device with bogus NAT address.
    • Verify that transcript is readable and exposes no passwords.
    • Verify that configuration display is clean and readable for trails with ascii data.
    • Verify that consecutive snapshots don't produce changed configs.
    • Verify that snapshot via file transfer and snapshot via tunneled mode produce the same output.
  6. Deploy to Stored (Startup) configuration
    • Verify successful Deploy to Stored of startup configuration with tftp, ftp, scp.
    • Verify ability to deploy a template.
    • Verify failed deploy – change tftp directory in Device Agent.
    • Verify failed deploy – stop tftp service.
    • Verify failed deploy – change ftp directory in Device Agent.
    • Verify failed deploy – change ftp username or password.
    • Verify failed deploy – change scp directory in Device Agent.
    • Verify failed deploy – change scp username or password.
    • Verify failed deploy – Edit Device with bogus NAT address.
  7. Deploy to Stored of other trails
    • Verify successful Deploy to Stored of custom trail with tftp, ftp, scp.
    • Verify ability to deploy a template.
    • Verify failed deploy – change tftp directory in Device Agent.
    • Verify failed deploy – stop tftp service.
    • Verify failed deploy – change ftp directory in Device Agent.
    • Verify failed deploy – change ftp username or password.
    • Verify failed deploy – change scp directory in Device Agent.
    • Verify failed deploy – change scp username or password.
    • Verify failed deploy – Edit Device with bogus NAT address.
  8. Deploy to Active (Running) configuration
    • Verify successful Deploy to Active (overlay or overwrite) of running configuration with tftp, ftp, scp, tunnel.
    • Test failure conditions (bad password, bad NAT address, dead tftp/ftp server, etc).
    • Verify ability to deploy a template.
    • Verify ability to deploy an ad-hoc template.
    • Change banner (multiline if possible) and verify successful deploy with new config and discrepancies produced.
    • Change the prompt (usually by changing the hostname) and verify whether the prompt changes and this is handled properly.
    • Attempt to deploy a template with syntax errors, verify errors detected.
    • Test stop on error for tunneled mode.
    • Test whether tunneled deploy detects that config mode has been exited and re-enters config mode.
    • Test whether logout gets out of config mode and logs out cleanly if a tunneled deploy runs into <error> tag while in config mode.
    • Test tunneled deploy where config mode allows programs to be run (like ping or tcpdump) that take too long and cause response timeouts. Verify logout kills any running program and does a complete logout (no response timeouts).
  9. Reboot
    • Verify successful reboot with re-connection and snapshots with ssh2 and telnet.
    • Test reboot with both uncommitted changes and no uncommitted changes.
    • Test reboot with another user logged in (may generate extra prompt).
    • Set "commit before reboot" if such a device option is available.
  10. Commit
    • Verify successful commit.
    • Verify commit of all contexts versus active context.
  11. Syntax Scan
    • Copy a full configuration into a template and syntax scan the template.
    • Create a template with errors to syntax scan; verify errors are detected and displayed cleanly.
  12. Telnet/SSH Session
    • Verify successful logon and completion of a series of commands using ssh2 and telnet.
    • Verify you are dropped into non-privileged mode on initial connection.
    • Verify telnet connection prompts you to enter username and password (no automatic login using device security profile).
  13. SSH Proxy
    • ssh -p 4000 -l sysadmin bnaServerAddress
    • connect deviceName
    • connect -prompt deviceName
    • connect -non-priv deviceName
    • Verify successful login and transcript is correctly recorded.
    • Verify login using ssh2 and telnet.
  14. TACACS+
    • Verify successful span action command using TACACS+ login using ssh2 and telnet.
    • Verify SSH Proxy login.
  15. Radius
    • Verify successful span action command using Radius login using ssh2 and telnet.
    • Verify SSH Proxy login.
  16. Syslog
    • Configure the device to send configuration change syslog messages to the BMC Network Automation syslog server (per device agent).
    • Make manual change to the device to generate the syslog message.
    • Verify BMC Network Automation logged an external event for the received syslog message.
  17. Common Custom Actions
    • Get System Serial Number – verify correct serial number is extracted into result.pbid.
    • Ping – verify successful ping and failed ping to bogus IP address.
    • Traceroute – verify successful traceroute and failed traceroute to bogus IP address.
    • Show text – verify correct and failed tests with different "show" commands.
  18. OS Image Snapshot
    • Verify successful snapshot with tftp, ftp, scp.
    • Verify discover-core and discover-image-core data is pulled out correctly.
    • Verify file saved into the OS image library is the same as currently running image file on the device.
    • Test failure conditions (bad password, bad NAT address, dead tftp/ftp server, etc).
    • Test snapshot to remote file server with tftp, ftp, scp; verify proper file naming (file on remote file server named same as file on the device).
  19. OS Image Deploy
    • Verify successful deploy with tftp, ftp, scp.
    • Verify discover-core and discover-image-core data is pulled out correctly.
    • If device can store multiple image files, test delete options for "delete always", "delete never", and "only when free space required".
    • Test option for reboot and do not reboot.
    • Test failure conditions (bad password, bad NAT address, dead tftp/ftp server, etc).
    • Test failed deploy – image file larger than the available space.
    • Test failed deploy – send a file that is not an image binary file or is an image from another type of device.
    • Test deploy from remote file server with tftp, ftp, scp.

Back to top

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

Comments