Adapter configuration elements and samples

BMC Server Automation versions 7.4 and later support the following types of Single Sign On (SSO) authentication:

Authentication based on Secure Remote Protocol (SRP) that uses the user_info.dat file or the user name and password

The BladeLogic Web Services interface (CLI tunnel) supports authentication based on SRP and is supported with BMC Server Automation version 8.1 and later.
Authentication based on Microsoft Active Directory and Kerberos

Adapter configuration elements

The following table describes the configuration elements for both the SRP and Active Directory and Kerberos authentication.

Adapter configuration elements for SSO authentication

UI Label	Element	Description	Required
None	`<env-variables>`	Contains one or more environment variables	No
None	`<env-variable>`	Contains the details for an environment variable (name-value pair)	No
None	`<name>`	Specifies the name of the environment variable to be set or cleared	No
None	`<value>`	Specifies the value corresponding to the name specified in the `<name>` environment variable Note: The environment variable is cleared if the value is empty or not specified.	No
Initial Command	`<initial-command>`	Specifies the initial command To use sessions and BMC BladeLogic SSO, you must specify the following initial command in the XML view for configuration: `<command prompt="prompt">nsh</command>` Valid values for `prompt`: `<hostname>%` `<hostname>#` Any other valid prompt	Yes
Prompt	`<prompt>`	Specifies the prompt to use for session capability Use the same prompt that appears on the NSH shell, `<hostname>%` or `<hostname>#,` or any other valid prompt.	Yes
Authentication Mechanism	`<authentication-mechanism>`	Specifies the authentication mechanism to use for acquiring BMC BladeLogic SSO credentials Valid values: SRP, AD_KERBEROS	Yes
Krb5 Conf File	`<krb5-conf-file>`	Specifies the krb5 configuration file used to acquire the SSO credentials for Active Directory and Kerberos based authentication By default, BMC Server Automation uses the settings specified in the config.properties file.	No
Login Conf File	`<login-conf-file>`	Specifies the login configuration file used to acquire the SSO credential for Active Directory and Kerberos based authentication By default, BMC Server Automation uses the settings specified in the config.properties file.	No
Executable Directory	`<executable-directory>`	Specifies the directory path containing the BMC BladeLogic executables: nsh, BLCLI, and bljython The path depends on the version of BMC BladeLogic: version 8.x = **BL_HOME\NSH\bin version 7.x = BL_HOME\OM\bin**	Yes
Script Directory	`<script-directory>`	Specifies the directory path containing the BLCLI wrapper scripts Do not include spaces in the path. Valid values: nsh, sh, bat, jy	Yes
Script Executable	`<script-executable>`	Specifies the executable to run blcli, nsh, sh, and bat scripts Default value: nsh	No
Jython Executable	`<jython-executable>`	Specifies the executable to run Jython based scripts Default value: bljython	No
Default User Role	`<default-user-role>`	Specifies the role this user is performing You can override this value in the adapter request.	No
Profile Name	`<profile-name>`	Specifies the profile name for which to acquire the SSO ticket	Yes
Blsso Cache Refresh Interval	`<blsso-cache-refresh-interval>`	Specifies the interval, in hours, to refresh the SSO credentials Default value: 9 hours Recommendation BMC recommends that you specify a value for `<blsso-cache-refresh-interval>` that is less than the BMC BladeLogic Server Automation application session expiry time. By default, BMC BladeLogic Server Automation 8.2 expires the cache after 10 hours. Therefore, setting `<blsso-cache-refresh-interval>` to 9 guarantees that the cache gets refreshed before the 10 hour BMC BladeLogic Server Automation expiry. For BMC BladeLogic Server Automation 8.2, setting `<blsso-cache-refresh-interval>` to a value greater than 9 might cause problems. You can also specify decimal values for the interval.	No
Blsso Cache Recovery Interval In Minutes	`<blsso-cache-recovery-interval-in-minutes>`	Specifies the interval, in minutes, to recover the state of the adapter Default value: 5 minutes The adapter tries to recover the state of the adapter from the FAULT state to the RUNNING state indefinitely at the specified interval.	No
Install Certificate	`<install-certificate>`	Specifies whether the adapter should install a BMC BladeLogic certificate, if the certificate is expired or not found Valid values: yes (default), no	No
Install Certificate Prompt	`<install-certificate-prompt>`	Specifies the console prompt that is displayed when the BMC BladeLogic system is waiting for user input to determine whether to accept the certificate Valid values: ?[yes\|no]:	No
Blcli Jvm Options	`<blcli-jvm-options>`	Sets the Java virtual machine (JVM) options to allocate memory in the BMC BladeLogic client The memory is allocated before any call to blcli_init, blcli_connect, or blcli_execute is executed. For example: If this element is set to Xmx512M, the max heap size is set to 512 MB before the JVM is created.	No
SRP User Name	`<srp-user-name>`	Specifies the user name used to acquire SSO credentials for SRP-based authentication	Conditional
SRP Password	`<srp-password>`	Specifies the password used to acquire SSO credentials for SRP-based authentication. If the password contains special characters, you must enclose the password in single quotation marks.	Conditional
User Credential File	`<user-credential-file>`	Specifies the user information certificate or data file to use for SRP-based authentication If you do not specify the `<srp-user-name>` and `<srp-password>` for SRP authentication, specify the location of the file to acquire session credentials.	Conditional
Credential Cache File	`<credential-cache-file>`	Specifies the file where the credential cache will be stored By default, BMC Server Automation stores the file in the user's home directory. For the example with kinituser, the file is stored in the C:\Documents and Settings\kinituser\Application Data\BladeLogic folder and the credential file is bl_sesscc.	No
Authentication Profile File	`<authentication-profile-file>`	Specifies the authentication file used for the BMC Server Automation SSO By default, for version 8.x, the **BL_HOME/NSH/bin/br/authenticationProfiles.xml file is used. By default, for version 7.x, the BL_HOME /OM/br/authenticationProfiles.xml** file is used. If you have a non-default authentication profile file, you must specify the location of the file in this element. See Troubleshooting the BMC Server Automation adapter for details.	No
Trusted Keystore File	`<trusted-keystore-file>`	Specifies the keystore file By default, BMC Server Automation uses the home directory to search for the trusted keystore file. If you have a non-default location for certificates, you must specify the location in this element.	No
Connection Ttl	`<connection-ttl>`	Specifies the lifetime of the cached connections (or the NSH process), in seconds Default value: 60 seconds	No
Timeout Secs	`<timeout-secs>`	Specifies the timeout interval for command execution in seconds Default value: 60 seconds	No
Is CLI Tunnel Enabled	`<is-cli-tunnel-enabled>`	Specifies whether CLI requests must be processed through the BMC BladeLogic Web Services interface. For details about how requests are executed when the cli tunnel is enabled, see Executing requests when the cli tunnel is enabled. Note:The `<is-cli-tunnel-enabled>` element and its child elements are valid for BMC Server Automation version 8.1 and later. For configuring the adapter with BMC Server Automation versions earlier than version 8.1, you must set the `<is-cli-tunnel-enabled>` element to false. Valid values: true, false (default)	No
None	`<cli-tunnel-properties>`	Contains the properties specific to the CLI tunnel	Conditional Required if the `<is-cli-tunnel-enabled>` element is set to true
None	`<application-server>`	Specifies the name of the BMC BladeLogic Application Server hosting the web service	Conditional Required if the `<is-cli-tunnel-enabled>` element is set to true
None	`<web-service-port>`	Specifies the port number on which the BMC BladeLogic web service is running on the BMC BladeLogic Application Server Default value: 9843	No.
None	`<user-name>`	Specifies the user name for authentication on the BMC BladeLogic Application Server	Conditional Required if the `<is-cli-tunnel-enabled>` element is set to true
None	`<password>`	Specifies the password corresponding to the user name	Conditional Required if the `<is-cli-tunnel-enabled>` element is set to true
None	`<role-name>`	Specifies the role that the current user would assume Default role: BLAdmins	No
None	`<session-refresh-interval>`	Specifies the interval, in minutes, at which the session ID required by the BMC BladeLogic Application Server is refreshed Valid value: Any integer Default value: 5 minutes The requests using BMC BladeLogic Web Services requires the session ID, and the session ID must be refreshed at regular intervals to ensure that the requests remain valid on the BMC BladeLogic application server.	No
None	`<enable-cli-with-tunnel>`	Specifies whether CLI requests must be enabled with the tunnel mode Valid values: true, false (default)	No
None	`<character-set>`	Specifies the supporting character set, which includes identifiers describing a series of universal characters Note: Use the `<character-set>` element only if the adapter requests and responses contain any other characters other than English. Valid values: ISO-8859-1, UTF-8	No

