Adapter request and response for the SSH adapter

The SSH adapter does not use an action. To configure an adapter request for communicating 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. If a <targets> block is not provided, the default target from the adapter configuration is used.

SSH adapter can execute commands on a remote target via an HTTP proxy server if the target is not accessible directly. For all targets defined in the adapter configuration and the dynamic targets, HTTP proxy is static.

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 configuration because they elements might cause errors.

The following table describes the elements of an adapter request for the SSH adapter.

Note

If you execute a large number of concurrent SSH requests using the SSH adapter, the adapter might display an intermittent error. For details about troubleshooting this error, see SSH Troubleshooting.

The following figure shows a sample adapter XML request when the <target-os-type-verification> element is set to false.

Sample adapter XML request when the <verify-os> element is set to false
<ssh-request>
    <prompts>
      <prompt name="prompt" />
    </prompts>
    <targets>
      <target name="">
        <host>clm-pun-XXXX</host>
        <port>22</port>
        <userName>root</userName>
        <password>yyyy</password>
        <timeout-secs>60</timeout-secs>
        <use-shell-mode />
        <target-os-type-verification>false</target-os-type-verification>
        <prompt />
        <establish-connection-timeout-secs>60</establish-connection-timeout-secs>
      </target>
    </targets>
    <commands>
      <command encryption-type="plain" timeout-secs="60"><![CDATA[pwd]]></command>
    </commands>
  </ssh-request>

The following figure shows a sample adapter XML request when the <enable-http-proxy> element is set to false. In this case, the SSH connection for the targets defined in the adapter configuration is not established via the HTTP proxy server.

Sample adapter XML request when the <enable-http-proxy> element is set to false
<ssh-request>
 <enable-http-proxy>false</enable-http-proxy>
 <commands>
   <command>clm-pun-abc</command>
   <command>ls -lrt</command>
 </commands>
</ssh-request>

The following figure shows a sample adapter XML request when the <enable-http-proxy> element is set to true. In this case, the SSH connection for the targets defined in the adapter configuration is established via the HTTP proxy server.

Sample adapter XML request when the <enable-http-proxy> element is set to true
<ssh-request>
 <enable-http-proxy>true</enable-http-proxy>
 <commands>
   <command>clm-pun-abc</command>
   <command>ls -lrt</command>
 </commands>
</ssh-request>

The following figure shows a sample adapter XML request when the <enable-http-proxy> element is set to false. In this case, the SSH connection for the targets defined in the adapter configuration and for the target defined in the adapter request is not established via the HTTP proxy server.

Sample adapter XML request when the <enable-http-proxy> element is set to false
<ssh-request>
  <targets>
   <target>
      <host>vl-clm-abc</host>
      <userName>userA</userName>
      <password>pwdUserA</password>
   </target>
 </targets>
 <enable-http-proxy>false</enable-http-proxy>
 <commands>
     <command>vl-clm-dev</command>
     <command>ls -lrt</command>
 </commands>
</ssh-request>

The following figure shows the adapter response when the <target-os-type-verification> element is set to false. 

Adapter response when the <verify-os> element is set to false
<ssh-command-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="clm-pun-XXXX">
     <metadata>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>pwd</command>
           <line-count>1</line-count>
           <execution-milliseconds>47</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">/root</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ssh-command-output>

The following figure shows the adapter response when the <target-os-type-verification> is not specified or is true.

Adapter response when the <verify-os> is not specified or is true
<ssh-command-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="clm-pun-XXXX">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>2.6.32-358.23.2.el6.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>pwd</command>
           <line-count>1</line-count>
           <execution-milliseconds>78</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">/root</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ssh-command-output>

 

The following figure shows a sample XML template for the SSH adapter request.

