Adapter request and response for a Kerberized SSH adapter for a local client

The Kerberized SSH adapter does not use an action. You must leave the adapter's Action field blank when configuring the Activity properties for a Call Adapter Activity in BMC Atrium Orchestrator Development Studio.

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. Partial information cannot be retrieved from the configuration node.

You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

When you use a context item as an input for an adapter request, you must enclose the adapter request in the <request-data> elements. However, when you create a static request, <request-data> is not required and the adapter request starts with the <adapterName-adapter-request> element.

BMC recommends that you do not include unused elements in the adapter request because they might cause errors.

The following table describes the elements of the Kerberized SSH adapter request with a local client.

Elements of the Kerberized SSH adapter request for a local client

Element	Description	Required
`<prompts>`	Contains additional `<prompt>` elements that might be needed to execute commands properly Note: This prompt indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues.	Conditional; required when one or more `<prompt>` elements are defined
`<prompt>`	Displays the console prompt when the system is waiting for a command A `name` attribute specifies the `<prompt>` value in a `<command>` element. In the absence of a value for this element, the `<prompt>` defined in the configuration node or the dynamic target is used.	No
`<verify-os>`	Determines whether the adapter must determine the target OS type soon after authentication is complete or a connection is established Valid values: true (default), false If the value of the `<verify-os>` element is true, the type of OS is verified and the exit codes are returned by the executed commands. If the value of the `<verify-os>` element is false, the type of OS is not verified and none of the commands executed return an exit code.	No
`<targets>`	Contains the `<target>` elements	Conditional; required if a target is referenced or defined in the request
`<target>`	Contains a `name` attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target If this value is not provided, the default target in the adapter configuration is used.	Conditional; required if a target is referenced or defined in the request
`<host>`	Specifies the host name or the IP address of the remote host This element applies to a dynamic target.	Conditional; required when defining a dynamic target
`<port>`	Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22	No
`<ktgt-cache-file-name>`	Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT)	Yes
`<ssh-command>`	Specifies the location of the SSH client executable This value is typically not defined. The SSH client executable is most commonly located in a directory specified in the PATH environment variable. This value is needed only when the executable is aliased or present in a non-standard location. Default value: ssh	No
`<ssh-options>`	Contains one or more `<ssh-option>` elements	Conditional; required when one or more `<ssh-option>` elements are defined
`<ssh-option>`	Specifies an available SSH option Note: Refer to the Man pages for the SSH client executable to obtain a list of all possible options. The sample values are: GSSAPIAuthentication=yes GSSAPIDelegateCredentials=yes	No
`<ssh-arguments>`	Contains one or more `<ssh-argument>` elements	Conditional; required when one or more `<ssh-argument>` elements are defined
`<ssh-argument>`	Specifies an available SSH argument The sample values are: -t, -v If a prompt is specified in the configuration or the request, -t,-t must be provided as the argument. This informs the SSH server to open a pseudo terminal session, which is required for the successful execution of prompt-based requests. Note: Multiple arguments can be provided in a single element or multiple elements can be defined, each with a single argument. If multiple arguments are provided in a single element, the arguments must be separated by a space. Refer to the Man pages for the SSH client executable to obtain a list of all possible options.	No
`<prompt>`	Displays the console prompt when the system is waiting for a command This element applies to a dynamic target. If this element is not provided, each command is executed in a separate session, as if each was executed in a new command shell. This element indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues.	Conditional; required when using the proxy command feature
`<timeout-secs>`	Specifies the time, in seconds, to wait for the expected prompt to be returned If the expected prompt is not returned before the specified period has elapsed, an error message is returned. This element applies to a dynamic target. Default value: 60 seconds	Conditional
`<establish-connection-timeout-secs>`	Specifies the time, in seconds, to wait for user authentication on the target server If authentication is not successful within this time, an error message is returned. Default value: 60 seconds	No
`<commands>`	Contains the `<command>` elements	Yes
`<command>`	Specifies the command to be executed on the remote host The command must be entered as if it were being keyed at the system prompt.	Yes

The following figure shows an XML sample request for the Kerberized SSH adapter with a local client. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. In this sample, the first target references the adapter configuration and the second target is a dynamic target.

XML sample of the Kerberized SSH adapter request for a local client


