Configuring Enterprise Manager for Oracle Tuxedo

This chapter describes subsequent configuration tasks made on Enterprise Manager for Oracle Tuxedo after you have configured JMX agent as described in the first chapter.

This chapter contains the following topics:

•	Discovering and Adding Oracle Tuxedo Targets

•	Configuring Security

Discovering and Adding Oracle Tuxedo Targets

In order to manage and monitor Oracle Tuxedo applications, you must first discover the Tuxedo targets using Enterprise Manager Cloud Control.

Once discovered, the domain and the components within it can be promoted to "managed target" status and an automatic discovery job runs every 24-hours to update the targets. In this process, management agents are assigned to each target, enabling Enterprise Manager Cloud Control to collect the data needed to monitor the target.

This section covers the following topics:

•	Discovering Targets Manually

•	Manually Adding a Standalone Target

Discovering Targets Manually

To discover all Tuxedo domains on a JMX agent, do the following steps:

1.	Log in to Enterprise Manager Cloud Control.

2.	From the home page, go to Targets >Middleware.

3.	Click Middleware Features >Tuxedo Summary.

4.	In the Tuxedo Summary page, click Add > Tuxedo Domain Discovery.

5.	If only one domain exists in the JMX agent, specify the following options on the page that appears:

•	Hostname: Mandatory parameter. Specifies the host where the Tuxedo domain master machine is running.

•	Port: Mandatory parameter. The port number specified by tlisten -j option.

•

Application Password: Optional parameter. Specifies the Tuxedo application password Enterprise Manager agent uses to connect to the Tuxedo domain. You must input this parameter if the Tuxedo domain SECURITY value is one of following: APP_PW, USER_AUTH, ACL, or MANDATORY_ACL; otherwise, leave the field blank.

•	User name: Optional parameter. Specifies the Tuxedo user name Enterprise Manager agent uses to connect to the Tuxedo domain. You must input this parameter if the Tuxedo domain SECURITY value is one of following: USER_AUTH, ACL, or MANDATORY_ACL; otherwise, leave the field blank.

•	User Password: Optional parameter. Specifies the Tuxedo user password Enterprise Manager agent uses to connect to the Tuxedo domain. You need to input this parameter if the Tuxedo domain SECURITY value is one of following: USER_AUTH, ACL, or MANDATORY_ACL; otherwise, leave the field blank.

•	Use SSL: Optional. This option refers to SSL mechanism between Enterprise Manager and JMX agent in the tlisten process.

•	Find Oracle Tuxedo Domains: If this box is unchecked, Tuxedo security related information is ignored and only tlisten and the Tuxedo Home targets are discovered. Leave this box checked if you want to discover the Tuxedo domains monitored by the tlisten process.

•	Monitoring Agent: Mandatory option. It is recommended you select the one residing on the same physical machine with tlisten.

Note:

The User name, Password, and Application password are used to generate Enterprise Manager Monitoring Credentialsfor all discovered targets. You can manage Monitoring Credentials by clicking Setup -> Security in the Enterprise Manager console.

6.	Click Discover Now.

If only one domain is being monitored by tlisten, you will get a list of discovered targets; otherwise, select the domain on the page that appears and enter the parameters specific to the domain, then click Discover Now again.

Manually Adding a Standalone Target

To add a standalone Tuxedo target to Enterprise Manager Cloud Control, do the following steps:

1.	Log in to Enterprise Manager Cloud Control as SYSMAN.

2.	From the home page, navigate to Setup >Add Targets.

3.	Click Add Targets Manually >Add Non-Host Targets by Specifying Target Monitoring Properties.

Enterprise Manager Cloud Control bypasses tlisten and directly adds the target into Enterprise Repository.

Configuring Security

Enterprise Manager for Oracle Tuxedo supports the following security mechanism:

Tuxedo Authentication and Authorization

If the SECURITY parameter of the Tuxedo domain is APP_PW, Enterprise Manager agents provide a Tuxedo application password for authentication. If the SECURITY parameter is USR_AUTH, ACL or MANDATORY_ACL, Enterprise Manager agents provide application password, user name, and user password for authentication; meanwhile, AUTHSVR must be configured in the UBBCONFIG file.

The client name of Tuxedo users used by Enterprise Manager must be "tpsysadm"; otherwise, some metrics and job requests will fail.

JOB