XML template of the SSH adapter request
<ssh-request>
 <prompts>
    <prompt name =""></prompt>
 </prompts>
 <targets>
    <target name=""/>
    <target>
      <host></host>
      <port></port>
      <user-name></user-name>
      <password encryption-type=""></password>
      <prompt></prompt>
       <target-os-type-verification></target-os-type-verification>
       <read-buffer-size></read-buffer-size>
      <timeout-secs></timeout-secs>
      <known-hosts-config></known-hosts-config>
      <allow-unknown-hosts></allow-unknown-hosts>
      <preferred-pk-algorithm></preferred-pk-algorithm>
      <establish-connection-timeout-secs></establish-connection-timeout-secs>
      <network-environment></network-environment>
      <line-termination></line-termination>
    </target>
    <target>
      <host></host>
      <port></port>
      <user-name></user-name>
      <private-key-file></private-key-file>
      <pass-phrase encryption-type-""></pass-phrase>
      <prompt></prompt>
      <timeout-secs></timeout-secs>
      <known-hosts-config></known-hosts-config>
      <allow-unknown-hosts></allow-unknown-hosts>
      <preferred-pk-algorithm></preferred-pk-algorithm>
      <establish-connection-timeout-secs></establish-connection-timeout-secs>
      <network-environment></network-environment>
      <line-termination></line-termination>
    </target>
 </targets>
  <commands>
    <command prompt=""></command>
    <command timeout-secs=""></command>
    <command></command>
  </commands>
</ssh-request> 

The following figure shows an XML sample for the SSH adapter request. Use the adapter request XML when you create a custom process by using the Call Adapter activity in TrueSight Orchestration Development Studio.

XML sample of the SSH adapter request
<ssh-request>
<targets>
 <target>
  <host>10.128.248.97</host>
  <user-name>user-name1</user-name>
  <password encryption-type="Plain">password for user-name1</password>
  <allow-unknown-hosts>true</allow-unknown-hosts>
  <prompt>#</prompt>
  <target-os-type-verification>false</target-os-type-verification>
  <read-buffer-size>1024</read-buffer-size>
  <port>22</port>
  <connection>
   <name>sshtarget_connection</name>
   <terminate-on-exit>false</terminate-on-exit>
   <connection-initialize-commands>
   <command prompt="MYPROMPT $">export PS1="MYPROMPT $"</command>
   <command prompt="MYPROMPT $">pwd</command>
   <command prompt="MYPROMPT $">cd Desktop</command>         
   </connection-initialize-commands>
  </connection>
 </target>
</targets>
 <prompts>
   <prompt name="first">login:</prompt>
   <prompt name="second">root@10.128.248.106's password:</prompt>
   <prompt name="third">#</prompt>
 </prompts>
 <commands>
   <command>hostname</command>
   <command prompt="second" ignore-exit-code="true">ssh root@10.128.248.106</command>
   <command prompt="third" ignore-exit-code="true">root@123</command>
   <command prompt="third" ignore-exit-code="true">ls</command>
 </commands>
</ssh-request> 

The following figure shows an XML sample for the SSH adapter request using the <use-pseudo-terminal> command.

XML sample of the SSH adapter request using the <use-pseudo-terminal> command
<ssh-request>
<targets>
 <target>
  <host>server1</host>
  <port>22</port>
  <user-name>user</user-name>
  <password>abc</password>
  <use-pseudo-terminal>true</use-pseudo-terminal>
</target>
</targets>
<commands>
 <command>type testFile.txt</command>
</commands>
</ssh-request>

The following figure shows an XML sample of the SSH adapter with CharSet.

XML sample of the SSH adapter request with CharSet
<ssh-request>
  <targets>
     <target>
        <host>server1</host>
        <port>22</port>
        <user-name>user</user-name>
         <password encryption-type="Plain">abc</password>
        <allow-unknown-hosts>true</allow-unknown-hosts>
        <character-set>Shift_JIS</character-set>
     </target>
  </targets>
  <commands>
       <command>type testFile.txt</command>
  </commands>
</ssh-request> 

The following figure shows an XML sample of the SSH adapter request using the private key data approach.

