configure

Use the configure command to configure Business Transaction Management as an alternative to using the browser-based Configuration Wizard for initial configuration. You use the configure command in conjunction with an input file that contains specifications for various Business Transaction Management settings.

Before executing the configure command, you must decide whether you want to store information in an embedded database, or in an Oracle database. If you want to store information in an Oracle database, you will need to install and set up the database before running the configure command.

The sections following the syntax description provide additional information about the configuration process and the input file.

Command Syntax

btmcli configure -i inputFile -sphereUrl -l username:password

Name Long Name Description

-i -inputFile The path to the configuration file to use to configure a Business Transaction Management installation.

-s

-sphereUrl

Name	Long Name	Description
-i	-inputFile	The path to the configuration file to use to configure a Business Transaction Management installation.
-s	-sphereUrl	The URL of the sphere you want to configure. http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere.
-l	-userLogin	The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role. See Security Options in Accessing CLI Commands for information on furnishing login credentials. You can encrypt passwords using the `encryptPassword` command.

The URL of the sphere you want to configure.

http://hostname:port/btmcentral/sphere/

This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere.

-l

-userLogin

The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.

See Security Options in Accessing CLI Commands for information on furnishing login credentials.

You can encrypt passwords using the encryptPassword command.

Example

The following example shows the configure command.

btmcli configure -i myConfigFile.xml -s http://localhost:8080/btmcentral/sphere/
                  -l admin:abracadabra

How the configure Command Works

The configure command checks every Business Transaction Management service for its current configuration state. If all services are in a configured state, the command exits and informs you that Business Transaction Management is configured. If there is a mix of configured and unconfigured services, the configure command attempts to configure the unconfigured services. If an error or exception occurs, Business Transaction Management logs the error and the configuration continues. When the configure command completes, it returns a message that describes all successful and unsuccessful service configurations.

If all Business Transaction Management services are configured successfully, the command returns a "configured" message.

You can run the configure command again following a configuration attempt where an error occurs, and the system will attempt to configure the service(s) that returned an error during the previous configuration attempt. The configure command does not try to reconfigure a service that reports a successful configuration.

If you would like to reconfigure a service that has been configured successfully, you can run the getSetupData and putSetupData commands.

Any reconfiguration of Business Transaction Management services requires a restart of the server.

The Configuration File

When you install and configure Business Transaction Management using the browser-based configuration wizard, a configuration file called essentialConfiguration.xml is created. (See Backing up and Restoring Business Transaction Management, for information on its location on different platforms.) You can use this file as a starting point to initialize a new Business Transaction Management system; you will need to change the contents of the file to specify your desired settings. This then becomes the input file to the configure command. The preference names in the configuration file, and their values, are both case sensitive.

Unlike the Configuration Wizard, the configure command does not allow you to stop midway through the configuration and then resume configuration at a later time. The configure command requires a complete configuration file -- if required parameters are missing from the file, the configure command returns an error.

Password Encryption

To supply an encrypted password for the configuration file, run the encryptPassword command and then copy and paste the resulting value into the configuration file.

If you use a clear text password in the configuration file, Business Transaction Management encrypts the password when it stores the configuration information in the setup data of the appropriate system services.

Configuration File Parameters

The following table lists the parameters to use in the configure command configuration file.

Alias Preferences

You can specify alias values for the nodes running Business Transaction Management central services: sphere, performance, and transaction monitoring. In each case the preference value is a comma-separated list of alternative DNS names/IP addresses that can be used to access services on the respective server.

For example, if the sphere URL is http://server1:8080/apcentral/sphere/, but the machine server1 also has the DNS alias spherehost, you can set sphereAliases to spherehost to reflect that. If the machine's primary IP address is 10.10.22.44, but the sphere's container is listening on all lP addresses and the machine has a second network interface running on 10.10.22.47, you could set sphereAliases to spherehost, 10.10.22.47 to reflect both these aliases.

If all Business Transaction Management central services are running in the same container (the demo case), the performanceAliases and transactionAliases are ignored. If the servers are running in different containers but on the same machine as the sphere, the aliases are applied to the same node definition. So, in effect, the performance and transaction aliases are added to those for the sphere, rather than tracked separately.