When any JOB (based on Tuxedo security configuration), is invoked, the following three cases may occur.

•

NONE

No "Credentials" page appears. Your job is executed immediately.

•

APP_PW

"Credentials" page appears, requiring you to provide Tuxedo username, password, and application password. Enterprise Manager OMS takes such information together to talk with JMX agent. If authentication is passed, your job is executed ; otherwise, your job will be rejected.

Note:

Even though Tuxedo does not use the value of Tuxedo Username and Tuxedo Password fields to authenticate or authorize, the two fields must be inputted as place holders.

•	ACL/ACL_MANDATORY

"Credentials" page appears requiring you to provide Tuxedo username, password, and application password. Enterprise Manager OMS uses this information to talk with JMX agent. If authentication is passed, the job is executed afterwards; by contrast, if either authentication or authorization is failed, your job will be rejected.

Note:

The startup of Tuxedo targets with Tuxedo Domain or Tuxedo Machine type:

•	does not need Authentication or Authorization;

•	can be invoked under any its target status.

Discovery

After discovery, all targets, which are required to update status/metric, are updated with username/password and application password into its target instance property.

For more information, see Discovering and Adding Oracle Tuxedo Targets.

Metric Fetchlet

Invoked by Enterprise Manager Agent, fetchlet utilizes username, password, and application password (which are stored as target instance properties), to connect with Tuxedo JMX Agent when Tuxedo security is enabled.

Standalone JMX Authentication

If you don't want to enable Oracle Tuxedo authentication, but require authentication at JMX interface, you can configure the standalone JMX authentication.

To enable the standalone JMX authentication, do the following steps:

1.	Run the command line tool jmxaaacfg to generate the password file.

The usage of jmxaaacfg is as follows:

$ jmxaaacfg [action] [username] [password] [password file name]

The argument action specifies one of the actions in add/delete/modify.

•	add: adds a new username/password pair.

•	delete: deletes the username/password pair.

•	modify: changes an existing username/password pair.

The parameters "username" and "password" are plaintext. jmxaaacfg will make it encrypted and save it in a password file the user creates. JMX AAA password file has its own format for RMI authentication, which is "username password". The parameter [password file name] should include a reasonable absolute path of the password file the user want to store.

For example:

a.	jmxaaacfg add [username] [password] [path/filename]

b.	jmxaaacfg modify [username] [new password] [path/filename]

c.	jmxaaacfg delete [username] [path/filename]

2.	Add the -q option to tlisten. The -q option specifies the location of the password file.

SSL Connection Between EM OMS/Agent and JMX Agent Embedded in "tlisten" Process

SSL connection has two types:

•	Between EM OMS and JMX agent

For example: Admin job action from every Tuxedo target home page, such as startup/shutdown, etc.

•	Between EM Agent and JMX agent

Both Metric fetchlet and Discovery (Manual / Automatic) are based on this connection.

Note:

You must install Enterprise Manager Cloud Control using advanced configuration mode, otherwise the admin job (modify UBB/boot or shutdown one target) will fail.

For more information, see Starting the tlisten Process.

JMX Agent

To enable SSL, you should enable SSL at tlisten startup. For more information , see Starting the tlisten Process.

If JMX Agent enables SSL, Enterprise Manager OMS/Agent must enable SSL; otherwise, OMS fails to connect with JMX Agent.

Discovery

If JMX Agent enables SSL, the "Use SSL" checkbox must be checked onthe discover UI page; otherwise, discovery will be rejected.

At discovery UI, if the "Use SSL" checkbox is checked, the discovery process runs with SSL security. Before discovery with the enabled SSL, the SSL runtime environment should be ready in three areas: Tuxedo Application, Enterprise Manager OMS, and Enterprise Manager Agent.

•	For Tuxedo Application

Make sure SSL is enabled for JMX Agent. For more information, see Starting the tlisten Process.

•	For Enterprise Manager OMS

•	Trust store should be configured well.

•	Each time auto discovery is invoked, "Use SSL" property on the domain target is checked. If "Use SSL" is true, the connection between OMS and JMX Agent is under SSL; otherwise, it is not.

•	Each time a job is invoked from Tuxedo target home page, "Use SSL" property on the domain target is checked. If "Use SSL" is true, the connection between OMS and JMX Agent is under SSL; otherwise, it is not.

•	For Enterprise Manager agent

