Skip Headers
Oracle Business Transaction Management Online Help
Release 12.1.0.2

E26585-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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 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

The Business Transaction Management installation directory contains a set of sample configuration files that you can use as a starting point for creating an input file that you can tailor for your environment. These sample files use the same format as the configuration file generated by the browser-based Configuration Wizard. The generated file is called essentialConfiguration.xml. See Backing up and Restoring Business Transaction Management, for information on its location on different platforms. As an alternative to using one of the sample files, you can perform initial configuration of Business Transaction Management using the Configuration Wizard, and then use the generated configuration file as the basis for the configure command's input file.

The preference names in the configuration file, and their values, are both case sensitive. A sample configuration file that you can use to create your own input file is located in: BTM_install_dir/samples/cli/config_files/yourAppServerConfig.xml. There is a sample configuration file for each supported platform.

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.