Guide for using adapters to integrate with BMC Impact.Full description
gergr
Descripción: BMC BAO Guide
Descrição completa
Guia Didáctica para la enseñanza de la ReligiónDescripción completa
Sap pi Adapters FaqFull description
respuestas al curso del Bloomberg Market Concepts (BMC)Descripción completa
analisisDeskripsi lengkap
Full description
Full description
penjelasan bmcFull description
respuestas al curso del Bloomberg Market Concepts (BMC)Full description
TOR Data Base Air Tanaah Air BakuFull description
respuestas al curso del Bloomberg Market Concepts (BMC)Full description
TBIT42 en Adapters OverviewDescription complète
tor orientasi perawatFull description
TorFull description
askep atrium fibritasi
teknologi panganDeskripsi lengkap
BMCFull description
Deskripsi lengkap
Defek Septum AtriumFull description
BMC Atrium Orchestrator User Guide for Base Adapters
Supporting BMC Atrium Orchestrator version 7.6.05.00 Base Adapters December 2010
www.bmc.com
Contacting BMC Software You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada Address
BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA
BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. BladeLogic, Inc. considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License agreement for the product and the proprietary and restricted rights notices included in this documentation. IBM® is the trademark or registered trademark of International Business Machines Corporation in the United States, other countries, or both. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. UNIX is the registered trademark of The Open Group in the US and other countries. Linux is the registered trademark of Linus Torvalds.
Restricted rights legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices must be sent to this address.
Customer support You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or email. To expedite your inquiry, see “Before contacting BMC.”
Support website You can obtain technical support from BMC at http://www.bmc.com/support. From this website, you can: ■ ■ ■ ■ ■ ■ ■ ■
Read overviews about the several levels of support services and other programs that BMC offers Find current information about BMC products Search the knowledge base for issues similar to yours and possible solutions, or for articles about the product Order or download product documentation Download products and maintenance Report an issue or ask a question Subscribe to receive proactive email alerts when new product notices are released Find worldwide BMC support center locations and contact information, including email addresses, fax numbers, and telephone numbers
Support by telephone or email In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or send an email message to [email protected]. (In the subject line, enter SupID:, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.
Before contacting BMC Have the following information available so that Customer Support can begin working on your issue immediately: ■
product information — — —
■
product name product version (release number) license number and password (trial or permanent)
operating system and environment information — — — — —
machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level
■
sequence of events leading to the issue
■
commands and options that you used
■
messages received (and the time and date that you received them) — — —
product error messages messages from the operating system, such as file system full messages from related software
3
License key and password information If you have questions about your license key or password, contact BMC as follows: ■
(USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an email message to [email protected].
■
(Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20 354 8702, or send an email message to [email protected].
■
(Asia-Pacific) Contact your BMC sales representative or your local BMC office.
About this book To request printed books or to view online books and notices (such as release notes and technical bulletins), see the Customer Support website at http://www.bmc.com/support_home. Some product shipments also include the online books on a documentation CD.
NOTE Online books are formatted as PDF or HTML files. To view, print, or copy PDF books, use the free Adobe Reader from Adobe Systems. If your product installation does not install the reader, you can obtain the reader at http://www.adobe.com.
The software also offers online Help. To access Help, press F1 within any product or click the Help button in graphical user interfaces (GUIs).
Related publications The following related publications supplement this book and the online Help: Document
Description
BMC Atrium Orchestrator System Administration Guide
Provides conceptual and procedural information about managing the BMC Atrium Orchestrator grid environment
BMC Atrium Orchestrator Development Studio User Guide
Describes how to use BMC Atrium Orchestrator Development Studio
BMC Atrium Orchestrator Common Actions User Guide
Contains conceptual information as well as inputs and outputs for the operations actions management module workflows
BMC Atrium Orchestrator Installation Guide
Describes how to plan for, install, and upgrade the BMC Atrium Orchestrator product
BMC Atrium Orchestrator Security Guide
Describes how to use BMC Atrium Orchestrator Access Manager to manage accounts and single sign-on configurations
BMC Atrium Orchestrator User Guide for Base Contains details about configuring and using the BMC Atrium Adapters Orchestrator base adapters BMC Atrium Orchestrator User Guides for Contain details about configuring and using the BMC Atrium Application Adapters Orchestrator application adapters
About this book
9
Conventions
Conventions This book uses the following special conventions: ■
All syntax, operating system terms, and literal examples are presented in this typeface.
■
Variable text in path names, system messages, or syntax is displayed in italic text: testsys/instance/fileName
■
The symbol => connects items in a menu sequence. For example, Actions => Create Test instructs you to select the Create Test command from the Actions menu.
Searching across PDF documents in a folder and its subfolders With Adobe Reader version 7.0 and later, you can perform a full-text search across all PDFs that reside in the same folder and its subfolders. If you do not have Adobe Reader version 7.0 or later, you can download the latest Adobe Reader version from http://www.adobe.com for free.
To search for a word or phrase in PDF documents in a single directory 1 Start Adobe Reader. 2 In the toolbar, click the search icon (binoculars). If the search icon is missing, right-click the toolbar to find more toolbar options. Different versions of Adobe Reader put the option in different places.
3 In the Search window, select All PDF Documents in under Where would you like to search?
4 Click the folder selection box and select Browse for Location. 5 Browse to the top-level folder that contains the PDF documents that you want to search.
6 In the What word or phrase would you like to search for? box, type a search term and click Search.
10
BMC Atrium Orchestrator Base Adapters User Guide
Searching across PDF documents in a folder and its subfolders
The search tool searches for the specified term in all of the PDFs in the chosen directory and its subdirectories and displays the results.
About this book
11
Searching across PDF documents in a folder and its subfolders
Adapter overview Adapters provide an interface between BMC Atrium Orchestrator workflow processes and external third-party applications and support systems. Adapters are located on peers and configured in Grid Manager to establish connections and facilitate communications. Adapters are used in BMC Atrium Orchestrator Development Studio when creating processes and in BMC Atrium Orchestrator for executing processes and providing input for rules to evaluate. Adapters are of the following categories: ■
Base adapters interface to systems by using standard protocols, such as JDBC, Telnet, SSH, JMS processes, and so on.
■
Application adapters interface with a specific product.
Within these categories are adapters of the following types: ■
Actor adapters interact with external systems, sending commands or requests and, in some cases, receiving responses to requests. For example, an email actor adapter can be used to send an email message.
Chapter 1 Overview of base adapters
13
Configuring the adapter
■
Monitor adapters listen on external systems and, based on their configuration, generate events. An email monitor adapter would monitor an email account on a specified server and generate an event when a specific message is received. This event could be used to trigger a workflow process.
You can configure the adapters with Grid Manager for specific grids and can then enable them on one or more peers on the grid. Any adapter that is used in a process must be enabled on at least one peer on a grid. The configuration is referenced when adapters are called within processes. You can create processes within BMC Atrium Orchestrator Development Studio. Actor adapters are used within workflow processes to perform specific functions and to interface with external applications. Schedules can be created to trigger the execution of specific processes. You can create rules within BMC Atrium Orchestrator Development Studio to evaluate events generated by monitor adapters. A rule contains event criteria and specifies a process to be executed when the rule is satisfied (true). You can create a module using BMC Atrium Orchestrator Development Studio. A module contains processes, schedules, and rules. Modules are exported from BMC Atrium Orchestrator Development Studio, within snapshots, to a grid's library for deployment and activation in Grid Manager. Upon activation of a module on a grid, schedules and rules are enabled. Schedules trigger processes at defined intervals and rules evaluate events generated by monitor adapters, triggering designated processes for events that evaluate to true for a rule. A single event can trigger multiple processes if multiple rules evaluate to true for that event.
Configuring the adapter Adapters are configured in Grid Manager, using an XML document to define the connection details and adapter properties. For each adapter, this guide includes the adapter type, a table outlining the adapter configuration fields, and an XML template for a configuration node, which is an XML file that contains the adapter configuration properties. Each adapter requires specific information in the configuration node to enable communications between systems or applications and processes. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties.
14
BMC Atrium Orchestrator Base Adapters User Guide
Configuring the adapter
The form view provides an easy-to-use interface for configuring adapters. It prevents human errors that might occur as a result of copying the configuration XML from the adapter user guide into the UI when configuring an adapter. You can switch to the XML view to configure those elements and attributes that are not available as fields or to configure all the elements and attributes using XML only. However, after you switch to the XML view, and save the configuration in the XML from that view, you cannot thereafter use the form view for modifying that configuration.
To configure the actor adapter, monitor adapter, or both 1 Log on to the BMC Atrium Orchestrator Grid Manager. 2 Access the adapters page, by clicking the Manage tab; then click the Adapters tab. 3 In the Adapters in Repository list, select the check box corresponding for the type of adapter to be added. The adapter type use the following naming convention: ro-adapter-adapter type. For example, the adapter type for the IMAP adapter would be ro-adapterimap.
4 Click Add to Grid to include the adapter in the Adapters on Grid list. 5 Click Configure corresponding to the newly added adapter. 6 On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or jump to step 7 on page 16 to configure the adapter using the XML view:
A Enter a name for the adapter. B Enter a description for the adapter. C Under Properties, enter or select values for the configuration elements. The configuration elements for each adapter are described in that adapter's section. Include all required elements indicated with an asterisk (*).
D (optional) Click Switch to XML View and use the following steps to specify elements and attributes that are not in the form view.
NOTE Switching to the XML view to specify those elements and attributes not included in the form means that you cannot thereafter use the form for modifying that configuration. This step is not required for base adapters that can be fully configured using the form.
Chapter 1 Overview of base adapters
15
Actor adapter requests
1. On the Warning message that appears, click Switch View. 2. In the Properties text box, use XML format to enter the configuration elements and attributes not available as fields in the form view. 3. Click OK.
7 (optional) Configure the adapter in the XML view using the following substeps: A Enter a name and a description for the adapter. B Click Switch to XML View. C On the Warning message that appears, click Switch View. D Copy the configuration elements and attributes from the adapter user guide into the Properties text box, and then click OK.
NOTE If the default value for an optional element is acceptable, omit the element. Do not include empty elements.
E On the Warning message that appears, click Save. This saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. The BMC Atrium Orchestrator Development Studio User Guide contains the detailed steps to establish adapter configurations on the grid and assign them to individual peers. In Grid Manager, you can create multiple adapters with the same type to accommodate different configuration node properties, provided that you give the adapters unique names.
Actor adapter requests Actor adapters use requests to obtain data from external systems and, in some cases, affect data in those systems. These requests are configured in BMC Atrium Orchestrator Development Studio in either a Call Adapter activity or an Assign activity. In a Call Adapter activity, the adapter request is defined by the following ways in the Properties tab of the Activity Property window:
16
BMC Atrium Orchestrator Base Adapters User Guide
Actor adapter requests
■
Static value: specifies the XML text of the request that you enter in the adapter’s Data field, exactly as shown in the templates and the samples provided in this
guide. ■
Context key: specifies that an Assign activity is used to create an XML document for
the adapter request and assigns that document to a context item. The context item is referenced in the Properties tab of the Call Adapter activity. This XML document must be contained within tags. These tags are not included in the XML templates and the samples provided in this guide. You must add them to create a request that executes successfully. Some adapters can perform more than one type of action, so you must specify the action in the Action field of the Properties tab. For each adapter, this guide includes the available actions, a table outlining XML request elements, an XML template of the request, and a sample of XML adapter request. The BMC Atrium Orchestrator Development Studio User Guide contains detailed steps about using the Call Adapter and Assign activities.
Chapter 1 Overview of base adapters
17
Actor adapter requests
Table 1 describes the fields associated with each available option in the Properties tab for a Call Adapter activity. Table 1
Call Adapter activity properties—static value as the adapter input (part 1 of 2)
Fields
Description
Adapter Name
Specifies the adapter to use to service the request It must be an adapter that has been configured in Grid Manager.
Peer Location
Specifies the location of the peer that services the adapter request The adapter must be enabled on the peer that services the request. This can be a different peer from the one that is executing the process. Following are the options: ■
any: Specifies that the adapter request can be serviced by any peer on the grid. The master job processor distributes the process to the next available peer. The adapter must be enabled on at least one peer on the grid.
■
this: Specifies that the adapter request is serviced by the selected peer and contains the master job processor. With this option, The adapter must be enabled on the configuration distribution peers (CDPs) and all the activity peers (APs) on the grid because any one of them can be the master job processor at any time. Lightweight activity peers (LAPs) cannot become the master job processor.
■
best: Allows the grid to determine the best peer to service the request. The adapter must be enabled on at least one peer on the grid.
peer: Enables you to specify the peer to service the adapter request. The adapter must be enabled on the peer specified in the Peer Name field. Peer Name
Specifies the peer on the grid on which the adapter is enabled This element is required when the value of is peer.
Action
Specifies the type of action to be performed by the adapter request Not all adapters use an adapter action. If an adapter does not have an associated action, leave this field blank.
18
BMC Atrium Orchestrator Base Adapters User Guide
Actor adapter requests
Table 1
Call Adapter activity properties—static value as the adapter input (part 2 of 2)
Fields
Description
Adapter Data
Specifies an XML document that defines the adapter request The samples and the templates for each adapter can be referenced in this document. You can enter the templates provided in this document into the Adapter Data field exactly as shown. Specifies, for the Context key option, a context item that contains an XML document with a root element, , for the adapter request
Adapter Input
Click the browse icon to launch the Context Browser and select a context item, the value of which must contain the element and all required elements for the adapter request. The specific XML required for each adapter can be referenced in this document. If you select a global context item, the globe icon is displayed. Adapter Output
Specifies the context item to which the adapter response is assigned Not all adapter requests produce an adapter response. If an adapter output is assigned for an adapter request that does not produce a response, the activity fails and a compensation is executed.
Each adapter request consists of the elements shown in Table 2. The complete adapter request is formed by the Call Adapter activity, which uses information provided in its Activity Property panel. The only XML content that you must provide is contained in the element shown in Figure 1. Figure 1
XML sample of an adapter request
target_adapter_name this | any | best | peer peer_nameadapter-specific request action textadapter-specific request XML data
Chapter 1 Overview of base adapters
19
Actor adapter responses
Table 2 describes the actor adapter request elements. Table 2
Actor adapter request elements
Request element
Description
Required
Specifies the adapter name as defined in Grid Manager
Yes
Contains information about which peer to use to execute the adapter request
Yes
Specifies the type of peer from which the adapter request executes: this, any, best, peer For description of these values, see Table 1 on page 18.
Yes
An adapter request can be executed on a peer different from the one that executes the process that initiates the adapter request.
Specifies the peer name
Yes
This element is used only when the value of is peer.
Specifies the action that the request executes
No
Specifies an XML document that provides the adapter with specific instructions and parameters to facilitate an action
No
Actor adapter responses An actor adapter response contains the result returned by an actor adapter request. The contents of the response vary by adapter, and not all adapters produce a response. The response can be assigned to a context item. In BMC Atrium Orchestrator Development Studio, you must enter this context item in the Adapter Output field of the Activity Property window of the Call Adapter activity. By assigning the adapter response to a context item, you make the response available to subsequent activities in the process. If an adapter output is assigned to an adapter request that does not produce a response, the activity fails and a compensation is executed. For each actor adapter that generates an adapter response, this guide includes the sample adapter responses. For detailed information about configuring activities and building workflows, see the BMC Atrium Orchestrator Development Studio User Guide.
20
BMC Atrium Orchestrator Base Adapters User Guide
Monitor adapter events
Monitor adapter events Monitor adapters generate events for specific occurrences of detected actions in external systems. The criteria for event generation are defined in the adapter's configuration node in Grid Manager. Monitor adapters generate events when they are enabled on an active peer and an external incident occurs that warrants an event notification. Figure 2 shows a sample event for a monitor adapter. Figure 2
XML sample of a monitor adapter event
adapter-nameevent text event XML data
Each adapter event contains XML elements as indicated in Table 3. Table 3
Monitor adapter event elements
Request elements
Description
Specifies the adapter name as configured in Grid Manager
Specifies the text that summarizes an event, a description of the event
Contains the adapter specific response The contents of this element vary depending on the adapter.
Rules are created in BMC Atrium Orchestrator Development Studio, within the rules designer for a module, to evaluate these events. For monitor adapter events that meet the module's rule criteria, a process is triggered. For detailed instructions for creating rules for a module, see the BMC Atrium Orchestrator Development Studio User Guide. To use the data from the monitor adapter event in the triggered process, create a job input parameter on the Start activity of the workflow. The content of the element from the monitor adapter event automatically populates this input.
Chapter 1 Overview of base adapters
21
Monitor adapter events
22
BMC Atrium Orchestrator Base Adapters User Guide
Chapter
2
2
Terminal adapter features A terminal adapter is a communication or an interface between a computer and an integrated services digital network line. The adapter enables you to host multiple client sessions simultaneously. Base adapters that share some common features and functionality and are classified as terminal type adapters are: ■ ■ ■ ■ ■ ■ ■ ■ ■
Multiple configuration nodes The multiple configuration nodes feature enables a single adapter configuration to have multiple remote hosts defined. Each configuration node designates the connection criteria for a specific remote host. The first configuration node is the default configuration node. If you do not assign a value to the first node, default is used. A name is mandatory for additional nodes. The following adapters support multiple configuration nodes: ■ ■ ■ ■ ■ ■ ■ ■
SSH Kerberized SSH Telnet SCP FTP SFTP Windows Command PowerShell
In the adapter request, the configuration node names are referred to as target names. Figure 3 provides an XML sample of an adapter configuration with multiple nodes. Figure 3
XML sample of an adapter configuration with multiple nodes
<>adapter-specific element1 <>adapter-specific element2 <>adapter-specific element3you have a config element <>adapter-specific element4
24
BMC Atrium Orchestrator Base Adapters User Guide
Dynamic Targets
NOTE The element is optional, but BMC recommends that you use it when more than one node is defined.
Dynamic Targets The dynamic targets feature enables you to define the connection information for a remote host within an adapter request. With the use of dynamic targets, you can configure an adapter in Grid Manager with a configuration node, , and designate the configuration node in each adapter request. Alternatively, an adapter configuration can contain a fully defined configuration node and have a dynamic target defined for selected adapter requests. The following adapters support dynamic targets: ■ ■ ■ ■ ■ ■ ■ ■
SSH Kerberized SSH Telnet SCP FTP SFTP Windows Command PowerShell
In an adapter request, you can designate the target information using the following methods. You can combine these methods in a single request for multiple targets. The commands provided in an adapter request are executed on each target designated in that request. ■
Method 1: To designate a specific target that has been defined in the adapter configuration, use the elements shown in the request in Figure 4.
Figure 4
XML sample of a specific target
... ...
■
Method 2: To use all the targets defined in the adapter configuration, use the elements shown in the request in Figure 5.
Chapter 2
Terminal adapter features
25
Command attributes for specifying directories
Figure 5
XML sample of all defined targets
... ...
■
Method 3: To define a dynamic target within a request, use the elements shown in the request in the Figure 6.
Figure 6
XML sample of a dynamic target
...
When defining a dynamic target in an adapter request, you must provide all the required target elements in the request. With a dynamic target, partial target information cannot be retrieved from the adapter configuration. A target is either defined completely in the configuration or in the adapter request.
Command attributes for specifying directories Command Line and Windows Command adapter requests contain elements that can use the following optional attributes to specify directories for command execution or script location. Table 4 describes the command attributes for directories. Table 4
attributes for directories
Attribute
Description
Specifies the directory where the command is executed If this attribute is not specified, the command executes in the $AO_HOME directory. This attribute is not valid for the Windows Command adapter.
Specifies the directory in which the script is located If this attribute is not specified, the script must be located in the current directory.
26
BMC Atrium Orchestrator Base Adapters User Guide
Command attribute for specifying a timeout
In the Command Line adapter sample XML request shown in Figure 7, the command executes in the /usr/executionDir directory, using a script from the /usr/scriptDir directory. Figure 7
XML sample of attributes for directories
... MyScript.sh ...
Command attribute for specifying a timeout Command Line, SSH, Kerberized SSH, Telnet, SCP, FTP, SFTP, and Windows Command adapters can use the timeout-secs attribute in a element to define the time, in seconds to wait after the execution of a command for a prompt to be returned after the successful execution of a command. This delay can prevent the request from becoming unresponsive, especially in cases where the prompt returned is different from the expected prompt. The default-value of timeout-secs is 60. In the XML sample shown in Figure 8, if the prompt is not returned within 90 seconds, the adapter response is an error message indicating that a timeout occurred. Figure 8
XML sample of a command attribute for timeout
... pwd ...
FAT commands to enable platform independence Command Line, SSH, Kerberized SSH, Telnet, Windows Command, and PowerShell adapters use a FAT command that enables the creation of platform-independent adapter requests. The element contains multiple elements, each containing a value that has syntax specific to a system type and an optional system version. The os-id and os-version attributes define the platform.
Chapter 2
Terminal adapter features
27
FAT commands to enable platform independence
Valid values for the os-id element are: ■
Windows Server 2008
■
MacOS
■
Windows NT
■
AIX
■
Windows 2000
■
HP-UX
■
Windows 2003
■
Cisco IOS
■
Windows XP
■
JunOS
■
Windows Default
■
F5 TM OS
■
Linux
■
SunOS
During the execution of the adapter request, the adapter compares the value of the os-id (and os-version if provided) command attributes with the target system's
type and version and executes the command that provides an exact match. If any of the os-ids in the element do not match with the target Windows OS, the adapter will search for the command where the os-id is Windows Default and execute the command for this os-id. If no exact match is found and Windows Default is not specified as an os-id, the adapter request is not executed and a compensation, if defined, is executed.
NOTE If you specify Windows Default as the os-id, you must not use the os-version attribute in the adapter request.
Like standard command elements, you can use multiple FAT command elements in a single adapter request. The XML sample shown in Figure 9 uses the ping command to send five requests to server1. Only one command is executed, based on the operating-system type of the computer executing the command. If the operating-system type does not match any of the types provided, a compensation, if defined, is executed. Figure 9
You can define more then one FAT command for each operating system. When you do that, you use a element to contain the elements to be executed for a single operating system. You use the os-id and os-version attributes of the element. Additional attributes added to the element apply to the child elements. In addition to the attributes in the element, each command can have individual attributes defined. When using the multiple command structure, you can define only the os-id and osversion as attributes of the element. You can use all other valid command attributes on either the or elements. If you specify an attribute in both the and the elements, the attribute value in the element takes precedence. Figure 10 illustrates the options available with the multi-command structure for FAT commands. For the Linux® commands, the first command has a timeout of 90 seconds and the second command has a timeout of 120 seconds. Figure 10
XML sample of a multi-command structure for FAT commands
Figure 11 shows an XML sample of FAT commands with Windows Default as the value for the os-id attribute. Figure 11
XML sample of FAT commands with Windows Default as the value for the os-id attribute
ipconfigdirhostname
Chapter 2
Terminal adapter features
29
Password encryption
Password encryption SSH, Kerberized SSH, Telnet, SCP, FTP, SFTP, Windows Command, and PowerShell adapters can use an encryption-type attribute with the element. You can use this attribute in the adapter configuration or in a dynamic target in an adapter request. If no encryption-type is specified, the value is considered to be unencrypted (Plain). The encryption-type value is not case sensitive. The valid values for encryption-type are Base64 and Plain. Figure 12 shows an XML sample of an SSH dynamic target using the Base64 option with an encrypted password. Figure 12
XML sample of SSH dynamic target using the Base64 option
... server12200user1cGFzczE=pr1120 ...
Command encryption Command Line, SSH, Kerberized SSH, Telnet, Windows Command, and PowerShell adapters can use an encryption-type attribute with the element. The valid values for encryption-type are Base64 (or base64) or Plain (or plain). If no encryption-type is specified, the value is considered to be unencrypted (Plain). Figure 13 shows an XML sample of a command using the Base64 option with an encrypted password. Figure 13
XML sample of a command using the Base64 option
... bHM= ...
30
BMC Atrium Orchestrator Base Adapters User Guide
Command attribute for continuing execution after a command failure
Command attribute for continuing execution after a command failure Command Line, SSH, Kerberized SSH, Telnet, Windows Command, and PowerShell adapters can use a continue-on-failure attribute with the element. With this attribute set to true, if a command fails to execute, the subsequent command is executed. In the absence of this attribute, or if this attribute is set to false, if a command fails to execute, the adapter response is an error message and subsequent commands are not executed. Figure 14 shows an XML sample of the continue-on-failure attribute. Figure 14
XML sample of continue-on-failure attribute
... first commandsecond commandthird command ...
Command attribute for disabling linetermination character Command Line, SSH, Kerberized SSH, Telnet, and Windows Command adapters can use a disable-line-termination attribute with the element. You can use this attribute for menu commands that need to be sent as a single character without any line termination. With this attribute set to true, the command is sent without any termination character. In the absence of this attribute, or with this attribute set to false, the specified or default (\n) line termination character is sent with the command. Figure 15 shows an XML sample of the disable-line-termination attribute. Figure 15
XML sample of disable-line-termination attribute
... CTRL-D ...
Chapter 2
Terminal adapter features
31
Command attribute for ignoring a command response
Command attribute for ignoring a command response SSH, Kerberized SSH, Telnet, and PowerShell adapters can use an ignore-response attribute with the element. Use this attribute to skip the processing of a response to a command. With this attribute set to true, any command response is ignored and the next command (if any) is executed. The ignored response appears in the response for the subsequent command. Typically, you would use this attribute when you issue an exit command is issued to log out of a shell. In the absence of this attribute, or with a value of false, any command response is processed normally. Figure 16 shows an XML sample of the ignore-response attribute. Figure 16
XML sample of ignore-response attribute
... exit ...
Command attribute for using a special character Command Line, SSH, Kerberized SSH, Telnet, and Windows Command adapters can use an is-special-character attribute with the element. You can use this attribute to define a command for Escape (ESC), Line Feed (LF), or Carriage Return (CR) by setting it to true. In the absence of this attribute, if you set it to false, you can specify any valid OS command. Figure 17 shows an XML sample of the is-special-character attribute. Figure 17
XML sample of is-special-character attribute
... ESC ...
32
BMC Atrium Orchestrator Base Adapters User Guide
Persistent connectivity
Persistent connectivity SSH, Kerberized SSH2, Telnet, SCP, FTP, SFTP, and Session-based CLI adapters can use a feature that permits a connection to persist for multiple requests within a process. A connection is named when established, and subsequent requests can specify this named connection to be reused for a request. The connection remains available until the end of the process, or until the connection is terminated with a element. The named connection is defined in an adapter request within the block by using a block that contains a tag and a tag. The tag is required. The tag is optional, and its default value is false, maintaining the connection. The SSH, SCP, FTP, and SFTP adapters also contain a tag that specifies the time (in seconds) for which a named connection should persist. The named connection is an optional function. If there is no block, the connection opens and closes within the request and must be reopened for each subsequent request of that target. Figure 18 shows an XML sample of a named connection used in conjunction with a dynamic target. This connection terminates upon completion of the request. Figure 18
XML sample of a named connection used in conjunction with a dynamic target
When using a named connection with a dynamic target, you must define the dynamic target completely in each request. You cannot reference its as a name attribute with the in subsequent requests. Only targets defined in the adapter configuration can be referenced with a name attribute in an adapter request.
Chapter 2
Terminal adapter features
33
Proxy commands
Figure 19 shows an XML sample of a named connection used in conjunction with a target name reference from the adapter configuration. In the absence of the element, this connection remains open upon completion of the request. Figure 19
XML sample of a named connection in conjunction with a target name reference
... target2_connection ...
Each subsequent request that uses a named connection is configured in the same manner, with either a complete dynamic target or a target name reference to the adapter configuration that contains a block. The connection is reused if open, or reestablished if it has been closed. Connections can persist to called processes below the primary process layer. The connection is terminated at the endpoint of the primary process layer.
Proxy commands SSH, Kerberized SSH, and Telnet adapters can use a pass-through function for command execution that enables you to connect to a secondary target from the initial host by using Telnet or SSH. With this connection, you can execute commands on the secondary target.
NOTE To use this functionality with SSH, you must use prompts. With unprompted SSH, each command is executed independently, not successively, as is needed to log on to the remote host. Additional options assist the command execution on secondary targets. Commands issued on a secondary host can be contained in tags. The command has an optional attribute, verify-os, which you can use to obtain the operating system type and version on the secondary host. This is an important function if FAT commands are used and the operating system on the secondary system is different from the initial host.
34
BMC Atrium Orchestrator Base Adapters User Guide
Known hosts
The ignore-exit-code attribute of the element prevents an exit code from being obtained after executing the command. By default, an exit code request is issued after each command. This can cause problems if the retrieval of an exit code is interpreted as a user name, password, prompt, or other input during the authentication process. You must use this attribute when the command that is automatically issued to obtain an exit code could be misinterpreted and would interfere with subsequent commands. As with all elements, the prompt attribute indicates the expected prompt returned upon execution of the command. The subsequent command is executed at this returned prompt. Prompts specified in a attribute are typically defined in a block in the request. If a prompt not defined in the block is used as an attribute value for a , the actual attribute value is used as the prompt. In the following example, if a value for prompt1 has not been defined in the block, prompt1 is used as the prompt for the command: command 1,
Figure 20 shows an XML sample of a request that uses the proxy command features. Figure 20
XML sample of a request that uses the proxy command features
Known hosts SSH, SCP, and SFTP adapters use functions that verify the encryption key when opening a connection. Table 5 describes optional elements that you can use in both adapter configurations and dynamic targets to verify the encryption key when opening a connection.
Chapter 2
Terminal adapter features
35
Public key authentication
Table 5
Optional elements for verifying the encryption key
Element
Description
Identifies the path to the local known_hosts file This file is used when verifying the key. Default value: homeDir/.ssh/known_hosts.
Specifies whether a connection must continue if the key verification fails Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error.
Specifies the preference of the algorithm used to encrypt the public key Valid values: ssh-dss, ssh-rsa (default)
Figure 21 shows an XML sample using the optional elements described in Table 5 on page 36. Figure 21
Public key authentication SSH, SCP, and SFTP adapters can use public-key-based authentication when servicing adapter requests. This feature is an alternative to password-based authentication. To use public key authentication, define the file location of the SSH key file and an associated pass phrase. Table 6 describes optional elements that you can use for the adapter configuration and dynamic targets in the adapter requests. The default authentication method is password-based; if a element is present in an adapter configuration or the dynamic target node of an adapter request, password authentication is used, regardless of the presence of and elements. If the element is omitted, the and elements are used.
36
BMC Atrium Orchestrator Base Adapters User Guide
Verification of OS
Table 6
Optional elements for public key authentication
Element
Description
Identifies the path and the file name for the local SSH key file This file is used when performing public key authentication. This path and file must exist on the peer servicing the adapter request.
Identifies the pass phrase that protects the private key file This element can contain an attribute of encryption-type to indicate whether the pass phrase provided is encrypted. Valid values (encryption type): Base64, Plain (default) (unencrypted)
Figure 22 shows an XML sample using the optional elements described in Table 6 on page 37. Figure 22
XML sample of public key authentication optional elements
Verification of OS Command Line, SSH, Kerberized SSH, and Telnet adapters can use a element in the adapter configuration or in a dynamic target definition within the adapter request. This element determines whether the adapter must determine the target OS type soon after authentication is complete or a connection is established. This element has a default value of true, indicating that the OS is verified. If the OS is verified, exit codes are returned by the executed commands. If the element is present with a value of false, the OS is not verified and none of the commands executed return an exit code.
Chapter 2
Terminal adapter features
37
Character set
Figure 23 shows an XML sample using the element in an adapter configuration. Figure 23
XML sample of element in an adapter configuration
... false ...
Character set Character sets are identifiers that describe a series of universal characters. The following adapters can use a element in the adapter configuration or in a dynamic target definition within the adapter request: ■ ■ ■ ■ ■ ■ ■ ■ ■
FTP JMS Actor JMS Monitor File Adapter Command Line SSH Telnet FTP SFTP
Figure 24 shows an XML sample using the character-set element in an adapter configuration. Figure 24
XML sample of the
Shift_JIS
Command group The tag has an optional attribute, in which multiple commands can be executed in the group. This is an important function if you use FAT commands and the operating system on the secondary system is different from the initial host. The Command line adapter supports this feature.
38
BMC Atrium Orchestrator Base Adapters User Guide
env-variables
Figure 25 shows an XML sample using the command-group feature in an adapter request. Figure 25
XML sample of the command-group feature in an adapter request
notepad.exe
env-variables Env-variables specify environment variables (name-value pairs). The Command line adapter supports this feature. Figure 26 shows an XML sample using the env-variables feature in an adapter request. Figure 26
XML sample of the env-variables feature in an adapter request
New_Variable11New_varaible11_value
executable directory Executable directory specifies the complete path to the directory in which the element is located. The Windows Command line adapter supports this feature. The default path is the same as the location of the adapter libraries: $AO_HOME/server/Grid/library/adapters/roadapter-windows-command-[version].
This element is applicable in default mode only.
Chapter 2
Terminal adapter features
39
Terminal adapters feature overview table
Figure 27 shows an XML sample using the executable-directory feature in an adapter configuration. Figure 27
XML sample of the executable-directory feature in an adapter configuration
Terminal adapters feature overview table Table 7 provides a quick reference of the features available for each terminal adapter. Table 7
Terminal adapter feature overview Command File Line SSH
Kerberized SSH Telnet SCP
FTP
Windows SFTP Command PowerShell
Multiple configuration nodes
N
N
Y
Y
Y
Y
Y
Y
Y
Y
Dynamic targets
N
N
Y
Y
Y
Y
Y
Y
Y
Y
Command attribute (working-dir)
N
Y
N
N
N
N
N
N
Y
Y
Command attribute (command-dir)
N
Y
N
N
N
N
N
N
Y
N
Command attributes (timeout-secs)
N
Y
Y
Y
Y
Y
Y
Y
Y
Y
FAT command
N
Y
Y
Y
Y
N
N
N
Y
Y
Password attributes (encryption-type)
N
N
Y
Y
Y
Y
Y
Y
Y
Y
Command attributes (encryption-type)
N
Y
Y
Y
Y
N
N
N
Y
Y
Command attributes (continue-on-failure)
N
Y
Y
Y
Y
N
N
N
Y
Y
Command attributes (disable-linetermination)
N
Y
Y
Y
Y
N
N
N
Y
N
Command attributes (ignore-response)
N
N
Y
Y
Y
N
N
N
N
Y
Feature
40
BMC Atrium Orchestrator Base Adapters User Guide
Terminal adapters feature overview table
Table 7
Terminal adapter feature overview Command File Line SSH
Kerberized SSH Telnet SCP
FTP
Windows SFTP Command PowerShell
Command attributes (is-special-character)
N
Y
Y
Y
Y
N
N
N
Y
N
Persistent connectivity
N
N
Y
Y
Y
Y
Y
Y
N
N
Proxy commands
N
N
Y
Y
Y
N
N
N
N
N
Known hosts
N
N
Y
N
N
Y
N
Y
N
N
Public key authentication
N
N
Y
N
N
Y
Y
N
N
Verification of OS
N
Y
Y
Y
Y
Y
N
N
N
N
Character set
Y
Y
Y
N
Y
Y
Y
N
N
Command group
N
Y
N
N
N
N
N
N
N
N
Env variables
N
Y
N
N
N
N
N
N
N
N
Executable directory
N
N
N
N
N
N
N
N
Y
N
Feature
NOTE In Linux environments, BMC recommends that you set the value of the color attribute to none with a command to prevent erroneous control characters in the command output (ls--color=none)
File adapter The File adapter is an actor adapter that performs read, write, append, and delete functions on a file. Using a file name and action (read, write, append, or delete) arguments, the File adapter performs the specified action on the specified file, and in the case of write and append, using the lines provided. The File adapter does not need a configuration node but, you must configure the adapter in Grid Manager.
NOTE The File adapter performs actions on the peer that executes the process. You cannot designate remote hosts for File adapter requests.
File adapter configuration The File adapter does not require a configuration node, but the XML element is needed for the Properties field in Grid Manager adapter configuration. Adapter type: ro-adapter-file[version] Default adapter name: FileAdapter Figure 28 shows an XML sample of an adapter configuration for the File adapter. Figure 28
XML sample of the File adapter configuration
Available actions File adapter request
46
File adapter request with read action
File adapter response with read action
File adapter request with write action
File adapter response with write action
File adapter request with append action
File adapter response with append action
File adapter request with a delete action
File adapter response with a delete action
BMC Atrium Orchestrator Base Adapters User Guide
File adapter request
File adapter request The File adapter uses one of the four actions, read, write, append, or delete. The File adapter requests and responses are action-specific. The samples and the templates for each action supported by the File adapter are detailed in the following sections. You can specify the required action in the adapter’s Action field of the property panel for the Call Adapter activity. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
File adapter request with read action When you create the adapter request in the Transform Editor, you must enclose this template within tags. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. Table 8 describes the adapter request elements for the File adapter with read action. Table 8
Adapter request elements for the File adapter with read action
Element
Description
Required
Specifies the absolute path, including the file name, of the file to be read
Yes
CharSet is also called Character Set that includes identifiers describing a series of universal characters
No
No
Specifies the supporting CharSet CharSet is also called Character Set that includes identifiers describing a series of universal characters
Specifies the elements that provide the tokenization details
No
If no value is provided, no tokenization occurs. To use the block, the value must be TEXT. Specifies the character used to mark the separation of fields on a line
Conditional
This element is required when the tokenize element is used. Special characters must be preceded by a \ to avoid XML parsing errors. See Table 9 for the samples. This element is required with the element.
Determines whether the first line of the file is to be treated as a header
No
Valid values: true, false (default)
Chapter 3 Using Terminal adapters
47
File adapter request with read action
Table 9 lists the sample delimiter formats that are valid for the File adapter. Table 9
Sample delimiter formats
Delimiter
Format
tab
\t
pipe
\|
asterisk
\*
dash
\-
comma
, or \,
semi colon
; or \;
underscore
_ or \_
dollar sign
\$
Figure 29 shows an XML template of the adapter request for a File adapter with read action. Figure 29
XML template of the File adapter request with read action
Figure 30 shows a sample adapter request for the File adapter with read action. Figure 30
XML sample of the File adapter request with read action /tmp/readfile.txtShift_JIStext,true
48
BMC Atrium Orchestrator Base Adapters User Guide
File adapter response with read action
File adapter response with read action The read action request for a File adapter returns an adapter response that contains the lines read by the adapter request. The possible formats depend on whether the request was executed on an XML file, included tokenization, or whether the tokenized lines included a header line. Tokenization is the process of breaking a stream of text up into meaningful elements called tokens. The sample responses are provided for each option. Each sample for a text file type uses the same sample data file provided. Table 10 describes the elements of a File adapter response to a request with read action. Table 10
Elements of a File adapter response to a request with read action—XML file type
Element
Description
<metadata>
Contains the summary information for the request
Indicates whether the command executed successfully Valid values: success, error
Indicates the error message returned when the value of the element is error When the value of the element is success, this element is absent.
Specifies the duration of the command execution, in milliseconds
Figure 59 shows a sample configuration of the Windows Session-based CLI adapter to clear environment variables. Figure 59
XML sample of the Session-based CLI adapter configuration to clear environment variables
New_Variable11New_Variable22
Chapter 3 Using Terminal adapters
75
UNIX Session-based CLI adapter configuration
Figure 60 shows a sample configuration of the Windows Session-based CLI with character-set. Figure 60
XML sample of the Session-based CLI configuration with character-set
cmd.exeShift_JIS
UNIX Session-based CLI adapter configuration In a UNIX environment, you provide the initial command as a Telnet command, which opens a sub-shell. Subsequent commands execute in the sub-shell in a session. You can specify the command at the command level or at the command-group level. The console prompt appears when the system is waiting for a command. This prompt indicates that a command has been executed. Figure 61 shows a sample configuration of the UNIX Session-based CLI adapter with prompt. Figure 61
XML sample of the Session-based CLI adapter configuration with prompt—UNIX platform
telnet -l test aotest$
Figure 62 shows a sample configuration of the UNIX Session-based CLI adapter with expect. Figure 62
XML sample of the Session-based Command Line configuration with expect—UNIX platform
telnet -l test aotest$
76
BMC Atrium Orchestrator Base Adapters User Guide
Session-based CLI adapter requests and responses
Session-based CLI adapter requests and responses Figure 63 shows the adapter request for the Session-based CLI adapter (Windows).
TIP The working-dir command works for the first command in the Session-based approach. After the initial command, if the directory changes, you must use the change directory command (cd) to alter the directory location.
Figure 63
XML sample of the Session-based CLI adapter request—Windows
Figure 68 shows an adapter request for the Session-based CLI adapter for persistent connectivity (UNIX). Figure 68
XML sample of the Session-based CLI adapter request with persistent connectivity—UNIX
my_connectionfalsels -lpwd
Figure 69 illustrates the adapter response for the Session-based CLI adapter for persistent connectivity (UNIX).
80
BMC Atrium Orchestrator Base Adapters User Guide
run-as support in Command Line adapter
Figure 69
XML sample of the Session-based CLI adapter response with persistent connectivity— UNIX platform
<metadata> success <metadata> Linux2.6.9-22.ELsmpi386success <metadata> ls -l/241130success <metadata> pwd1900success
2008 var
run-as support in Command Line adapter The run-as feature enables you to execute any program or command using a different user account other than the current logged in user (you). The run-as feature enables you to perform the following tasks: ■ ■
Switch between different accounts and execute commands or programs Execute any command with elevated or restricted privileges
Chapter 3 Using Terminal adapters
81
run-as support in Command Line adapter
The run-as feature in Command Line adapter is supported on the following platforms: ■ run-as support on Windows ■ run-as support on Linux/UNIX ■ run-as with Kerberos authentication support on Linux/UNIX Support for the run-as feature in the Command Line adapter is platform dependent.
run-as support on Windows run-as support on Windows enables you to execute any program (.exe) using a different user account other than the currently logged in user (you). To use this feature, set the following attributes: ■
run-as
■
user-name
■
password wait-for-command-output
■
NOTE run-as support on Windows does not support execution of DOS commands.
Before you begin The Command Line adapter uses the PsExec utility to support the run-as feature on Windows platforms. To use the run-as feature on Windows, perform the following steps:
1 Download the PsExec utility that is freely available at http://technet.microsoft.com/hi-in/sysinternals/bb897553(en-us).aspx.
2 Unbundle the zip file and set the unbundled location to the system's path environment variable.
3 Restart the grid.
82
BMC Atrium Orchestrator Base Adapters User Guide
run-as support in Command Line adapter
Table 24 describes the adapter request attributes for the Command Line adapter to support the run-as feature on Windows. Table 24
Adapter request attributes for the run-as feature in the Command Line adapter— Windows
Attribute
Description
Required
run-as
Specifies a Boolean value to execute the command as a different user
No
This attribute must be set to true to execute the command as a different user. Valid values: true, false (default) user-name
Specifies the user name (of an existing user) used to execute the program
Conditional
This attribute is required if you set the run-as attribute to true. password
Specifies the password for the user account specified in the user-name
Conditional
This attribute is required if you set the run-as attribute to true. wait-forcommandoutput
Specifies whether to wait for the process or command output or until the adapter times-out
No
When this value is set to true, the adapter waits for the process output or the adapter time-out duration. When you set this value to false, the adapter returns the execution status of the command. Valid values: true, false (default) Note: BMC recommends that you do not set this attribute to execute programs (.exe) for which no output is expected. For example, notepad.exe.
Figure 70 shows a sample adapter request for the Command Line adapter to support the run-as feature on Windows using simple commands. Figure 70
XML sample of the Command Line adapter request for the run-as feature (Windows)— simple commands format
ipconfig
Figure 72 shows a sample adapter response for the Command Line adapter to support the run-as feature on Windows using simple commands.
Chapter 3 Using Terminal adapters
83
run-as support in Command Line adapter
Figure 71
XML sample of the Command Line adapter response for the run-as feature (Windows)— simple commands format (part 1 of 2)
<metadata> success <metadata> Windows XP5.1x86success <metadata> ipconfig3400success
84
BMC Atrium Orchestrator Base Adapters User Guide
run-as support in Command Line adapter
Figure 72
XML sample of the Command Line adapter response for the run-as feature (Windows)— simple commands format (part 2 of 2)
Figure 73 shows a sample adapter request for the Command Line adapter to support the run-as feature on Windows using a command group. Figure 73
XML sample of the Command Line adapter request for the run-as feature (Windows)— command group format
notepad.exe
Figure 74 shows a sample adapter response for the Command Line adapter to support the run-as feature on Windows using a command group. Figure 74
XML sample of the Command Line adapter response for the run-as feature (Windows)— command group format (part 1 of 2)
<metadata> success <metadata> Windows XP5.1x86success <metadata> notepad.exe2400success
Figure 76 shows a sample adapter request for the Command Line adapter to support the run-as feature on Windows using FAT commands. Figure 76
XML sample of the Command Line adapter request for the run-as feature (Windows)— FAT command format
ipconfig
Figure 77 shows a sample adapter response for the Command Line adapter to support the run-as feature on Windows using FAT commands. Figure 77
XML sample of the Command Line adapter response for the run-as feature (Windows)— FAT command format (part 1 of 2)
<metadata> success <metadata> Windows XP5.1x86success
86
BMC Atrium Orchestrator Base Adapters User Guide
run-as support in Command Line adapter
Figure 77
XML sample of the Command Line adapter response for the run-as feature (Windows)— FAT command format (part 2 of 2)
<metadata> ipconfig1900success
run-as support on Linux/UNIX run-as support on Linux/UNIX enables you to execute any program or command using a different user account other than the currently logged in user (you). To use this feature, set the following attributes: ■
run-as
■
user-name
■
password
Before you begin The Command Line adapter uses the sudo command to support the run-as feature. To use the sudo command to support run-as on Linux or UNIX platform, an administrator must add an entry for users with the level of authorization in the /etc/sudoers file.
Chapter 3 Using Terminal adapters
87
run-as support in Command Line adapter
Table 25 describes the adapter request attributes for the Command Line adapter to support the run-as feature on Linux or UNIX. Table 25
Adapter request attributes for the run-as feature in the Command Line adapter—Linux or UNIX
Attribute
Description
Required
run-as
Specifies a Boolean value to execute the command as a different user
No
This attribute must be set to true to execute the command as a different user. Valid values: true, false (default) user-name
Specifies the user name (of an existing user) used to execute the program
Conditional
This attribute is required if you set the run-as attribute to true. password
Specifies the password of a user who is currently logged on
Conditional
This is the password of a user with which the BMC Atrium Orchestrator service (grid) runs. This attribute is required if you set the run-as attribute to true.
Figure 78 shows a sample adapter request for the Command Line adapter to support the run-as feature on Linux or UNIX using simple commands. Figure 78
XML sample of the Command Line adapter request for the run-as feature (Linux or UNIX)—simple commands format
whoamiwhoami
Figure 79 shows a sample adapter response for the Command Line adapter to support the run-as feature on Linux or UNIX using simple commands.
88
BMC Atrium Orchestrator Base Adapters User Guide
run-as support in Command Line adapter
Figure 79
XML sample of the Command Line adapter response for the run-as feature (Linux or UNIX)—simple commands format
run-as Kerberos authentication support on Linux/UNIX run-as support with Kerberos authentication on Linux/UNIX enables you to execute any program or command using a different user account other than the currently logged in user (you). The user account is verified using Kerberos authentication mechanism. To use this feature, set the following attributes: ■
run-as
■
user-name
■
krb-authentication krb-command krb-options
■ ■
Before you begin The Command Line adapter uses ksu as the default command to support the run-as feature with Kerberos authentication on Linux or UNIX. ksu is part of Kerberos applications installed with Kerberos V5 (MIT). If you have a different Kerberos authentication mechanism installed on your system that has its own set of Kerberos applications supported (similar to ksu), use the krbcommand and krb-options attributes in the adapter request. Doing this prevents the Command Line adapter from using ksu, the default command.
Chapter 3 Using Terminal adapters
91
run-as support in Command Line adapter
Before executing any command or program using run-as with Kerberos authentication, you must acquire the required Kerberos ticket. If the required Kerberos ticket is not available in the cache, the adapter request fails with a timeout error. Currently, the adapter does not support setting the password for acquiring the required Kerberos ticket.
NOTE Solaris computers have SEAM Kerberos installed that does not support ksu. You need to first install Kerberos V5 to use the run-as with Kerberos authentication feature on Solaris.
Table 26 describes the adapter request attributes for the Command Line adapter to support the run-as with Kerberos authentication feature on Linux or UNIX. Table 26
Adapter request attributes for the run-as with Kerberos authentication feature in the Command Line adapter—Linux or UNIX (part 1 of 2)
Attribute
Description
Required
run-as
Specifies a Boolean value to execute the command as a different user
No
This attribute must be set to true to execute the command as a different user. Valid values: true, false (default) user-name
Specifies the name of an existing user using which the program or process is executed
Conditional
This attribute is required if the run-as attribute is set to true. No krbSpecifies a Boolean value to execute the command as a different user authenticat using Kerberos authentication ion This attribute must be set to true to execute the command as a different user using a Kerberos ticket to authenticate the user. Valid values: true, false (default)
92
BMC Atrium Orchestrator Base Adapters User Guide
run-as support in Command Line adapter
Table 26 Attribute
Adapter request attributes for the run-as with Kerberos authentication feature in the Command Line adapter—Linux or UNIX (part 2 of 2) Description
Required
krb-command Specifies the command used by the adapter to support run-as with Kerberos authentication
No
Use this attribute to switch to a different command similar to ksu (for example, kuu). Default value: ksu krb-options Specifies the krb-options for the krb-command
No
Valid values: -n principal_name: Specifies a Kerberos principal name for a specified krb user -c cache_name: Specifies a cache name (for example, FILE:/tmp/my_cache) -k: Specifies that the target cache must not be deleted upon termination of the target shell or a command If you do not specify the -k option, the adapter deletes the target cache. Note: The above command options are specific to ksu. You can set krboptions specific to the krb-command that you specify.
Figure 84 shows a sample adapter request for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using simple commands. Figure 84
XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)—simple commands format
whoamiwhoami
Figure 85 shows a sample adapter response for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using simple commands.
Chapter 3 Using Terminal adapters
93
run-as support in Command Line adapter
Figure 85
XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)—simple commands format
Figure 86 shows a sample adapter request for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using a command group. Figure 86
XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)—command group format
whoami;pwd whoami
Figure 87 shows a sample adapter response (Linux) for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using a command group.
Chapter 3 Using Terminal adapters
95
run-as support in Command Line adapter
Figure 87
XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)—command group format (part 1 of 2)
XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)—command group format (part 2 of 2)
whoami55200success
Figure 88 shows a sample adapter request for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using FAT commands. Figure 88
XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)—FAT command format
whoami
Figure 89 shows a sample adapter response for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using FAT commands.
Chapter 3 Using Terminal adapters
97
SSH adapter
Figure 89
XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)—FAT command format
SSH adapter The SSH adapter is used to execute commands on a remote host using the SSH protocol. With this adapter, the use of a prompt is optional. If a element is not defined, each command is executed in a separate session, as if each command is executed in a new command shell. Each command is executed independently, without any effect on subsequent commands. With the definition of a element, commands are executed in a sequence, in the same login shell. Executing a command with non-prompt-based SSH is similar to appending the command to a Linux or Solaris client's command (ssh user1@server1 ls). This results in an environment that is different from prompt-based SSH, in which the command is executed within the context of a login shell. The SSH adapter can use the common features described in“Terminal adapter features” on page 23.
98
BMC Atrium Orchestrator Base Adapters User Guide
SSH adapter configuration
SSH adapter configuration For the SSH adapter, in addition to target computers defined in the adapter configuration, you can define dynamic target computers in each adapter request. If a dynamic target is defined in the SSH adapter request, use a configuration node, , in the adapter configuration. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-ssh[version] Default adapter name: SSHAdapter To configure the SSH adapter, see “Configuring the adapter” on page 14. Table 27 describes the adapter configuration elements for the SSH adapter that you can specify by using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the "UI label" column. Table 27
Configuration node elements of the SSH adapter (part 1 of 4)
UI label
Element
Description
Required
Target
Specifies the host name or the IP address of the remote host computer
Yes
Port
Specifies the port on which the remote host listens
No
Default value: 22 User Name
Specifies the user name required for remote host authentication
Yes
Password
Specifies the password corresponding to the specified user name
No
If this value is not defined, the element can be used. This element can contain a encryption-type attribute to indicate that the specified password is encrypted. Valid values: Base64, Plain (non-encrypted) (default) Note: If you provide the and elements in the Grid Configuration, the approach is used and the element is ignored.
Chapter 3 Using Terminal adapters
99
SSH adapter configuration
Table 27
Configuration node elements of the SSH adapter (part 2 of 4)
UI label
Element
Description
Required
Private Key File
Identifies the path and file name of the local SSH key file
Conditional
This file is used for public key authentication. The path and file must exist on the peer servicing the adapter request. This element is used if the element is not provided. Note: If you provide the and elements in the Grid Configuration, the approach is used and the element is ignored. Pass Phrase
Identifies the pass phrase that protects the private key file
Conditional
This element might be used if the element is not provided. This element can contain a encryption-type attribute to indicate whether the passphrase provided is encrypted. Valid values (encryption type): Base64, Plain (unencrypted) (default) Prompt
Specifies the console prompt displayed when the system is waiting for a command (the terminating string, typically ending with $, >, or # ) The element is required to use the proxy command feature. Each command executes in a separate session, as if each command is executing in a new command shell. This prompt indicates the completion of the command execution. It must be unique, not matching the potential command output to prevent parsing issues.
100
BMC Atrium Orchestrator Base Adapters User Guide
Conditional
SSH adapter configuration
Table 27
Configuration node elements of the SSH adapter (part 3 of 4)
UI label
Element
Description
Required
Timeout Secs
Specifies the time, in seconds, to wait for the expected prompt to be returned
No
If the expected prompt is not returned before the specified period has elapsed, an error message is returned. You need this element even if you specify the element defined in the target block or the element defined in the command block. This element is used for the echo $? commands to pick up the exit code of the commands, and is also used as the timeout for all the commands run to determine the kind of operating system to which the adapter is connected. This element is not used when connecting to or disconnecting from the adapter. Default value: 60 seconds Known Hosts
Identifies the path to the local known_hosts file
No
This file is used to perform key verification. Default value: home_dir/.ssh/known_hosts
Allow Unknown Hosts
Determines whether a connection must continue if the key verification fails
No
Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. Preferred Pk Algorithm
Specifies the preference of the algorithm used to encrypt the public key
No
Valid values: ssh-dss, ssh-rsa (default)
Chapter 3
Using Terminal adapters
101
SSH adapter configuration
Table 27
Configuration node elements of the SSH adapter (part 4 of 4)
UI label
Element
Description
Required
Establish Connection Timeout Secs
Specifies the time, in seconds, that the adapter waits for No user authentication on the target server If authentication is not successful within the specified time, an error message is returned. Even if the adapter is busy, if a command takes longer than this time to finish and returns no progress messages or any input of any type for longer than the , the adapter disconnects. The adapter disconnects after even if you specify the to be longer. For example, if is 60 seconds, and is 1800 seconds, but the command returns nothing while it runs, the adapter times out at 60 seconds. However, if the command returns some progress indication (messages of each step it does, dots, and so on), the adapter does not disconnect until 1800 seconds. Default value: 60 seconds
Network Environment
Solaris 9
No
Valid values: true, false (default) Note: The value must be false when connecting to network devices. Line Termination
SSH command
No
Typically, the value is a hexadecimal value for \r (&# D;) or \n (&# A;). Default value: No line termination character is assigned Character Set
Specifies the supporting CharSet
No
CharSet is also called Character set and includes identifiers describing a series of universal characters. Default value: ISO-8859-2
Figure 90 on page 103 and Figure 91 on page 103 show the XML templates for SSH adapter configurations.
102
BMC Atrium Orchestrator Base Adapters User Guide
SSH adapter configuration
Figure 90
XML template of the SSH adapter configuration—password approach
Figure 91
XML template of the SSH adapter configuration—private-key-file approach
NOTE BMC recommends that you use the password or the private-key-file approach; not both the approaches together.
Figure 92 shows an XML sample for SSH adapter configuration with CharSet. Figure 92
XML sample of the SSH adapter configuration with CharSet
server1testuser22abctrueShift_JIS
Chapter 3
Using Terminal adapters
103
SSH adapter request
SSH adapter request The 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 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 block from the adapter request. If a block is not provided, the default target from the adapter configuration is used. When the adapter request is formed using the Advanced Transform Editor, you must enclose this template within tags. BMC recommends that you do not include unused elements in the adapter configuration because they elements might cause errors. Table 28 describes the adapter request elements for the SSH adapter. Table 28
Adapter request elements—SSH adapter (part 1 of 5)
Element
Description
Required
Contains any additional elements that might be needed to execute the commands properly
Conditional
The element is required when one or more elements are defined.
Specifies the console prompt displayed when the system is waiting for a command
No
The name attribute of this element is used to specify the value in a element. If not provided, the defined in the configuration node or the dynamic target computer is used. Note: This indicates the completion of the command execution. It must be unique, not matching potential command output to prevent parsing issues.
Contains the elements
Conditional
This element is required if a target is referenced or defined in the request.
Contains a name attribute referencing a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target is referenced or defined in the request. If not provided, the default target in the adapter configuration is used.
104
BMC Atrium Orchestrator Base Adapters User Guide
Conditional
SSH adapter request
Table 28
Adapter request elements—SSH adapter (part 2 of 5)
Element
Description
Required
Specifies the host name or the IP address of the remote host
Conditional
This element applies to a dynamic target computer and is required when defining a dynamic target.
Conditional
Specifies the port on which the remote host listens This element applies to a dynamic target. Default value: 22
Specifies the user name to be used for remote host authentication
Conditional
This element applies to a dynamic target and is required when defining a dynamic target.
Specifies the password corresponding to the provided
No
This element contains a password-encryption attribute that indicates whether the specified password is encrypted. Valid values: Base64 or Plain Default value: Plain (non-encrypted)
Enables the use of pseudo terminals when invoking SSH connections
Conditional
This element can only be used when the requests or connections do not contain any prompt elements Default value: true
Identifies the path and the file name for the local SSH key file
Conditional
This file is used when performing public key authentication. This element can be used if is not provided. The path and file must exist on the peer servicing the adapter request.
Conditional
Identifies the passphrase used to protect the private key file This element might be used if is not provided. This element can contain an attribute of encryption-type to indicate whether the passphrase provided is encrypted. Valid values (encryption type): Base64, Plain (unencrypted) (default)
Specifies the console prompt displayed when the system is waiting for a command
Conditional
This element applies to a dynamic target. It is required when using the proxy command feature. If this element is not supplied, each command executes in a separate session, as if the command is executed in a new command shell. This prompt indicates the completion of the command execution. It must be unique, not matching potential command output to prevent parsing issues.
Chapter 3
Using Terminal adapters
105
SSH adapter request
Table 28
Adapter request elements—SSH adapter (part 3 of 5)
Element
Description
Required
Specifies the time, in seconds, to wait for the expected prompt to be returned
Conditional
If the expected prompt is not returned before the specified period has elapsed, an error message is returned. You need this element even if you have specified the element defined in the target block or the element defined in the command block. This element is used for the echo $? commands to pick up the exit code of the commands, and is also used as the timeout for all the commands run to determine the kind of operating system to which the adapter is connected. This element is not used when connecting to or disconnecting from the adapter. Default value: 60 seconds
Identifies the path to the local known_hosts file
Conditional
This file is used to perform key verification. This element applies to a dynamic target. Default value: home_dir /.ssh/known_hosts
Determines whether a connection must continue if the key verification fails Conditional Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error.
Specifies the preference of the algorithm used to encrypt the public key This element applies to a dynamic target. Valid values: ssh-dss, ssh-rsa (default)
106
BMC Atrium Orchestrator Base Adapters User Guide
Conditional
SSH adapter request
Table 28
Adapter request elements—SSH adapter (part 4 of 5)
Element
Description
Required
Specifies the time, in seconds, that the adapter waits for user authentication No on the target server If authentication is not successful within the specified time, an error message is returned. Even if the adapter is busy, if a command takes longer than this time to finish and returns no progress messages or any input of any type for longer than the , the adapter disconnects. The adapter disconnects after even if you specify the to be longer. For example, if is 60 seconds, and is 1800 seconds, but the command returns nothing while it runs, the adapter times out at 60 seconds. However, if the command returns some progress indication (messages of each step it does, dots, and so on), the adapter does not disconnect until 1800 seconds. Default value: 60 seconds
be false when connecting to network devices. Valid values: true, false (default) command
No
Typically, the value is a hexadecimal value for \r (&# D;) or \n (&# A;) Default value: No line termination character is assigned
Specifies an XML document that contains the commands in the request
No
The wrapper process does not check the XML syntax.
Chapter 3
Using Terminal adapters
107
SSH adapter request
Table 28
Adapter request elements—SSH adapter (part 5 of 5)
Element
Description
Required
Specifies a string that has the commands and arguments for the request
No
Parameters other than the type may be provided when using the wrapper parameters like or . The default command is echo Success. If only the parameter is present, the workflow generates from the other command inputs and executes: cmd1 If only the parameter is present, the workflow uses the provided commands in the following format: cmd1cmd2cmd3 If both, and are present, the workflow executes the command provided by the user. Note: If you specify a value for in the block, this value is used. Else, the value for in the target block is used. For example, if you specify in the block, and in the target block, the command times out after 120 seconds. session is opened
No
This element is supported only in case of named connection (persistent connectivity) You can specify any command within this tag which will get executed while initializing the connection.
Specifies the supporting CharSet CharSet is also called Character set that includes identifiers describing a series of universal characters.
108
BMC Atrium Orchestrator Base Adapters User Guide
No
SSH adapter request
Figure 93 shows a sample XML template for the SSH adapter request. Figure 93
XML template of the SSH adapter request
Figure 94 shows an XML sample for the SSH adapter request using the command. Figure 94
XML sample of the SSH adapter request with use-pseudo-terminal command
server122userabctruetype testFile.txt
Chapter 3
Using Terminal adapters
109
SSH adapter request
Figure 95 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 BMC Atrium Orchestrator Development Studio. Figure 95
XML sample of the SSH adapter request
10.128.248.97user-name1password for user-name1true#22sshtarget_connectionfalseexport PS1="MYPROMPT $"pwdcd Desktoplogin:[email protected]'s password:#hostnamessh [email protected]root@123ls
Figure 96 shows an XML sample of the SSH adapter with CharSet. Figure 96
XML sample of the SSH adapter request with CharSet
server122userabctrueShift_JIStype testFile.txt
110
BMC Atrium Orchestrator Base Adapters User Guide
SSH adapter response
SSH adapter response The SSH adapter returns an adapter response that contains the details for the command executed by the adapter request. Table 29 describes the elements of an SSH adapter response. Table 29
Elements of an SSH adapter response (part 1 of 2)
Element
Description
Contains the request level summary information
Indicates the status of the request Valid values: success, error
Indicates the error message returned if the value of the element is error When the value of the 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 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 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
<metadata>
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
Chapter 3
Using Terminal adapters
111
SSH adapter response
Table 29
Elements of an SSH adapter response (part 2 of 2)
Element
Description
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. If the value returned for the is not 0 or 9999, the value of the element is error, and an 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 element is success, this element is absent.