•	Trust store should be well configured.

•	Modify startup options for SSL.

•	If a metric collection is scheduled, "Use SSL" property on that target is checked. For the connection between Enterprise Manager agent and JMX agent, if "Use SSL" is true, SSL is enabled; otherwise, it is not.

•	If discovery is successful, Enterprise Manager OMS saves all targets discovered using target properties (of which "Use SSL" should be set to true).

WARNING:

If you have already discovered all Tuxedo targets with SSL disabled and then started JMX agent with SSL enabled, Enterprise Manager OMS/Agent fails to connect with JMX agent; all relative targets status is unknown and all job actions from the Tuxedo home page are rejected.

Solution: you should run manual discovery again if this scenario occurs.

Keystore and Trust Store Configuration

JMX Agent

keystore

tlisten startup options provide keystore location/password to enable SSL.

Notes:

•	You must keep or know the keystore password;

•	Reboot tlisten after keystore change if tlisten is active.

Listing 3‑1 Example - Generate keystore.jks

$ keytool -genkeypair -alias tuxedo -keyalg RSA -validity 1825 -keystore keystore.jks

Enter keystore password:

Re-enter new password:

What is your first and last name?

[Unknown]: Tuxedo

What is the name of your organizational unit?

[Unknown]: Oracle Tuxedo

What is the name of your organization?

[Unknown]: Oracle Corporation

What is the name of your City or Locality?

[Unknown]: Redwood Shores

What is the name of your State or Province?

[Unknown]: CA

What is the two-letter country code for this unit?

[Unknown]: US

Is CN=Tuxedo, OU=Oracle Tuxedo, O=Oracle Corporation, L=Redwood Shores, ST=CA, C=US correct?

[no]: yes

 

Enter key password for <tuxedo>

(RETURN if same as keystore password):

Note:

You must press Enter to set key password the same as keystore password ; otherwise, your discovery will not succeed.

 

Enterprise Manager OMS

Trust Store

On the OMS side, SSL follows the standard Java Secure Socket Extension (JSSE). For more information , see the Java Secure Socket Extension (JSSE) Reference Guide.

To configure trust store, do the following steps:

1.	Generate a JMXAgent trust certificate from JMXAgent keystore. (Suppose the certificate name is tuxedo.cer. )

2.	Import JMXAgent trust certificate into one of the following trust stores:

•	The trust store given by javax.net.ssl.trustStore, if such option is set in the WLS startup script, startWebLogic.sh, or WLS startup system property.

•	$MW_HOME/oracle_common/jdk/jre/lib/security/jssecacerts, if it exists.

•	$MW_HOME/oracle_common/jdk/jre/lib/security/cacerts, if it exists.

Where, $MW_HOME is the Oracle Enterprise Manager installation directory.

Listing 3‑2 Example - Export Certificate

$ keytool -export -alias tuxedo -keystore keystore.jks -rfc -file tuxedo.cer

Enter keystore password:

Certificate stored in file <tuxedo.cer>

 

Listing 3‑3 Example - Import tuxedo.cer

$ keytool -import -alias tuxedo -file tuxedo.cer -keystore $MW_HOME/oracle_common/jdk/jre/lib/security/cacerts

Enter keystore password:

Re-enter new password:

Owner: CN=Tuxedo, OU=Oracle Tuxedo, O=Oracle Corporation, L=Redwood Shores, ST=CA, C=US

Issuer: CN=Tuxedo, OU=Oracle Tuxedo, O=Oracle Corporation, L=Redwood Shores, ST=CA, C=US

Serial number: 4fab2940

Valid from: Thu May 10 10:34:40 CST 2012 until: Tue May 09 10:34:40 CST 2017

Certificate fingerprints:

MD5: 63:E2:6E:93:AD:5A:7F:21:CB:3C:51:3F:8C:92:AA:0D

SHA1: 77:D2:86:4F:74:A3:84:64:A0:5B:CA:50:7A:EF:66:DC:7F:92:83:0F

Signature algorithm name: SHA1withRSA

Version: 3

Trust this certificate? [no]: yes

Certificate was added to keystore

 

Note:

The default password for $MW_HOME/oracle_common/jdk/jre/lib/security/jssecacerts and $MW_HOME/oracle_common/jdk/jre/lib/security/cacerts is changeit.

Enterprise Manager Agent

Trust Store

