Device type header XML element reference

(Required) A globally unique ID (GUID)

Run the create_guid.sh or create_guid.bat script in the BCAN_HOME\tools directory to generate a new GUID for use here.

(Required) Name of the device type, up to 255 characters in length

This name appears on the GUI and must be unique across all device types. BMC recommends that you include the name of the vendor in the name of the device type, to help identify the device type in the GUI.

GUID of the device type that acts as a managing system to devices of this type. That is, if some operations are performed directly on the device while other operations must pass through a parent managing device, then fill in this GUID. For example, a Cisco Nexus device may be managed by a Cisco VNMC Virtual Appliance.

true or false to indicate if the standard differencing algorithm is to be used when comparing a configuration against a template

If templates that are pushed to this type of device can contain snippets or small parts of the full configuration, then this flag should be set to false to generate better side-by-side difference reports. If templates pushed to the device must contain a complete configuration, then set this flag to true, again to generate better difference reports.

true or false to indicate if devices can be accessed via the Telnet protocol. When true, only <interaction> elements should be used in device commands to send CLI commands and read responses.

Default value is true.

String containing the name of a pseudo terminal to use in SSH connections.

Some types of devices require a pseudo terminal to make interactions work. If you are able to send commands but fail to read any responses, a pseudo terminal may fix the issue. Some commonly recognized pseudo terminals are vt100, ansi, and dumb.

String containing the name of a pseudo terminal to be used in Telnet connections.

Some types of devices require a pseudo terminal to make interactions work. If you are able to send commands but fail to read any responses, a pseudo terminal might fix the issue. Some commonly recognized pseudo terminals are vt100, ansi, and dumb.

Number indicating the width of the terminal to use in SSH connections, defaulting to 80

Most devices allow the terminal width to be set to unlimited, which should be done explicitly during the login <deviceCommand>, as word wrapping can interfere with parsing device responses or with contents of configurations captured from the screen in tunneled mode. If the width cannot be made unlimited, setting the terminal width to a higher value can alleviate word wrapping problems.

Number indicating the width of the terminal to use in Telnet connections, defaulting to 80

Most devices allow the terminal width to be set to unlimited, which should be done explicitly during the login <deviceCommand>, as word wrapping can interfere with parsing device responses or with contents of configurations captured from the screen in tunneled mode. If the width cannot be made unlimited, setting the terminal width to a higher value can alleviate word wrapping problems.

true or false to indicate if configuration snapshot or deploy or both can be performed using tunneled mode (which avoids using any file transfer protocol)

When true, you must implement the tunneled support in the applicable <deviceCommand> or <httpDeviceCommand> sections, depending on what the device is capable of. For example, for a tunneled mode snapshot, the device must support display of the configuration to the screen, or reporting it in an HTTP response. For a tunneled mode deploy, the device must support line-by-line configuration command entry.

When using file transfer, specifies the filename extension for temporary files sent to or received from the device

Normally, temporary files are named with a .tmp extension, but some devices only produce or allow files named with a specific extension (such as .zip). This extension replaces normal .tmp extension. You should include the dot to make it a true extension. Note that this does not apply to operating system image files, but only to configuration files.

true or false to indicate if the filename extension should be included in any filename argument of file transfer commands

When false, the complete filename is used. When true, only the base name (without the extension) is used.

true or false to indicate if the TFTP protocol is supported to send and receive files

Default value is true.

true or false to indicate whether the device reboots automatically after a configuration is restored (such as via a Deploy To Stored action).

When true, this tells the system to wait for the reboot to complete and to re-login before taking the trailing configuration snapshot(s) which reflect the deployed changes.

Number of seconds to wait to allow the device to reboot.

Once the system issues the reboot (or more precisely, completes the interactions in the reboot <deviceCommand> or <httpDeviceCommand>), it tries to connect and login to the device to obtain the current configurations. To prevent the connection or login from failing because the device is not yet done booting, this sleep value can be increased.