Executing requests when the CLI tunnel is enabled

Single CLI command in the request: The command is executed using the CLI tunnel approach.
Multiple CLI commands in the request: The first command is executed using the CLI tunnel approach and the remaining commands are ignored because of limitations in BMC Server Automation Web Services API.
Combination of NSH, JYTHON, or CLI commands in the request: The commands are executed using the traditional, CLI-based approach, which does not use the SOAP (CLI tunnel) interface.

Sample adapter configuration with SRP

The figure shows a sample configuration for both SRP-based authentication with srp-user-name and srp-password. In this sample, the adapter internally executes the blcred command:

blcred cred -acquire -profile defaultProfile -username username -password password

The blcred command acquires credentials and refreshes at intervals, based on the value of the <blsso-cache-refresh-interval> element in the adapter configuration. The following sample shows an adapter configuration with SRP and the adapter configured to interact with BMC Server Automation using the BladeLogic Web Services interface.

<config>
  <env-variables>
    <env-variable>
      <name>BL_AUTH_PROFILE_NAME</name>
      <value>BLAdmin</value>
    </env-variable>
    <env-variable>
      <name>BL_RBAC_ROLE</name>
      <value>RBACAdmins</value>
    </env-variable>
  </env-variables>
  <initial-command>
    <command prompt="%">nsh</command>
  </initial-command>
  <prompt>%</prompt>
  <authentication-mechanism>SRP</authentication-mechanism>
  <krb5-conf-file></krb5-conf-file>
  <login-conf-file></login-conf-file>
  <executable-directory>C:\Program Files\BMC Software\BladeLogic\8.1\NSH\bin</executable-directory>
  <script-directory>C:\scripts\BLOM\jy_Scripts</script-directory>
  <script-executable>nsh.exe</script-executable>
  <jython-executable>bljython.bat</jython-executable>
  <default-user-role>Admins</default-user-role>
  <profile-name>defaultProfile</profile-name>
  <blsso-cache-refresh-interval>1.5</blsso-cache-refresh-interval>
  <blsso-cache-recovery-interval-in-minutes>10</blsso-cache-recovery-interval-in-minutes>
  <install-certificate>yes</install-certificate>
  <install-certificate-prompt>?[yes|no]:</install-certificate-prompt>
  <blcli-jvm-options>-Xmx512M -XX:-HeapDumpOnOutOfMemoryError -Xms512m</blcli-jvm-options>
  <srp-user-name>Admin</srp-user-name>
  <srp-password>Admin</srp-password>
  <user-credential-file></user-credential-file>
  <credential-cache-file></credential-cache-file>
  <authentication-profile-file></authentication-profile-file>
  <trusted-keystore-file></trusted-keystore-file>
  <connection-ttl>30</connection-ttl>
  <timeout-secs>120</timeout-secs>
  <is-cli-tunnel-enabled>true</is-cli-tunnel-enabled>
  <cli-tunnel-properties>
    <application-server>blappserver</application-server>
    <web-service-port>9843</web-service-port>
    <user-name>Admin</user-name>
    <password>pass</password>
    <role-name>RBACAdmins</role-name>
    <session-refresh-interval>6</session-refresh-interval>
  </cli-tunnel-properties>