Note: All parameters are type=string, except for the acceptLicenseTerms parameter, which is type=boolean.

Parameter Name(s)	Required?	Description
sphereUrl	YES	URL of the sphere you are configuring. The sphere is deployed in btmMain. The value should be the same value provided in the -s flag for the configure command. http://hostname:port/btmcentral/sphere/
databaseChoice	YES	Indicates the type of database to use for the Business Transaction Management databases. Use one of the following: embedded (Java platforms only) oracle If you specify embedded, ignore all subsequent database settings.
nodeAliases	No	Aliases for the node running the sphere. See discussion of Alias preferences, above.
performance.nodeAliases	No	Aliases for the node running the performance server (btmperformance.war). See discussion of Alias preferences, above.
transaction.nodeAliases	No	Aliases for the node running the transaction server (btmexmrt.war). See discussion of Alias preferences, above.
deploymentUsername, deploymentPassword	YES	Some Business Transaction Management services communicate with the application server to perform discovery; these services require a set of administrative credentials mapped to an administrative user for the application server This is required for all application servers except Tomcat
agentServiceDB_databaseUrl, agentServiceDB_provider, agentServiceDB_userName, agentServiceDB_password	NO	Agent message log database. By default, all agents in a container log to this database. You can override the behavior after initial configuration. See Setting up the Message Log Database. This is required if databaseChoice is Embedded.
sphereServiceDB_databaseUrl, sphereServiceDB_provider, sphereServiceDB_userName, sphereServiceDB_password	NO	Sphere database settings. Required if databaseChoice != Embedded
exmServiceDB_databaseUrl, exmServiceDB_provider, exmServiceDB_userName, exmServiceDB_password	Required if databaseChoice != Embedded	Exception management component database settings. Required if databaseChoice != Embedded
performanceDB_databaseUrl, performanceDB_provider, performanceDB_userName, performanceDB_password	Required if databaseChoice != Embedded	Performance component (SLM) database settings. Required if databaseChoice != Embedded
performanceUrl	YES	The URL to use to contact the performance (SLM) component of Business Transaction Management (this component is deployed in btmPerformanceServer). The performance component must be running at the time of configuration. btmPerformanceServer is typically deployed in a separate container than the sphere. When you specify an performanceURL on a different node that the sphere, Business Transaction Management also registers the remote container with the sphere.
transactionURL	NO	The URL to use to contact the transaction component of Business Transaction Management (this component is deployed in btmTransactionServer). The transaction component must be running at the time of configuration. btmTransactionServer is typically deployed in a separate container than the sphere. When you specify an transactionURL on a different node that the sphere, Business Transaction Management also registers the remote container with the sphere.
base_locationType, base_directory, base_maxDuration, base_maxSize, base_numFiles	Optional	By default, trace log files are stored in the directory BTMStorageRoot/deployment_name/system_service/logdir BTMStorageRoot varies with the application server; for more information, see Backing up and Restoring Business Transaction Management.. If you wish to store trace log files in a different location, use the parameters described below. Note: These parameters will not affect the trace log file settings for the following system services: aqms, notifier, and domain. base_locationType - This required parameter must have a value of "default" or "custom"; if the value is "custom", then the base_directory parameter must have a value. base_directory - The directory where Business Transaction Management should create log files. This parameter must have a value if base_locationType = custom. Do not use this preference if base_locationType = default. Note: If you change the directory location using the above parameters, you are required to also include the base_maxDuration, base_maxSize and base_numFiles parameter settings. base_maxDuration - log file age in hours. Once a log file reaches this age, it rotates. (When you configure Business Transaction Management using the Management Console, the default setting is 168.) base_maxSize - size in kilobytes for all log files together. Once the log files become larger than this setting, log file rotation occurs. (When you configure Business Transaction Management using the Management Console, the default setting is 50000.) base_numFiles - number of concurrent log files that can exist. (When you configure Business Transaction Management using the Management Console, the default setting is 7.) base_maxSize / base_numFiles gives the maximum size for each log file. When this size is reached for a particular file, it rotates.