true or false to indicate that during a reboot, the device prompts you to save any unsaved changes

This setting affects the GUI only. It helps validate the selected Reboot Options in the Reboot and Deploy OS Image actions.

String to send to the device when the device seems to be stuck waiting for input and has not emitted any response.

If the system sends a command and does not receive a response within a timeout, the entire action can be flagged as failed. There are rare instances where sending certain commands can cause the device to go off processing and it misses reading a trailing carriage return or a line feed. The device acts as if the system neglected to send it the complete end-of-line sequence. Using this element, you can have the system send out another end-of-line sequence or a control-C or whatever will trigger the device back into its normal CLI processing without causing any error.

You may specify non-printable characters using \xnnn notation, where nnn is the numeric value for the character (for instance, \x003 is the control-C character).

true or false to indicate that this type of device supports multiple security contexts or other multiple virtual components (such as virtual routers or VRFs or VDOMs)

When true, the system augments the device edit page to allow you to specify security context fields, and those selections are passed into the XML processing as properties (which can be used to switch contexts and the like).

true or false to indicate if a configuration can be deployed to the device in tunneled mode

When true, indicates that configurations contain line-by-line commands that can be understood by the device individually when pushed in tunneled mode. When false, configurations cannot be deployed in tunneled mode, but templates can be (presuming a different syntax is used in templates versus configurations).

Default value is true.

String containing the name of the security context (or other virtual component) where other contexts can be created

This is relevant only to CLM container management.

true or false to indicate if the current operating system image file can be deleted prior to a new operating system image file being deployed

Set this to true when the image management is done in discrete steps, one of which is to delete the current image to make space for the new image.

true or false to indicate if the adapter code includes logic to login through a terminal server (which typically requires extra interactions directed at a terminal server to connect to the right serial port connected to the device's console port, followed by the device's console login interactions)

When true, the system uses the device security profile Managed By Terminal Server setting to pass the extra credentials as properties into the XML code. When you connect to the console port via terminal server, only tunneled mode can be used. You should implement tunneled snapshot as a minimum to make such a connection useful. Image management is not possible while implementing tunneled snapshot.

String containing a regular expression that matches an operating system image filename where the file contains an archive-style of image

Some devices support deployment of an image bundled into a tar archive, which requires the use of different commands. The filename of the image being deployed is used to control which commands are issued, based on whether the filename matches this element or not. The %imageArchive% property is set to true when a filename matches this regular expression, which can then be used by the XML code to execute the right set of commands.

String containing one or more characters, enclosed in square brackets, that are not allowed to be used in port type names in the CLM container management environment

The system automatically removes any such characters from port type names.

true or false to indicate if an operating system image file is always to be deployed using the original name of the file

Normally, the system deploys files using its own temporary filenames. But a device might reject files whose names do not conform to its operating system image file naming conventions, so setting this to true uses the filename of the file that was loaded into the system (either into the OS image library or into the Deploy OS Image action).

true or false to indicate that prior to deploying an operating system image, the system should verify that the new image file(s) will fit into the free space on their target file system(s)

The system always checks for fit into total size, but this element adds a check on free size. This element should be set to true only for device types that have a distinct file-copy step that precedes the image-installation step. (Most devices combine download and install into a single command that does its own file management, where a check on total size is sufficient). Device type also needs to have fully-implemented discover-image-details that reports the used, free, and total space, or this flag has no effect.

String containing the full class name of the Java code that performs the operating system image management functions.

This effectively limits user implementation of image management, since only the factory-installed Java code is available for reference here. However, if a device supports the installation of an image through a single command that downloads, validates, and installs an image file, then you might be able to use the class com.bmc.bcan.engine.network.devices.SimpleNonrecoveringImageLoader here. As its name implies, it has minimal logic and does not recover the old image on errors (the device is presumed to preserve its original image automatically). This class is used by the factory-installed device types, such as Cisco Nexus, Juniper JunOS, Dell PowerConnect, and others, which you might refer to as examples of image management.