</config>

The following configuration snippet shows a sample configuration for SRP-based authentication using the user credentials in the user_info.dat file. In this sample, the adapter internally executes the following command to acquire credentials:

blcred cred -acquire -profile defaultProfile -i "C:\Documents and Settings\kinituser\Application Data\
BladeLogic\user\user_info.dat"

<config>
     <initial-command>
         <command prompt="%">nsh</command>
     </initial-command>
     <prompt>%</prompt>
     <authentication-mechanism>SRP</authentication-mechanism>
     <executable-directory>C:\Program Files\BMC Software\BladeLogic\8.0\NSH\bin</executable-directory>
     <script-directory>C:\scripts\BLOM\jy_Scripts</script-directory>
     <script-executable>nsh.exe</script-executable>
     <jython-executable>bljython.bat</jython-executable>
     <default-user-role>Admins</default-user-role>
     <profile-name>defaultProfile</profile-name>
     <blsso-cache-refresh-interval>1.5</blsso-cache-refresh-interval>
     <blsso-cache-recovery-interval-in-minutes>10</blsso-cache-recovery-interval-in-minutes>
     <install-certificate>yes</install-certificate>
     <install-certificate-prompt>?[yes|no]:</install-certificate-prompt>
     <blcli-jvm-options>-Xmx512M -XX:-HeapDumpOnOutOfMemoryError -Xms512m</blcli-jvm-options>
     <user-credential-file>C:\Documents and Settings\kinituser\Application Data\BladeLogic\user\