<krb-request>
    <prompts>
        <prompt name ="prompt 1">user1-></prompt>
    </prompts>
      <verify-os></verify-os>
    <targets>
    <target name="host1"/>
    <target>
        <host>server2</host>
        <port>2200</port>
        <ktgt-cache-file-name></ktgt-cache-file-name>
        <ssh-command></ssh-command>
        <ssh-options>
            <ssh-option>GSSAPIAuthentication=yes</ssh-option>
        </ssh-options>
        <ssh-arguments>
            <ssh-argument>-t -v</ssh-argument>
        </ssh-arguments>
        <prompt>pr1</prompt>
        <timeout-secs>120</timeout-secs>
        <establish-connection-timeout-secs>90</establish-connection-timeoutsecs>
    </target>
    </targets>
    <commands>
        <command prompt="prompt 1">ls -l</command>
        <command prompt="prompt 1">pwd</command>
    </commands>
</krb-request>

The following table describes the elements of a Kerberized SSH adapter response to a request with a local client.

Elements of a Kerberized SSH adapter response for a local client

Element	Description
`<request-metadata>`	Contains the request level summary information
`<status>`	Indicates the status of the request Valid values: success, error.
`<error>`	Indicates the error message returned when the value of the `<status>` element is error When the value of the `<status>` element is success, this element is absent.
`<targets-output>`	Contains the command output for all the targets
`<target-output>`	Contains the command output for a specific target The host attribute provides the host name or the IP address of the target computer.
`<target-metadata>`	Contains the target level summary information
`<os-id>`	Indicates the operating system type of the target
`<os-version>`	Indicates the operating system version of the target
`<os-arch>`	Indicates the architecture of the target system This element is absent if the target system does not have a defined architecture.
`<status>`	Indicates the status of the target connection Valid values: success, error
`<error>`	Contains the error message if a target level error occurs When the value of the `<status>` element is success, this element is absent.
`<commands-output>`	Contains the command responses for all the commands executed on the target computer
`<command-output>`	Contains the command response for a specific command
`<metadata>`	Contains the command summary information
`<command>`	Specifies the command executed
`<line-count>`	Specifies the number of lines returned by the command
`<execution-milliseconds>`	Specifies the duration of the command execution, in milliseconds
`<exit-code>`	Specifies the exit code returned by the target after the command is executed A successful execution returns a value of 0. An unsuccessful execution returns a nonzero value. If the exit code is not obtained, a value of 9999 is returned by default. Note: If the value returned for the <exit-code> is not 0 or 9999, the value of the `<status>` element is error, and an `<error>` element is present in the response.
`<status>`	Indicates the status of the command execution Valid values: success, error
`<error>`	Contains the error message if the execution of the command is interrupted When the value of the `<status>` element is success, this element is absent.
`<output>`	Contains the lines that result from the command
`<line>`	Specifies the output resulting from the command The index attribute indicates the sequence in which the line is returned. This can contain a response returned when the `<exit-code>` is nonzero.

The following figure illustrates the adapter response for the Kerberized SSH adapter with a local client.

XML sample of the Kerberized SSH adapter response for a local client


<kerberos-ssh-command-output>
   <request-metadata>
     <status>success</status>
   </request-metadata>
   <targets-output>
   <target-output host="server1">
     <target-metadata>
       <os-id>Linux</os-id>
       <os-version>2.6.12-1.1381_FC3smp</os-version>
       <status>success</status>
     </target-metadata>		
   <commands-output>
     <command-output>
     <metadata>
       <command>first command executed</command>
       <line-count>2</line-count>
       <execution-milliseconds>value</execution-milliseconds>
       <exit-code>0</exit-code>
       <status>success</status>
     </metadata>
   <output>
     <line index="1">line 1</line>
     <line index="2">line 2</line>
   </output>
     </command-output>
   <command-output>
   <metadata>
     <command>second command executed</command>
     <line-count>1</line-count>
     <execution-milliseconds>value</execution-milliseconds>
     <exit-code>0</exit-code>
     <status>success</status>
   </metadata>
   <output>
     <line index="1">line 1</line>
   </output>		
   </command-output>
   </commands-output>
   </target-output>
   </targets-output>
</kerberos-ssh-command-output>

Adapter request and response for a Kerberized SSH adapter for a local client

Comments