<supportedFileSystems>

<fileSystem>

String containing the name of a filesystem where operating system image files can reside

When deploying an operating system image, the selected Target Image Filesystem must be one of the listed values, or Default is also acceptable.

<osImageInformation>

<osImageType order="0" name="" primary="false">


Defines what operating system image files are supported by the device, especially when multiple files make up the running image.

Leave this element out when devices of this type manage their images as a single file, or when the command to deploy an image file does not vary based on the contents of the file. When multiple files are supported and must be identified to the device in the image deployment commands (as they are in Cisco Nexus), then define multiple <imageType> elements, with one being flagged with primary="true". This element contains the following attributes:

• order: Number indicating where this image type appears among the other image types for this device type. It is used in the GUI to order the file selection controls. Used by the system to form the image name (associated with a device or a configuration), where the displayed name is made up of one part per image type in order.
• name: String that identifies the image file.
• primary: true or false to indicate that this is the primary image, which appears first regardless of the value of order.

String containing the full class name of the Java code that performs the hardware inventory management functions

This element effectively limits user implementation of hardware inventory management, since only the factory-installed Java code is available for reference here.

String containing what functions (to be used in the ${eval} substitution parameter resolution) generate properly-encrypted passwords

This documentation helps you develop rules that verify passwords are set to expected values, where those values are encrypted.

String containing instructions to help you create acceptable templates

Use a CDATA tag to enclose HTML elements that formats this information for display in the Device Adapter Capabilities report. Refer to Common concepts and XML elements for the CDATA tag.

String containing general notes, caveats, quirks, or anything else special about this type of device that might affect how users manage them

Use a CDATA tag to enclose HTML elements that formats this information for display in the Device Adapter Capabilities report. Refer to Common concepts and XML elements for the CDATA tag.

String containing the full class name of the Java code that performs virtual firewall functions in CLM container management

This element effectively limits user implementation of virtual firewall management, since only the factory-installed Java code is available for reference here.

<snmpOids>

<snmpOid category="">

String containing an SNMP OID that maps to a device of this type (usually the sysObjectID in the system MIB)

Used when importing devices from an external system that is aware of the device's OID, to assign this device type to the imported device. The <snmpOid> element contains the following attribute:

• category: Number that identifies the device category (router, switch, etc), from the <id> values in the CategoryMap.xml file. When importing devices, the device's category is set to this value, which is validated against what is in CategoryMap.xml.

<supportedConfigurationTrailDeclarations>

<supportedConfigurationTrailDeclaration>

<guid>

<format>

<capturesDecoded>

<decoderClass OS="">

<backupCommandGuid>

<mergeCommandGuid>

<restoreCommandGuid>

Specifies that devices of this type support snapshot (and optionally deploy) of the specified configuration

The <supportedConfigurationTrailDeclaration> element can contain the following child elements:

• <guid>: (Required) String containing the GUID of the configuration trail
• <format>: String containing either ascii or binary, indicating the contents of the configuration. An ASCII configuration is displayable; a binary configuration is not, unless it is decoded.
• <capturesDecoded>: true or false to indicate if a decoded version of a binary configuration is available by capturing the output of running a command (such as a show command). The command must populate a property called decodedContents.
• <decoderClass>: String containing the full class name of the Java code that performs the decoding of a binary configuration. You might add new decoders that you have written in Java by placing your jar files into the BCAN_DATA\endorsed\lib directory.
• <backupCommandGuid>: (Required) GUID of the <deviceCommand> or <httpDeviceCommand> that implements snapshot or backup of this configuration. This GUID should be unique among all the command GUIDs for the supported trails in this device type. If necessary, generate a new GUID by running the create_guid.sh or create_guid.bat script in the BCAN_HOME\tools directory. Then use this new GUID in your <deviceCommand> or <httpDeviceCommand>.
• <mergeCommandGuid>: GUID of the <deviceCommand> or <httpDeviceCommand> that implements deployment of this configuration into the device's active settings. Similar to the backup GUID, it must be unique among the command GUIDs for this device type.
• <restoreCommandGuid>: GUID of the <deviceCommand> or <httpDeviceCommand> that implements deployment of this configuration into the device's stored settings. Similar to the backup GUID, it must be unique among the command GUIDs for this device type.