Enterprise Manager Agent may have a trust store pre-installed, $EMAGENT_HOME/agent_inst/sysman/config/montrust/AgentTrust.jks, where $EMAGENT_HOME is the installed Enterprise Manager agent directory (e.g., /u01/OraHomes/agent).

If AgentTrust.jks exists, you should import your public key into AgentTrust.jks; otherwise, copy TuxedoTrust.jks to $EMAGENT_HOME/agent_inst/sysman/config/montrust/ and rename it to AgentTrust.jks.

Usually, on the Enterprise Manager Agent side, you need to import the CA certificate into $EMAGENT_HOME/agent_inst/sysman/config/montrust/AgentTrust.jks. For AIX 5.3 64-bit platforms, you must also import the CA certificate into $EMAGENT_HOME/agent_13.1.0.0.0/oracle_common/jdk/jre/lib/security/cacerts.

For example, type the following commands:

cd $EMAGENT_HOME/agent_13.1.0.0.0/oracle_common/jdk/jre/lib/security/cacerts

keytool -import -alias tuxedo -file tuxedo.cer -keystore $EMAGENT_HOME/agent_13.1.0.0.0/oracle_common/jdk/jre/lib/security/cacerts -storepass changeit

Where:

•	$EMAGENT_HOME is the agent install home on the AIX host

•	tuxedo is the CA certificate alias

•	tuxedo.cer is the CA certificate file

Notes:

•	The Trust store name is AgentTrust.jks and the password is "welcome"; both of them are unchangeable.

•	Reboot Enterprise Manager Agent after truststore change if Enterprise Manager Agent is active.

Listing 3‑4 Example - Import into AgentTrust.jks

$ keytool -import -alias tuxedo -file tuxedo.cer -keystore AgentTrust.jks

Enter keystore password:

Owner: CN=Tuxedo, OU=Oracle Tuxedo, O=Oracle Corporation, L=Redwood Shores, ST=CA, C=US

Issuer: CN=Tuxedo, OU=Oracle Tuxedo, O=Oracle Corporation, L=Redwood Shores, ST=CA, C=US

Serial number: 4fab2940

Valid from: Thu May 10 10:34:40 CST 2012 until: Tue May 09 10:34:40 CST 2017

Certificate fingerprints:

MD5: 63:E2:6E:93:AD:5A:7F:21:CB:3C:51:3F:8C:92:AA:0D

SHA1: 77:D2:86:4F:74:A3:84:64:A0:5B:CA:50:7A:EF:66:DC:7F:92:83:0F

Signature algorithm name: SHA1withRSA

Version: 3

Trust this certificate? [no]: yes

Certificate was added to keystore

 

Listing 3‑5 Example - Verify AgentTrust.jks

$ keytool -list -v -keystore AgentTrust.jks

Enter keystore password:

 

Keystore type: JKS

Keystore provider: SUN

 

Your keystore contains 11 entries

 

...

 

Alias name: tuxedo

Creation date: May 10, 2012

Entry type: trustedCertEntry

 

Owner: CN=Tuxedo, OU=Oracle Tuxedo, O=Oracle Corporation, L=Redwood Shores, ST=CA, C=US

Issuer: CN=Tuxedo, OU=Oracle Tuxedo, O=Oracle Corporation, L=Redwood Shores, ST=CA, C=US

Serial number: 4fab2940

Valid from: Thu May 10 10:34:40 CST 2012 until: Tue May 09 10:34:40 CST 2017

Certificate fingerprints:

MD5: 63:E2:6E:93:AD:5A:7F:21:CB:3C:51:3F:8C:92:AA:0D

SHA1: 77:D2:86:4F:74:A3:84:64:A0:5B:CA:50:7A:EF:66:DC:7F:92:83:0F

Signature algorithm name: SHA1withRSA

Version: 3

 

Summary

Before enabling SSL, do the following steps:

1.	Ensure that keystore at JMX agent is available and start tlisten with SSL enabled options correctly

2.	Ensure Enterprise Manager agent trust store is available. Restart Enterprise Manager agent

3.	Ensure Enterprise Manager OMS trust store is available

4.	Reboot tlisten/EM Agent/OMS after keystore/trustore is changed

5.	Ensure that SSL follows the rule of Maximum Key length (Bits) used in SSL (For example, RSA: 512 and larger; AES: 256/128).