user_info.dat</user-credential-file>
     <connection-ttl>30</connection-ttl>
     <timeout-secs>120</timeout-secs>
     <is-cli-tunnel-enabled>false</is-cli-tunnel-enabled>
</config>

Sample adapter configuration with Active Directory and Kerberos

This sample code illustrates a configuration with Active Directory and Kerberos authentication. In this sample, the adapter internally executes the following command to acquire the credentials.

blcred cred -acquire -profile name

The adapter refreshes the credentials according to the value specified in the <blsso-cache-refresh-interval> element.

<config>
     <initial-command>
         <command prompt="%">nsh</command>
     </initial-command>
     <prompt>%</prompt>
     <authentication-mechanism>AD_KERBEROS</authentication-mechanism>
     <executable-directory>C:\Program Files\BMC Software\BladeLogic\8.0\NSH\bin</executable-directory>
     <script-directory>C:\scripts\BLOM\jy_Scripts</script-directory>
     <script-executable>nsh.exe</script-executable>
     <jython-executable>bljython.bat</jython-executable>
     <default-user-role>Admins</default-user-role>
     <profile-name>AD</profile-name>
     <blsso-cache-refresh-interval>1.5</blsso-cache-refresh-interval>
     <blsso-cache-recovery-interval-in-minutes>10</blsso-cache-recovery-
interval-in-minutes>
     <install-certificate>yes</install-certificate>
     <install-certificate-prompt>?[yes|no]:</install-certificate-prompt>
     <connection-ttl>30</connection-ttl>
     <timeout-secs>120</timeout-secs>
     <is-cli-tunnel-enabled>false</is-cli-tunnel-enabled>
</config>

Configuring the adapter by using the traditional approach

<config>
  <authentication-mechanism />
  <profile-name />
  <default-user-role />
  <executable-directory />
  <script-directory />
  <initial-command>
    <command>nsh</command>
  </initial-command>
  <prompt />
  <is-cli-tunnel-enabled>true</is-cli-tunnel-enabled>
  <cli-tunnel-properties>
  <application-server>xxx.xxx.xx.xx</application-server>
  <web-service-port>9843</web-service-port>
  <user-name>BLAdmin</user-name>
  <password>BLAdmin</password>
  <role-name>BLAdmins</role-name>
  <session-refresh-interval>6</session-refresh-interval>
  <enable-cli-with-tunnel>false</enable-cli-with-tunnel>
  </cli-tunnel-properties>