<commentLines>

<line scope="" context="global" caseSensitive="false">

String containing a regular expression that matches configuration lines that should be treated as comments

Comments are ignored when looking for changes, so comments cause no discrepancies to be flagged, nor do they cause new configurations to be added to the trail of previous versions of the configuration. The <line> element contains the following attributes:

• scope: String containing a comma-separated pair of trail GUIDs to limit when the line is a comment. When specified, the line is treated as a comment only when comparing a configuration of the first trail against a configuration of the second trail. For example, some devices represent some setting one way in the running configuration and a different way in the startup configuration. You can ignore the difference when comparing running versus startup (to avoid a discrepancy), but continue to monitor the setting when comparing running versus running and startup versus startup.
• context: One of global, compliancy, discrepancy, parser, or matcher, indicating at what processing steps, this line should be treated as a comment (and not treated as a comment at all other times).
  • global: Comment applies all the time.
  • compliancy: Comment applies only when performing compliance rule violation checks.
  • discrepancy: Comment applies only when looking for running versus startup discrepancies.
  • parser: Comment applies only when parsing a configuration, as done during smart merge and tunneled merge.
  • matcher: Comment applies only when comparing a configuration with a template, to display a difference report.
• caseSensitive: true or false to indicate if the regular expression matching should be case sensitive or not.

<commentBlocks>

<block scope="" context="global" caseSensitive="false">


<begin inclusive="false">

<end inclusive="false">

<include>

<exclude>

<mask invert="false">

Specifies that multiple consecutive lines of a configuration be treated as comments, delimited by begin and end lines. The scope, context, and caseSensitive attributes behave the same as described in <commentLines>. The <block> element contains the following child elements:

• <begin>: (Required) Regular expression that matches the line which starts the block. The inclusive flag controls whether this line is part of the comments or not.
• <end>: (Required) Regular expression that matches the line which ends the block. The inclusive flag controls whether this line is part of the comments or not.
• <include>: Regular expression to match a line that must be present inside a block for the block to be treated as a comment.
• <exclude>: Regular expression to match a line that must not be present inside a block for the block to be treated as a comment. This takes precedence over <include> (that is, if a line matches both, the block is excluded from being a comment).
• <mask>: Regular expression indicating which lines inside the block are to be treated as comments. When not present, all lines are comments. When present, only matching lines are comments. The invert flag set to true makes only non-matching lines into comments.

<disregardLeadingWord>

<word>

String that should be ignored when it appears at the start of a configuration line

Used when comparing a configuration against a template, to generate more usable difference reports (for example, to align set and clear versions of the same parameters).

<sortedCommands>

<line type="single" caseSensitive="false" trails="" parentBlockPattern="" order="ascending" makeContiguous="false">

String containing a regular expression that matches command lines in a configuration that should be sorted prior to the configuration being checked for changes or discrepancies, where ordering of lines has no significance at all and the device is prone to re-order lines randomly (causing spurious differences)

The system pulls out all the lines that match, sorts them, and then re-inserts them into the configuration in the new order. The scope of the sorting is limited to the lines that match one <line> definition.

Sorting of blocks and negated lists is limited to device types that support Smart Merge, which is not user-extensible. The <line> element contains the following attributes:

• type: One of the following values, indicating how many lines are grouped together into a logical unit before sorting those units:
  • single: The regular expression is to match a standalone command line.
  • blockMember: The regular expression is to match a standalone command line found inside blocks defined by parentBlockPattern. Lines within the same block are sorted among themselves.
  • block: The regular expression is to match a block header; the sorting treats the header and its contained lines as one unit.
  • negatedList: The regular expression is to match command lines that stand alone, but that together define a single component (such as an access control list); the sorting treats the lines defining the single component together as one unit. Negated lists are defined through smart merge, so what is considered to be a negated list is not exposed to end users.