XML sample of the SSH adapter request using the private key data approach
<ssh-request
 <targets>
   <target>
      <host>10.128.248.118</host>
      <prompt>$</prompt>
      <user-name>rajat</user-name>
      <allow-unknown-hosts>true</allow-unknown-hosts>
      <private-key-data>
        --BEGIN RSA PRIVATE KEY----
        Proc-Type: 4,ENCRYPTED
        DEK-Info: DES-EDE3-CBC,0FFD900EA089BBDD
        S5lpB02OesPZ9bEXJfYaziok9kSs46VfgHRF1WPgRQGFOnVvs0m+KU1iL5EiFzRC
        m3q9h2Dat+uLzdrnGWyAjaiTqAnlMcBtlgdu6UQfwPipXMMnOJpU2M0+8NqtZGiL
        3yFK6Zoox9EQ+enU2KlV05UUpo6I0erHvHcigDDK6tI4x50H7dHVtNixOlH3a/q5
        3A0t6ccPaOcBui+dsTO65nK7AcywRzhdhSBrDaFBoJBuBqiZ5p3AAi2xre+QAIpx
        wCoDBp76FRFePv2NYl7KEH4ajU4kR6DQoJiwgoD9TE6S/OwY79gr1cAoYQt+ldDi
        xiMzm5gV4BooYQDX8j63Qt6qABhOAAzATbOBedHdtRsn01B6saRtjrdI2QrHzx0t
        Cw/d3RoUS16uoXi66eA9L6dnwa5dyfO1KhkA3NV5LkX7NXfu5wu8Oua3JOnbRCIH
        shTrprCuwRFfUEqKz+KytckMbuVFPmD79pw4vsIWemN2xAPMdQEUFzprxWaI+6SY
        H0GSfiekfPBlE+8/jR2+a3giTAuRnUlchcCG7G95T/rREYzlx4vLTjVA3gzw/CPE
        9fcEBvgJVTY7VkpKQspsV9WM5tDKUJbsLG1UIKTa+ZLyIC1Nd9QroDGWbT72QxnA
        jzNDLS/CB4i/DK71dri19AZLre5pXL4G1Jgw192l+xx2oXv0xdHPHArBSpdnKQdo
        81ytjZomCPH41Ez5HxIBRHYWJz/rKsFPcnfAHCgRAxDJU8WXEB6GhwAvFqc6VFdK
        7HkD1Ec3uVw5BDize8DWY/fLJQL4T4zwvirWAlMQrbrdRwRc+9WxikBy1oVvxN4U
        dSUSsePwQ9QQq0PhKx+a3A/Ue9y/H51SEXsA46Uhtk9QV39D5tWEs/DoGqn8glGE
        I77saju3aQCjlpXq9QQXVAhvScG4MMhlri87DiCKa4PJ7kvq5d4IizlxMq0wjflX
        nrTqZDvMUAudZgi86679Km2WG5ZwSgXNOjA+B/Jo5c/T4Z1gWlnvpW5R0PUnsrMx
        V7U3fWcq2R8XUQzOdc4dJx55e8kP3tilO3HbNmfDRAgPoBUE1nIfRpv738nYbbOl
        msSrcv2lULIsF1qvA69ZOM5ziKvu0ElpgHMhZTGB4mcO8bDuBIdVeYhmmBgNL5r1
        GPOjdA/rqchWovR2SdCPTN0QiAhdFSzOKXSCJnv29dXsWSEUiYiXnTkLuyNOIgTS
        5ypd6MzPDbY8gWL/OYrdC8H98jt9YiZVroU7ra9zFoRC8cXbKgZevqoNnUUBTcfa
        pj5VzhKsHOwcObdL/oGxum97CDpjNoUYjqEF2W8N6rnScaCqoInOjGkm0WLxreLD
        BwsOJ2J7c40sr0gWzDGBC70HmA2rQba9TWZDuoE98H8XAv8Pdnv9K8+u/Q6IoXpo
        LJJmvjvA4LiPGn688+nKrcvrx8D5iz64ynQ2TaQlwz538AKFsaIBrn2F1oSnZ09M
        m45n5Rgkih0pti9SiOHbm84X7696mQLdh2y07U1IXj+uQoC30gJHKQa37kEEKYeV
        +ERwLmMr+JH2DWADnBMqizd2+ROo0V2vL4Vj17B+9rGg0LmnyCkyQQ==
        --END RSA PRIVATE KEY----
      </private-key-data>
      <pass-phrase encryption-type="plain">changeit</pass-phrase>
    </target>
   </targets>
   <commands>
     <command>pwd</command>
     <command>export abd="asdsd"</command>
     <command>echo $abd</command>
     <command>pwd</command>
   </commands>
