Creating the top_manifest.xml File

top_manifest.xml is the primary plugin file used directly by SecureTrack. It defines values for SecureTrack, such as the Data Retrieval executable, plugin metadata, error messages, and the icon file, and defines parameters to be used by the Data Retrieval executable.

The following is an example top_manifest.xml file:

The above example can be copied from here to be used as a template file. The XML Schema is documented in the schema.htm file included in the TOP Developer's Package.

The top_manifest.xml file must consist of valid XML, and must contain the following sections, under the root <plugin> tag:

• Plugin information: The following four mandatory tags. SecureTrack displays these tags' values in the list of installed plugins:
  • <name>: A name for the plugin, which must be unique when installed in SecureTrack. Tufin recommends the following naming convention:

    <name>Plugin.contributor.device_vendor.device_model</name>

  • <version>: A version number for the plugin, which should be incremented upon changes to the plugin. The version number must be in the form major.minor .

    For example:

    <version>1.0</version>

  • <vendor>: The device vendor, such as Blue Coat or F5, with no spaces in the name. This name appears in the device tree in Compare view and in the Devices page.

    For example:

    <vendor>Blue_Coat</vendor>

  • <model>: The device type. This text will also appear in the SecureTrack device tree in Compare view and in the Devices page.

    For example:

    <model>ProxySG</model>

• Data retrieval information: This section is delimited by the <data-retriever> tag. It contains the following tags:
  • <command> (mandatory): The filename of the main Data Retrieval executable, relative to the tar archive root. For example, if the executable is called configuration_retriever, and is under an "exe" directory in the archive:

    <command>exe/configuration_retriever</command>

  • <protocols> (mandatory): A <protocol> tag for each protocol that can be used for connecting to the device. SSH and Telnet are currently supported.

    If more than one <protocol> tag are included, then when adding a device to SecureTrack, the user will select which to use for the specific device.

    For example:

    <protocols>

    <protocol>ssh</protocol>

    <protocol>telnet</protocol>

    </protocols>

  • <command-line> and/or <standard-input> (optional): Parameters to be passed to the Data Retrieval executable. These parameters pass values defined in SecureTrack to the executable. SecureTrack passes multiple standard-input parameters separated by ASCII LF (0x0A).

    There are six available optional parameters, each of which can be passed via command line or via standard input. It is recommended for sensitive information (such as password, enable password) to be passed via standard input rather than command line.

    The command line parameters section is delimited by the <command-line> tag; the standard input section - by the <standard-input> tag. Within each of the two categories (command line and standard input), parameters will be passed in the order they are defined.

    Each parameter is delimited by the <param> tag, and contains a <value> tag, which contains a variable prefixed with the $ sign. The <value> tag may be preceded by a <key> tag, to pass a relevant flag to the executable, as required by the executable. For example:

    <param>

    <key>-t<key>

    <value>$timeout</value>

    </param>

    The six available parameters are:

    • Connection protocol: Where the protocol is selected per device when adding the device in SecureTrack, define this parameter, as follows:

      <param>

      <value>$protocol</value>

      </param>

    • Device IP address: Use the $ip-address variable, which will be resolved to the IP address configured in SecureTrack per device:

      <param>

      <value>$ip-address</value>

      </param>

    • Username for SecureTrack to log into the device: Use the $username variable:

      <param>

      <value>$username</value>

      </param>

    • Timeout: How long SecureTrack will wait for a response from device before continuing, as configured in SecureTrack's Timing page. Use the $timeout variable:

      <param>

      <value>$timeout</value>

      </param>

    • Device authentication password: Use the $password variable:

      <param>

      <value>$password</value>

      </param>

    • Device authentication enable password: A second password required by some devices. Where relevant, use the $enable-password variable:

      <param>

      <value>$enable-password</value>

      </param>

The following sections are optional:

• <error_codes> (note the plural: codes): Defines error messages to be displayed in SecureTrack's Status page (and in st status output).

  This section is delimited by the <error_codes> tag (note the plural: codes), and contains an <error_code> (note the singular: code) tag for each error code that can be returned by the Data Retrieval executable.

  Error code 0 is reserved for success, and should not be defined here. It is also recommended not to use error code 1, which is a default error code in many script shells.

  Each <error_code> tag contains:

  • A <code> tag, containing an error code that can be generated by the Data Retrieval executable, and
  • A <description> tag, containing the corresponding error message that should be displayed by SecureTrack.

  For example:

  <error_codes>

  <error_code>

  <code>2</code>

  <description>Invalid Number of Parameters</description>

  </error_code>

  <error_code>

  <code>3</code>

  <description>Connection Timeout</description>

  </error_code>

  ...

  </error_codes>

• <representation>: Contains the <icon> tag, which defines an icon graphic file. SecureTrack displays the monitored device with this icon, in Compare view, Devices page, and Status page. This graphic must be a 16x16 GIF, and is recommended to be transparent. If no icon file is supplied, SecureTrack uses a default TOP icon.

  For example:

  <representation>

  <icon>icon.gif</icon>

  </representation>