• caseSensitive: true or false to indicate if the regular expression matching should be case sensitive or not.
• trails: Defines which trails contain the commands to be sorted, as a comma-separated sequence of configuration trail GUIDs. If not specified, then all trails supported by this device type are searched.
• parentBlockPattern: When type is blockMember, specifies a regular expression for finding the blocks that contain the lines to be sorted.
• order: One of ascending or descending, for the direction of the sorting. Default is ascending order.
• makeContiguous: When type is single, true or false to indicate how the sorted lines are to be re-inserted into the configuration. When false, the lines are put back into the empty spaces left when they were removed. When true, all of the lines are re-inserted at the point where the first one had originally appeared.

<sortedParameters>

<sortedParameter>

<command>

<format>

<numberParamsInGroup>

Specifies command line parameters or arguments that should be sorted within the line prior to the configuration being checked for changes or discrepancies, where the order of the parameters is not relevant and the device is prone to re-order those parameters randomly. The parameters must be separated by a space. The <sortedParameter> element can contain the following child elements:

• <command>: (Required) Regular expression for locating the command lines whose parameters need to be sorted. Matching is case insensitive.
• <format>: (Required) Defines how to parse the command line to find the parameters. The last group indicates the parameters.
• <numberParamsInGroup>: (Required) Number indicating how many parameters make up a sortable unit.

<configProcessors>

<textProcessor search="" replace="" incoming="false" outgoing="false" fileTransfer="false" tunneledTransfer="false" trails="" delegateClassName="">

Specifies how text in a configuration or a template should be altered.

This element applies only to ASCII configurations (not to binary ones). For both search and replace attributes, you can specify non-printable characters using \xnnn notation, where nnn is the numeric value for the character (for instance, \x003 is the control-C character). The textProcessor element contains the following attributes:

• search: (Required) String containing a regular expression to match text to be removed from the configuration.
• replace: String containing the text to be inserted as a replacement. If not specified, search string is removed.
• incoming: true or false to indicate if the replacement is to be done in configurations coming from the device.
• outgoing: true or false to indicate if the replacement is to be done in configurations or templates being sent to the device.
• fileTransfer: true or false to indicate if the replacement is to be done in configurations or templates being transferred using a file transfer protocol.
• tunneledTransfer: true or false to indicate if the replacement is to be done in configurations or templates being sent to or received from the device using tunneled mode.
• trails: Defines which trails contain the text to be altered, as a comma-separated sequence of configuration trail GUIDs. If not specified, then all trails supported by this device type are searched.
• NEW IN 8.9.02delegateClassName: Fully-qualified name of a Java class that can be used to process text. When populated, this attribute is used instead of the search and replace attributes, and configuration text is passed to a method named process in the specified class, for it to use the custom text processing logic, returning the processed string as the result.
  Note: The indentation through this attribute introduces some discrepancies when comparing configuration files generated after version 8.9.02 against those generated before. If you want to avoid discrepancies, revert to the text processor included in earlier versions. For more information, see Avoiding discrepancies due to updated text processor in version 8.9.02. However, BMC recommends to mark the 8.9.02 configuration as the trusted configuration.

<sensitiveLines>

<line>

String containing a regular expression (case-insensitive) that identifies a command line that contains sensitive data

The system exposes sensitive data only to users with the sensitive data right. Sensitive data is found in configurations, templates, rules, transcripts, and reports. In the regular expression, use parentheses around the sensitive parts of the command; the system masks these parts of the line when displayed to a non-privileged user.

<responseBlockDeclarations>

<responseBlockDeclaration name="">

<response property="" value="">

<errorBlockDeclarations>

<errorBlockDeclaration name="">

<error property="" retry="false">