</ssh-request> 

The following figure shows an XML sample for the SSH adapter request using the <use-shell-mode> command.

XML sample of the SSH adapter request using the <use-shell-mode> element
<ssh-request>
  <targets>
      <target name="">
           <host>XYZABC</host>
           <user-name>root</user-name>
           <password>bmcAdm1n</password>
           <allow-unknown-hosts>true</allow-unknown-hosts>
           <establish-connection-timeout-secs>70</establish-connection-timeout-secs>
           <use-shell-mode>true</use-shell-mode>
           <character-set>UTF-8</character-set>
       </target>
           </targets>
       <commands>
           <command  timeout-secs="500" >ls</command>
           <command  timeout-secs="500" >cat readthisfile.txt</command>
       </commands>
</ssh-request>

The following figure shows the sample adapter request using the <mask-command-string> element in multiple commands.

<ssh-request>
   <prompts>
     <prompt name="prompt" />
   </prompts>
   <targets>
     <target name="">
       <host><hostname></host>
       <port>22</port>
       <userName>root</userName>
       <password>****MASKED****</password>
       <timeout-secs>60</timeout-secs>
       <use-shell-mode />
       <use-pseudo-terminal />
       <prompt />
       <establish-connection-timeout-secs>60</establish-connection-timeout-secs>
     </target>
   </targets>
   <commands>
     <command mask-command-string="true" timeout-secs="500"><![CDATA[hostname]]></command>
     <command mask-command-string="true" timeout-secs="500"><![CDATA[ifconfig]]></command>
   </commands>
 </ssh-request>

The following figure shows the adapter response for the request.

<ssh-command-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="hostname">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>4.1.12-112.14.13.el7uek.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>****MASKED****</command>
           <line-count>1</line-count>
           <execution-milliseconds>954</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1"><hostname></line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>*****MASKED*****</command>
           <line-count>26</line-count>
           <execution-milliseconds>971</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">ens160: flags=4163&lt;UP,BROADCAST,RUNNING,MULTICAST&gt;  mtu 1500</line>
           <line index="2">        inet 10.135.39.4  netmask 255.255.224.0  broadcast 10.135.63.255</line>
           <line index="3">        inet6 fe80::250:56ff:fe8f:a69  prefixlen 64  scopeid 0x20&lt;link&gt;</line>
           <line index="4">        ether 00:50:56:8f:0a:69  txqueuelen 1000  (Ethernet)</line>
           <line index="5">        RX packets 939755556  bytes 82157297538 (76.5 GiB)</line>
           <line index="6">        RX errors 6  dropped 6  overruns 0  frame 0</line>
           <line index="7">        TX packets 802796  bytes 294988281 (281.3 MiB)</line>
           <line index="8">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0</line>
           <line index="9" />
           <line index="10">ens192: flags=4163&lt;UP,BROADCAST,RUNNING,MULTICAST&gt;  mtu 1500</line>
           <line index="11">        inet 10.135.7.139  netmask 255.255.224.0  broadcast 10.135.31.255</line>
           <line index="12">        inet6 fe80::250:56ff:fe8f:5979  prefixlen 64  scopeid 0x20&lt;link&gt;</line>
           <line index="13">        ether 00:50:56:8f:59:79  txqueuelen 1000  (Ethernet)</line>
           <line index="14">        RX packets 3905536083  bytes 254060709433 (236.6 GiB)</line>
           <line index="15">        RX errors 6  dropped 6  overruns 0  frame 0</line>
           <line index="16">        TX packets 2250102  bytes 98458648 (93.8 MiB)</line>
           <line index="17">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0</line>
           <line index="18" />
           <line index="19">lo: flags=73&lt;UP,LOOPBACK,RUNNING&gt;  mtu 65536</line>
           <line index="20">        inet 127.0.0.1  netmask 255.0.0.0</line>
           <line index="21">        inet6 ::1  prefixlen 128  scopeid 0x10&lt;host&gt;</line>
           <line index="22">        loop  txqueuelen 0  (Local Loopback)</line>
           <line index="23">        RX packets 714540  bytes 254373372 (242.5 MiB)</line>
           <line index="24">        RX errors 0  dropped 0  overruns 0  frame 0</line>
           <line index="25">        TX packets 714540  bytes 254373372 (242.5 MiB)</line>
           <line index="26">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ssh-command-output>

