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. You cannot retrieve partial information from the configuration node.
You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the adapter uses the default target from the adapter configuration. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors.
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.
The following table describes the elements of a Telnet adapter request.
| | |
|---|
| Contains additional <prompt> elements that are needed to execute commands properly | Conditional; required when a <prompt> element is is defined |
| Displays the console promptwhenthe system is waiting for a command
The name attribute of the <prompt> element specifies the value in a <command> element.
The <prompt> element indicates the completion of command execution. It must be unique to prevent parsing issues; it must not match potential command output.
If you do not specify this element, the adapter uses <prompt> defined in the configuration node or the dynamic target. | |
<target-os-type-verification> | Specifies whether to verify the operating system used and retrieves the type of the operating system.
Valid values: true (default), false Note: This element can only be used as a dynamic target, which means that you can specify the element in the adapter request. The <target-os-type-verification> element cannot be used in a FAT command. | |
| Contains the <target> elements | Conditional; required if a <target> is referenced or defined in the request |
| Contains a name attribute that references a configuration node from the adapter configuration or contains the elements that define a dynamic target
If not specified, the adapter uses the default target in the adapter configuration. | Conditional; required if a target is referenced or defined in the request |
| Specifies the host name or the IP address of the remote host
This element applies to a dynamic target. WarningNote You can specify an IPv6 address with a zone ID for the <host> element in the adapter requests—for example,<host>fe80::20c:29ff:fe5d:38f0%eth0</host>.
To find the zone ID of the required computer, see Zone ID for an IPv6 address. | Conditional; required for defining a dynamic target |
| Specifies the port on which the remote host listens
This element applies to a dynamic target.
Default value: 23 | |
| Specifies the user name for remote host authentication
This element applies to a dynamic target. | Conditional; depends on your environment requirements |
| Specifies the password that corresponds to the <user-name> provided or that is used for remote host authentication
This element applies to a dynamic target.
This element can contain an encryption-type attribute. | Conditional; depends on your environment requirements |
| Indicates whether the password specifiedisencrypted; is an attribute of the<password> element, not an element itself
Valid values: Base64, Plain (default) | |
| Specifies the console prompt displayed when the system is waiting for a command
This prompt indicates the completion of command execution. It must be unique to prevent parsing issues, not matching potential command output. | Conditional; required when defining a dynamic target |
| Specifies the time, in seconds, to wait for the expected prompt to return before displaying an error message
This element applies to a dynamic target.
Default value: 60 seconds | |
| Displays the console promptwhenthe system is waiting for a user name
This element applies to a dynamic target.
Default value: login | |
| Displays the console promptwhenthe system is waiting for a password
This element applies to a dynamic target.
Default value: Password | |
| Contains the <command> elements ErrorWarning Specify either the <command> or <commands> element. Do not use both the elements in the same adapter request. | |
| Specifies the commands to be executed on the remote host
You can specify a prompt for the command using the prompt name attribute (specified in <prompt>) or by using the prompt attribute in the <command>element. See XML sample of the Telnet adapter request. WarningNote The <command> element can contain the read-buffer-size attribute, which specifies the buffer size, in bytes, that will be used to read from I/O streams. This value takes precedence over the value set in the dynamic target or in the adapter configuration. Also, the value set for read-buffer-size in the dynamic target takes precedence over the value set in the adapter configuration. ErrorWarning Specify either the <command> or <commands> element. Do not use both the elements in the same adapter request. | |
| Informs the adapter I/O stream reader whether to expect a command echo in the adapter response; is an attribute of the <command> element, not an element itself
Set <expect-command-echo> to true to remove the command echo from the adapter response.
Valid values: true (default), false | |
<connection-initialize-command> | Enables you to run a command to change the prompt as the first command after the session is opened
This element is supported only for a named connection (persistent connectivity). You can specify any command to be executed while initializing the connection. | |
| Specifies the supporting CharSet
Also called character set, it includes identifiers describing a series of universal characters. | |
| Specifies the buffer size, in bytes, that will be used to read from I/O streams
Default value: 1024 | |
| Specifies whether to enable the SSL communication mode for the adapter
Valid values: true, false (default) WarningNote During an SSL communication, the Telnet adapter does not validate the authenticity of the server's certificate. | |
Sample XML adapter request when <verify-os> is set to false
<telnet-request>
<prompts>
<prompt name="prompt">></prompt>
</prompts>
<targets>
<target name="">
<host>vw-pun-xyz</host>
<port>23</port>
<userName>Administrator</userName>
<password>zzzz</password>
<target-os-type-verification>false</target-os-type-verification>
<timeout-secs>60</timeout-secs>
<prompt>></prompt>
<login-prompt>login:</login-prompt>
<password-prompt>password:</password-prompt>
</target>
</targets>
<commands>
<command encryption-type="plain" timeout-secs="60">whoami</command>
</commands>
</telnet-request>
Adapter response when the <verify-os> is set to false
<telnet-command-output>
<metadata>
<status>success</status>
</metadata>
<targets-output>
<target-output host="vw-pun-xyz">
<metadata>
<status>success</status>
</metadata>
<commands-output>
<command-output>
<metadata>
<command>whoami</command>
<line-count>3</line-count>
<execution-milliseconds>109</execution-milliseconds>
<exit-code>9999</exit-code>
<status>success</status>
</metadata>
<output>
<line index="1">vw-pun-xyz\administrator</line>
<line index="2"></line>
<line index="3">C:\Documents and Settings\Administrator></line>
</output>
</command-output>
</commands-output>
</target-output>
</targets-output>
</telnet-command-output>
Adapter response when the <verify-os> is set to true or not specified
<telnet-command-output>
<metadata>
<status>success</status>
</metadata>
<targets-output>
<target-output host="vw-pun-xyz">
<metadata>
<os-id>Windows 2003</os-id>
<os-version>5.2 Build 3790 Service Pack 2</os-version>
<status>success</status>
</metadata>
<commands-output>
<command-output>
<metadata>
<command>whoami</command>
<line-count>3</line-count>
<execution-milliseconds>313</execution-milliseconds>
<exit-code>0</exit-code>
<status>success</status>
</metadata>
<output>
<line index="1">vw-pun-xyz\administrator</line>
<line index="2"></line>
<line index="3">C:\Documents and Settings\Administrator></line>
</output>
</command-output>
</commands-output>
</target-output>
</targets-output>
</telnet-command-output>
The [expand] macro is a standalone macro and it cannot be used inline.
The following figure shows an XML sample of the Telnet adapter request. Use the adapter request XML when you create a custom process by using the Call Adapter activity in TrueSight Orchestration Development Studio. In this case, the first target references the adapter configuration and the second target is a dynamic target.
XML sample of the Telnet adapter request
<telnet-request>
<prompts>
<prompt name="P1">/usr/bin></prompt>
</prompts>
<targets>
<target name="host1"/>
<target>
<host>server3</host>
<port>2300</port>
<user-name>user</user-name>
<password encryption-type-"Plain">test</password>
<prompt>user1$</prompt>
<target-os-type-verification>true</target-os-type-verification>
<timeout-secs>120</timeout-secs>
<login-prompt>user-name:</login-prompt>
<password-prompt>password for user1:</password-prompt>
<target-os-type-verification>true</target-os-type-verification>
<read-buffer-size>1024</read-buffer-size>
<connection>
<name>target1_connection</name>
<terminate-on-exit>false</terminate-on-exit>
<connection-initialize-commands>
<command prompt="%" ignore-response = "true">prompt %</command>
<command prompt="%" ignore-response = "true">cd Cookies</command>
</connection-initialize-commands>
</connection>
</target>
</targets>
<commands>
<command prompt="P1">ls -l</command>
</commands>
</telnet-request>
WarningNote
The command must be entered as if it were being keyed at the system prompt. The adapter appends cmd \c or/bin/sh -c at the beginning of the command as needed.
XML sample of the Telnet adapter with CharSet
<telnet-request>
<targets>
<target>
<host>server1</host>
<user-name>user</user-name>
<password encryption-type-"Plain">test</password>
<prompt>></prompt>
<login-prompt>login:</login-prompt>
<password-prompt>password:</password-prompt>
<target-os-type-verification>true</target-os-type-verification>
<read-buffer-size>1024</read-buffer-size>
<character-set>Shift_JIS</character-set>
</target>
</targets>
<commands>
<command>type testFile.txt</command>
</commands>
</telnet-request>
XML sample of the Telnet adapter request for multiple configurations
<telnet-request>
<targets>
<target name="host2" />
</targets>
<commands>
<command working-dir="/" timeout-secs="2">ls -l</command>
<command timeout-secs="1">pwd</command>
</commands>
</telnet-request>
XML sample of the Telnet adapter request with multiple commands
<telnet-request>
<prompts>
<prompt name="prompt">${Prompt}</prompt>
</prompts>
<targets>
<target name="">
<host>${target1_host}</host>
<userName>${target1_username}</userName>
<password>${target1_password}</password>
<prompt>${Prompt}</prompt>
<login-prompt>${loginprompt}</login-prompt>
<password-prompt>${passwordprompt}</password-prompt>
</target>
</targets>
<commands>
<command>${Command}</command>
<command>${Command1}</command>
</commands>
</telnet-request>
XML sample of the Telnet adapter request with IPv6 support in a Linux to Linux environment
<telnet-request>
<prompts>
<prompt name="prompt">$</prompt>
</prompts>
<targets>
<target name="">
<host>fe80::219:d1ff:fe2f:82e6%eth0</host>
<port>23</port>
<userName>name</userName>
<password encryption-type="plain">name</password>
<timeout-secs>60</timeout-secs>
<prompt>$</prompt>
</target>
</targets>
<commands>
<command encryption-type="plain" timeout-secs="60">ls -l</command>
</commands>
</telnet-request>
XML sample of the Telnet adapter request with IPv6 support in a Windows to Linux environment
<telnet-request>
<targets>
<target>
<host>fe80::219:d1ff:fe2f:82e6%4</host>
<port>23</port>
<userName>name</userName>
<password>name</password>
<prompt>$</prompt>
<login-prompt>login:</login-prompt>
<password-prompt>Password:</password-prompt>
</target>
</targets>
<commands>
<command>hostname</command>
</commands>
</telnet-request>
The [expand] macro is a standalone macro and it cannot be used inline.
The Telnet adapter returns an adapter response containing the details for the command executed by the adapter request. The following table describes the elements of a Telnet adapter response.
The following table describes the output elements of a Telnet adapter response.
| |
|---|
| Contains the request level summary information |
| Indicates the status of the request
Valid values: success, 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. |
| Contains the command output for all the targets |
| Contains the command output for a specific target
The host attribute provides the host name or the IP address of the target. |
| Contains the target level summary information |
| Indicates the operating system type of the target |
| Indicates the operating system version of the target |
| Indicates the architecture of the target system
This element is absent if the target system does not have a defined architecture. |
| Indicates the status of the target connection
Valid values: success, error |
| Contains the error message if a target-level error occurs
When the value of the <status> element is success, this element is absent. |
| Contains the command responses for all the commands executed on the target computer |
| Contains the command response for a specific command |
| Contains the command summary information |
| Specifies the command executed |
| Specifies the number of lines returned by the command |
| Specifies the duration of the command execution, in milliseconds |
| 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 non zero value. If the exit code is not obtained, a value of 9999 is returned by default. 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. |
| Indicates the status of the command execution
Valid values: success, error |
| Contains the error message if the execution of a command is interrupted
When the value of the <status> element is success, this element is absent. |
| Contains the lines resulting from the command |
| Contains 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. |
XML sample of the Telnet adapter response
<telnet-command-output>
<request-metadata>
<status>success</status>
<error>Present only with status of 'error'</error>
</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>
<error>Present only with status of 'error'</error>
</target-metadata>
<commands-output>
<command-output>
<metadata>
<command> command executed </command>
<line-count>1</line-count>
<execution-milliseconds>value</execution-milliseconds>
<exit-code>0</exit-code>
<status>success</status>
<error>Present only with status of 'error'</error>
</metadata>
<output>
<line index="1">line 1</line>
</output>
</command-output>
</commands-output>
</target-output>
</targets-output>
</telnet-command-output>
XML sample of the Telnet adapter response with multiple commands
<telnet-command-output>
<metadata>
<status>success</status>
</metadata>
<targets-output>
<target-output host="10.128.248.114">
<metadata>
<os-id>SunOS</os-id>
<os-version>5.10</os-version>
<status>success</status>
</metadata>
<commands-output>
<command-output>
<metadata>
<command>ls</command>
<line-count>6</line-count>
<execution-milliseconds>129</execution-milliseconds>
<exit-code>0</exit-code>
<status>success</status>
</metadata>
<output>
<command>pwd</command>
<line-count>2</line-count>
<execution-milliseconds>621</execution-milliseconds>
<exit-code>0</exit-code>
<status>success</status>
</metadata>
<output>
<line index="1">/export/home/user1</line>
<line index="2">$</line>
</output>
</command-output>
</commands-output>
</target-output>
</targets-output>
</telnet-command-output>
XML sample of the Telnet adapter response with IPv6 support in a Linux to Linux environment
<telnet-command-output>
<metadata>
<status>success</status>
</metadata>
<targets-output>
<target-output host="fe80::219:d1ff:fe2f:82e6%eth0">
<metadata>
<os-id>Linux</os-id>
<os-version>2.6.9-22.ELsmp</os-version>
<status>success</status>
</metadata>
<commands-output>
<command-output>
<metadata>
<command>ls -l</command>
<line-count>19</line-count>
<execution-milliseconds>57</execution-milliseconds>
<exit-code>9999</exit-code>
<status>success</status>
</metadata>
<output>
<line index="1">total 84096</line>
<line index="2">drwxr-xr-x 2 root root 4096 Nov 16 09:43 760200</line>
<line index="3">drwxr-xr-x 7 root root 4096 Dec 9 12:28 Adobe CS5.1</line>
<line index="4">drwxrwxr-x 10 root root 4096 Dec 8 10:13 AMREPO_7602_9180</line>
<line index="5">drwxrwxr-x 17 name name 4096 Nov 15 12:49 Backup Data</line>
<line index="6">drwxr-xr-x 2 root root 4096 Jan 12 10:28 BEM</line>
<line index="7">drwxr-xr-x 3 root root 4096 Nov 22 15:01 blom</line>
<line index="8">drwxrwxr-x 3 name name 4096 Oct 21 2008 BPM_CLI</line>
<line index="9">drwxrwxr-x 2 name name 4096 Feb 3 2009 BPM_MIB</line>
<line index="10">drwxr-xr-x 2 root root 4096 Nov 28 15:19 BSA</line>
<line index="11">drwxrwxr-x 13 root root 4096 Dec 23 12:59 CDP_760200_9480</line>
<line index="12">rw-rr- 1 root root 17 Jun 30 2010 data.txt</line>
<line index="13">rw-rw-r- 1 name name 55 Aug 22 2008 deleteElements.csv</line>
<line index="14">drwxr-xr-x 2 name name 4096 Apr 15 2009 Desktop</line>
<line index="15">drwxr-xr-x 2 name name 4096 Mar 5 2009 DevLabDetails</line>
<line index="16">rw-rr- 1 name name 0 Apr 13 2011 echo</line>
<line index="17">rw-rw-r- 1 name name 5451 Dec 22 2008 InstallCert.class</line>
<line index="18">rw-rw-r- 1 name name 5036 Dec 22 2008 InstallCert.java</line>
<line index="19">rw-rw-r- 1 name name 1086 Dec 22 2008 InstallCert$</line>
</output>
</command-output>
</commands-output>
</target-output>
</targets-output>
</telnet-command-output>
The [expand] macro is a standalone macro and it cannot be used inline.