</config>

Configuring the adapter by using the tunnel approach

<config>
  <is-cli-tunnel-enabled>true</is-cli-tunnel-enabled>
  <cli-tunnel-properties>
    <application-server>10.128.248.91</application-server>
    <web-service-port>9843</web-service-port>
    <user-name>BLAdmin</user-name>
    <password>BLAdmin</password>
    <role-name>BLAdmins</role-name>
    <session-refresh-interval>6</session-refresh-interval>
    <enable-cli-with-tunnel>false</enable-cli-with-tunnel>
  </cli-tunnel-properties>
</config>

Configuring the adapter by using the traditional and tunnel approaches

<config>
  <authentication-mechanism />
  <profile-name />
  <default-user-role />
  <executable-directory />
  <script-directory />
  <initial-command>
    <command>nsh</command>
  </initial-command>
  <prompt>#</prompt>
  <executable-directory>c:\Program Files\BMC Software\BladeLogic\NSH\bin</executable-directory>
  <script-directory>c:\jy_Scripts</script-directory>
  <script-executable>nsh</script-executable>
  <jython-executable>bljython</jython-executable>
  <authentication-mechanism>SRP</authentication-mechanism>
  <profile-name>pr106</profile-name>
  <srp-user-name>BLAdmin</srp-user-name>
  <srp-password>BLAdmin</srp-password>
  <default-user-role>BLAdmins</default-user-role>
  <blsso-cache-refresh-interval>9</blsso-cache-refresh-interval>
  <blsso-cache-recovery-interval-in-minutes>5</blsso-cache-recovery-interval-in-minutes>
  <install-certificate>yes</install-certificate>
  <install-certificate-prompt>?[yes|no]:</install-certificate-prompt>
  <connection-ttl>60</connection-ttl>
  <timeout-secs>60</timeout-secs>
  <is-cli-tunnel-enabled>true</is-cli-tunnel-enabled>
  <cli-tunnel-properties>
    <application-server>10.128.248.91</application-server>
    <web-service-port>9843</web-service-port>
    <user-name>BLAdmin</user-name>
    <password>BLAdmin</password>
    <role-name>BLAdmins</role-name>
    <session-refresh-interval>6</session-refresh-interval>
    <enable-cli-with-tunnel>true</enable-cli-with-tunnel>
  </cli-tunnel-properties>
</config>

Enabling custom logging

To enable custom logging for the adapter, you must specify a log file name. You can also provide additional parameters for logging.

Note

You must be using TrueSight Orchestration version 8.1 or later to use the custom logging feature. These parameters will be ignored in earlier versions of TrueSight Orchestration Platform.

These parameters are available with supported adapter versions. See TrueSight Orchestration Content documentation for details.

Log File Name: Provide a name for the log file.
This file will be stored in the AO_HOME/tomcat/logs directory. If Log File Max Backup Index value is greater than 0, the log file name is suffixed with the backup index. For example, if the parameter value is a.log, backup log files will have names, such as a.log.1, a.log.2.
Log File Size: Specify a size limit for the log file.
If the value specified for Log File Max Backup Index is greater than 0, when the specified size is reached, the current file is renamed with the suffix .1. Otherwise, the log file will be reset and over-written. The default value is 10MB. The available units are KiloBytes (KB), MegaBytes (MB) or GigaBytes (GB).
Log File Max Backup Index: Enter the maximum number of backup files allowed. The default value is 10.
Log File Append: Select this option to append new log information to the existing information in the file. If unselected, the file will be overwritten with new log information.

Log Level: Enter the logging level using one of the following choices:

Logging level	Description
DEBUG	The most detailed logging level; logs low-level messages, normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions
INFO (default)	Logs normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions
WARN	Logs recoverable erroneous conditions and unrecoverable erroneous conditions
ERROR	The least detailed logging level; logs only error conditions that are not usually recoverable

Adapter configuration elements and samples