The following table describes the elements of an SSH adapter response.

The following figure shows the adapter response for the SSH adapter.

XML sample of the SSH adapter response
<ssh-command-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="10.128.248.97">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>2.6.9-42.ELsmp</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>hostname</command>
           <line-count>2</line-count>
           <execution-milliseconds>16</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">realops-linux.abc.com</line>
           <line index="2">[root@realops-linux ~]#</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>ssh root@10.128.248.106</command>
           <line-count>1</line-count>
           <execution-milliseconds>297</execution-milliseconds>
           <exit-code>9999</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">root@10.128.248.106's password:</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>root@123</command>
           <line-count>3</line-count>
           <execution-milliseconds>22062</execution-milliseconds>
           <exit-code>9999</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">Last login: Tue Apr 20 12:35:32 2010 from 10.128.248.86</line>
           <line index="2">-bash: REPO: command not found</line>
           <line index="3">[root@realops-sshclient ~]#</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>ls</command>
           <line-count>16</line-count>
           <execution-milliseconds>172</execution-milliseconds>
           <exit-code>9999</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">[00m[00manaconda-ks.cfg[00m [00mprofile413456623[00m</line>
           <line index="2">[01;34mDesktop[00m  [00mprofile425614260[00m</line>
           <line index="3">[00minstall.log[00m [00mprofile615033302[00m</line>
           <line index="4">[00minstall.log.syslog[00m [01;31mtelnet-server-0.17-26.EL3.3.i386.rpm[00m</line>
           <line index="5">[01;34mjava[00m [01;31mvsftpd-2.0.1-8.el4.i386.rpm[00m</line>
           <line index="6">[01;32mjdk-6u16-solaris-i586.sh[00m   [00mzprofile1104250438[00m</line>
           <line index="7">[01;32mjdk-6u16-solaris-sparc.sh[00m  [00mzprofile1429689734[00m</line>
           <line index="8">[01;32mjdk-6u16-solaris-sparcv9.sh[00m  [00mzprofile1632425172[00m</line>
           <line index="9">[00mprofile1064777096[00m   [00mzprofile1760702416[00m</line>
           <line index="10">[00mprofile1178790592[00m  [00mzprofile1877235460[00m</line>
           <line index="11">[00mprofile1379315196[00m  [00mzprofile2053475337[00m</line>
           <line index="12">[00mprofile1647775163[00m  [00mzprofile437787547[00m</line>
           <line index="13">[00mprofile1835270538[00m  [00mzprofile478856458[00m</line>
           <line index="14">[00mprofile2042636870[00m  [00mzprofile667791972[00m</line>
           <line index="15">[00mprofile2068878841[00m  [00mzprofile861707713[00m</line>
           <line index="16">[m[root@realops-sshclient ~]#</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ssh-command-output> 

The following figure shows an XML sample of the SSH adapter response using the private key data approach.

XML sample of the SSH adapter response using the private key data approach
<ssh-command- output>                                                               
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="10.128.248.118">
     <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>pwd</command>
           <line-count>2</line-count>
           <execution-milliseconds>8</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">/home/rajat</line>
           <line index="2">-bash-3.00$</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>export abd="asdsd"</command>
           <line-count>1</line-count>
           <execution-milliseconds>6</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">-bash-3.00$</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>echo $abd</command>
           <line-count>2</line-count>
           <execution-milliseconds>7</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">asdsd</line>
           <line index="2">-bash-3.00$</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>pwd</command>
           <line-count>2</line-count>
           <execution-milliseconds>5</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">/home/rajat</line>
           <line index="2">-bash-3.00$</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ssh-command-output> 
<ssh-request>
 <enable-http-proxy>false</enable-http-proxy>
 <commands>
   <command>clm-pun-abc</command>
   <command>ls -lrt</command>
 </commands>
</ssh-request>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*