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 prompt when the 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. | |
| Specifies 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. Otherwise, the type of OS is not verified and none of the executed commands returns an exit code. | |
| 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 to define 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 specified is encrypted; 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 prompt when the system is waiting for a user name
This element applies to a dynamic target.
Default value: login | |
| Displays the console prompt when the system is waiting for a password
This element applies to a dynamic target.
Default value: Password | |
| Contains the <command> elements | |
| 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. | |
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 BMC Atrium Orchestrator 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>
<verify-os>true</verify-os>
<timeout-secs>120</timeout-secs>
<login-prompt>user-name:</login-prompt>
<password-prompt>password for user1:</password-prompt>
<verify-os>true</verify-os>
<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>
<verify-os>true</verify-os>
<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.
Elements of a Telnet adapter response
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>
XML sample of the Telnet adapter response with IPv6 support in a Windows to Linux environment
<telnet-command-output>
<metadata>
<status>success</status>
</metadata>
<targets-output>
<target-output host="fe80::219:d1ff:fe2f:82e6%4">
<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>hostname</command>
<line-count>2</line-count>
<execution-milliseconds>438</execution-milliseconds>
<exit-code>0</exit-code>
<status>success</status>
</metadata>
<output>
<line index="1">induslog118.synapse.com</line>
<line index="2">-bash-3.00$</line>
</output>
</command-output>
</commands-output>
</target-output>
</targets-output>
</telnet-command-output>
