| Oracle® Application Server Administrator's Guide 10g Release 3 (10.1.3.2.0) Part Number B32196-01 |
|
|
View PDF |
| Oracle® Application Server Administrator's Guide 10g Release 3 (10.1.3.2.0) Part Number B32196-01 |
|
|
View PDF |
When you install Oracle Application Server, the installation procedure automatically starts Oracle Enterprise Manager 10g Application Server Control and its related processes. You can then immediately start using the Application Server Control Console to manage the application server components.
You can also control and configure Application Server Control. For example, you can start and stop Application Server Control, change the Application Server Control Console password, and configure security for Application Server Control.
This appendix covers how to manage and configure Application Server Control. It contains the following topics:
Changing the Application Server Control Administrator Password
Configuring Security for the Application Server Control Console
For 10g Release 3 (10.1.3.2.0), Application Server Control is deployed as a standard J2EE application. The Application Server Control application (ascontrol) is deployed automatically on every OC4J instance you create.
As a result, you can start and stop the ascontrol application from the command line, using the procedure described in Section 3.3.1, "Starting and Stopping Components Using opmnctl".
You can also stop and restart the active ascontrol application from the Application Server Control Console; however, unlike other J2EE applications that you deploy on this release, there are some restrictions when starting and stopping the ascontrol application from the Application Server Control Console:
If you are managing one standalone OC4J instance, then you cannot stop, start, or restart the ascontrol application from the Application Server Control Console. If you stopped the ascontrol application, you would be unable to display or use the Application Server Control Console.
If you are in clustered environment, where you are managing multiple OC4J instances, then you can use the Cluster Topology page to start, stop, or restart the active ascontrol application. However, Enterprise Manager displays a warning that describes the implications of stopping the active ascontrol application.
The active ascontrol application represents the Application Server Control currently being used to manage your Oracle Application Server environment. If you stop the active ascontrol application, you will no longer be able to use the Application Server Control Console until the application is started.
You cannot, however, use the Application Server Control Console to start a second ascontrol application. If you attempt to do so, Application Server Control displays an error message stating that an active ascontrol application is already running.
Note that the OC4J instance used to deploy the active ascontrol application is called the Administration OC4J instance. OC4J instances other than the Administration OC4J instance are called remote OC4J instances. In most cases, there is no need to start the ascontrol in a remote OC4J instance.
However, there is a scenario where the ascontrol application in a remote OC4J instance must be running. For more information, see "Starting ascontrol When Viewing Remote Log Files" in the Application Server Control online help.
You can verify that the Application Server Control is started by pointing your browser to the Application Server Control Console URL:
http://hostname.domain:port/em
For example:
http://mgmthost.acme.com:7777/em
To locate the Application Server Control Console port number, use the following command and check the number for HTTP_Server:
(UNIX) ORACLE_HOME/opmn/bin/opmnctl status -l (Windows) ORACLE_HOME\opmn\bin\opmnctl status -l
To use Application Server Control, you must have an Application Server Control administrator account. The privileges you have when managing your environment are based on the user account and password you use to log in to the Application Server Control Console.
When you install Oracle Application Server, a default super administrator account is created. This account is called oc4jadmin and you set the password for this account during the Oracle Application Server installation. You can use the oc4jadmin account to log in to the Application Server Control Console for the first time. Then, you can create additional administration user accounts to use for everyday administration tasks.
Regardless of the user account you use to log in to the Application Server Control Console, you can always change the password for your own administrator account. However, there are special considerations when changing the oc4jadmin password.
For more information, see the following sections:
Changing the oc4jadmin Password for the Administration OC4J Instance
Using Application Server Control to Change the oc4jadmin Password for a Remote OC4J Instance
Using the Command Line to Change the oc4jadmin Password for a Remote OC4J Instance
To change your own administrator account:
Log in to the Application Server Control Console using your administrator username and password.
Navigate to the Application Server home page and select Setup at the top of the page.
Application Server Control Console displays the Password page. Note that the User field on this page identifies which account you are modifying. If you are modifying the oc4jadmin user account, refer to Section A.2.3 for more information.
Enter your current administrator password, the new password, and the new password again for confirmation.
To provide additional security, the new password:
Must contain at least five characters, but not more than 30 characters.
Must begin with an alphabetic character. It cannot begin with a number, the underscore (_), the dollar sign ($), or the number sign (#).
At least one of the characters must be a number.
Can contain only numbers, letters, and the following special characters: US dollar sign ($), number sign (#), or underscore (_).
Cannot contain any Oracle reserved words, such as VARCHAR.
Note that these restrictions are enforced by Application Server Control and Oracle Universal Installer; they are not enforced by the OC4J system-jazn.xml or application-based security configuration files.
Click OK to reset the password.
The next time you log in, you must use the new password.
The default oc4jadmin administration user account serves two distinct purposes in the Oracle Application Server environment. Each is described in the following sections:
During the Oracle Application Server installation, you must define a password for the oc4jadmin account. You can then use the oc4jadmin account to log in to the Application Server Control for the first time.
The oc4jadmin user account is automatically assigned a set of administrative roles that allow users who log in with this account to manage and configure all aspects of the OC4J instance. However, the oc4jadmin account should not be used for everyday administration tasks. Instead, you should create additional administration accounts for that purpose.
In addition to serving as the initial login account for Application Server Control, the oc4jadmin account is also used by the Application Server Control software when it performs administration tasks. Specifically, when you perform configuration tasks on an OC4J instance, Application Server Control connects to the instance using the oc4jadmin user account and password. In this context, the oc4jadmin user and password are referred to as the administration credentials.
Specifically, when you click the name of an OC4J instance on the cluster topology page, Application Server Control uses the administration credentials to connect to the OC4J instance. Application Server Control uses these credentials to connect to both the local administration OC4J, as well as the other, remote OC4J instances in the cluster. This concept is illustrated in Figure A-1.
Figure A-1 How Application Server Control Uses the Administration Credentials to Manage OC4J Instances in a Cluster
There is only one set of administration credentials for each cluster. By default, the oc4jadmin account and password that you defined for the administration OC4J (Oracle Home 1 in Figure A-1) are stored as the administration credentials for the cluster.
As a result, each OC4J instance in your cluster must have an oc4jadmin user account and the password for the oc4jadmin account must be the same as the password defined for the administration OC4J. Otherwise, the administration credentials defined for the cluster will not work and Application Server Control will not be able to connect to the OC4J instance.
You can later change the password for the oc4jadmin account, but if you are managing a cluster of Oracle Application Server instances, you must use caution when changing the oc4jadmin password.
The procedure for changing the oc4jadmin password for the administration OC4J is the same as the procedure for changing your own administrator password. Simply log in using the oc4jadmin user name and password, and then click Setup.
However, changing the oc4jadmin password can have implications on certain operations you perform from the Application Server Control Console. This is because the oc4jadmin username and password are used as the administration credentials for the cluster topology. For more information, see Section A.2.2.2.
When you change the oc4jadmin password by clicking Setup on any page in the Application Server Control Console, you are changing the password for the oc4jadmin account in the administration OC4J instance only.
Changing the password through the Setup link does not change the oc4jadmin password used by any remote OC4J instances. A remote OC4J instance is any OC4J instance in a cluster topology that is not hosting the active Application Server Control.
As a result, if you change the oc4jadmin password by using the Setup link in Application Server Control Console so it is different from the oc4jadmin password defined in the remote OC4J instances, you will no longer be able to navigate to those instances from the Cluster Topology page. Enterprise Manager displays the following error message when you attempt to display the home page of an OC4J instance where the administration credentials are not valid:
Unable to make a connection to OC4J instance instance_name on Application Server application_server_name. A common cause for this failure is an authentication error. The administrator password for each OC4J instance in the Cluster must be the same as the administrator password for the OC4J instance on which Application Server Control is running.
To remedy this problem, you must change the administration credentials for the remote OC4J instance so it matches the administration credentials for the administration OC4J.
If you are managing multiple OC4J instances in a cluster topology, you can use the Setup link at the top of the Cluster Topology page to change the password for the Administration OC4J, which hosts the ascontrol application.
However, to change the oc4jadmin password of a remote OC4J instance in a cluster topology, you must use the following procedure.
Note that this procedure assumes that:
The oc4jadmin account is being used as the administration credentials for the cluster.
The oc4jadmin password is currently the same for both the administration OC4J and the remote OC4J instance. If it is not, you will not be able to use Application Server Control to change the remote oc4jadmin password; instead, use the procedure described in Section A.2.5.
To use Application Server Control to change the oc4jadmin password for a remote OC4J instance:
From the Cluster Topology page, click the name of the remote OC4J instance you want to modify.
Be sure that you are selecting a remote OC4J instance and not the Administration OC4J that hosts the active ascontrol application.
See Also:
Section 2.3.3.1, "Viewing the Cluster Topology and Locating the Active Application Server Control"Enterprise Manager displays the OC4J home page for the selected remote instance.
Click Administration to display the list of administration tasks you can perform on the selected OC4J instance.
Click the task icon in the Security Providers row of the table.
On the Security Providers page, click Instance Level Security.
On the Instance Level Security page, click Realms.
In the jazn.com row of the Results table, click the number (for example, 3) in the Users column.
Enterprise Manager displays the list of users defined for the selected security provider.
Click oc4jadmin to modify the oc4jadmin user account.
Use the password fields on the User page to change the password of the oc4jadmin account for this remote OC4J instance, and then click Apply.
Return to the Cluster Topology page and restart the remote OC4J instance.
To change the oc4jadmin password for a remote account without using Application Server Control:
Log in to the computer where the remote OC4J is installed and running.
Locate the following configuration file in the Oracle home of the OC4J instance:
ORACLE_HOME/j2ee/oc4j_instance_name/config/system-jazn-data.xml
Use a text editor to open the system-jazn-data.xml file and locate the following entry for the oc4jadmin user:
<user>
<name>oc4jadmin</name>
<display-name>OC4J Administrator</display-name>
<guid>41A2E560C96711DABFD08D3BF8B780C4</guid>
<description>OC4J Administrator</description>
<credentials>{903}4nlfYYDwaqMJipVbGXuS2ce8egfwBPqp</credentials>
</user>
Replace the value of the <credentials> element with the new password. Be sure to include an exclamation point character (!) before the password.
For example:
<credentials>!abcdefg1234</credentials>
In this example, replace abcdefg1234 with the actual password you want to use.
The exclamation point ensures that the password will be encrypted in the configuration file.
See Also:
"Password Obfuscation in OC4J Configuration Files" in the Oracle Containers for J2EE Configuration and Administration GuideSave your changes and exit the system-jazn-data.xml file.
Restart the OC4J instance.
For example, use the following Oracle Process Manager and Notification Server (OPMN) commands to stop and then start the Oracle Application Server instance:
ORACLE_HOME/opmn/bin/opmnctl stopall ORACLE_HOME/opmn/bin/opmnctl startall
Securing the Application Server Control Console involves securing two types of communication links:
Browser client to server communication
Communication between Oracle Application Server components
Enabling security involves some trade-offs: higher security may mean the use of SSL and the need for more processing power and memory. Because of this, security measures should be applied where they are needed, depending on your environment.
The following sections describe how to configure security for the Application Server Control application:
Note:
This section provides an overview of the steps you must perform to secure the Application Server Control Console. For more complete instructions on the security settings and options described in this section, refer to:By default, Application Server Control user credentials are sent (over a corporate network or the internet) in clear text from the browser to the Web server. As such, it is vulnerable to a security attack.
To secure communication between browser clients and Web servers that host the Application Server Control, you must encrypt all Application Server Control communication (including Application Server Control user credentials).
In a secure configuration, browser clients connect directly to the Administration OC4J instance over HTTPS to access the Application Server Control Console. This is the recommended configuration in both OC4J standalone installations and in Oracle Application Server environments.
The following procedure describes how to configure the Administration OC4J instance to serve Application Server Control Console clients using HTTPS:
Task 1: Create a Keystore and SSL Certificate for the Administration OC4j
To create a keystore and SSL certificate for the Administration OC4J instance, take the following steps:
Stop the Administration OC4J instance.
Create a keystore with an RSA private/public keypair using the keytool executable. This creates an SSL certificate that OC4J can use for secure HTTP communication with browser clients. The keytool executable is located in the ORACLE_HOME/jdk/bin directory. Use the following command:
keytool -genkey -keyalg "RSA" -keystore keystore -storepass passwd -validity days
When you are prompted for a key password, press Return, rather than entering a different password. The key password is used to protect the private key of the generated key pair. You must use the same password as the keystore password for SSL to work properly.
See Also:
"Using Keys and Certificates with OC4J and Oracle HTTP Server" in the Oracle Containers for J2EE Security Guide
The description of the JSSE keytool command, which is available on the Sun Microsystems Web site:
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
Task 2: Unbind the ascontrol Application from the Non-Secure Web Site
To unbind the ascontrol Web application from the default non-secure Web site, take the following steps:
Edit the configuration file for the Web site where the Application Server Control Console (ascontrol) Web module is bound. By default, the file is:
(UNIX) ORACLE_HOME/j2ee/Admin_OC4J_instance_name/config/default-web-site.xml (Windows) ORACLE_HOME\j2ee\Admin_OC4J_instance_name\config\default-web-site.xml
Remove the <web-app> element that binds the ascontrol application. For example, remove the following line:
<web-app application="ascontrol" name="ascontrol" root="/em" load-on-startup="true" ohs-routing="true" />
Save and close the file.
Task 3: Create a New HTTPS Web Site for the ascontrol Application
Create a new Web site for the Application Server Control (ascontrol) application by creating a new configuration file in the Administration OC4J instance that uses HTTPS. Take the following steps:
Copy an existing *-web-site.xml file in the ORACLE_HOME/j2ee/Admin_OC4J_instance_name/config directory to create a new Web site. For example, copy default-web-site.xml to ascontrol-web-site.xml.
Make the following changes to the <web-site> element of the newly created ascontrol-web-site.xml file:
Set the display name of the Web site to ASControl Secure HTTP Web Site by modifying the display-name attribute.
Configure the Web site to use HTTPS by setting the protocol attribute to http, and by setting the secure attribute to true.
Configure the port that browser clients will use to access the Application Server Control Console Web site, by setting an new port number in the port attribute. For example, set port to 1156.
Add an <ssl-config> element with its required keystore and keystore-password properties to reference the keystore you created in the previous task.
Modify the path attribute of the <access-log> element to point to a new log file to store the new Web site's access log.
Bind the ascontrol Web module to this Web site by:
Setting the application and name attributes of the <default-web-app> element within the <web-site> element to ascontrol
Setting the root attribute of the <default-web-app> element to "/ "
Removing all other <web-app> elements within the <web-site> element
The following excerpt of a Web site configuration file, named ascontrol-web-site.xml, is an example of a dedicated Web site for the ascontrol Web application:
<web-site xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/web-site-10_0.xsd"
port="1156" protocol="http" secure="true"
display-name="ASControl Secure HTTP Web Site""
schema-major-version="10" schema-minor-version="0" >
<default-web-app application="ascontrol" name="ascontrol" root="/ " />
<access-log path="../log/ascontrol-web-access.log" split="day" />
<ssl-config keystore="private/OracleAS_2/jdk/bin/mykeystore"
keystore-password="welcome"/>
</web-site>
Note that the value of the keystore attribute is either an absolute path or a path relative to the location of the *-web-site.xml file.
In this example, Application Server Control Console users access the console by accessing the following URL:
https://hostname:1156
Task 4: Register the New ascontrol HTTPS Web Site
Register the new Web site in the Administration OC4J instance:
Locate the server.xml file in the ORACLE_HOME /j2ee/Admin_OC4J_instance_name/config directory.
Add a <web-site> element to the <application-server> element pointing to the new ascontrol-web-site.xml file (the path attribute is absolute or relative to the location of the server.xml file). For example:
<web-site path="./ascontrol-web-site.xml" />
If the Administration OC4J instance is in a clustered environment, register the new Web site with OPMN by modifying the following file:
(UNIX) ORACLE_HOME/opmn/conf/opmn.xml (Windows) ORACLE_HOME\opmn\conf\opmn.xml
Locate the <ias-component> element for the Administration OC4J (under ias-component ID OC4J and the process-type ID that is equal to the name of the Administration OC4J). Add a new <port> element for the new Web site in the Administration OC4J section. For example:
<ias-instance id="yellow.stadm21.ora.com" name="yellow.stadm21.ora.com">
. . .
<ias-component id="OC4J">
<process-type id="home" module-id="OC4J" status="enabled">
. . .
<port id="default-web-site" range="8989" protocol="http"/>
<port id="secure-web-site" range="1156" protocol="https"/>
<port id="rmi" range="12401-12500"/>
<port id="jms" range="12601-12700"/>
<process-set id="default_group" numprocs="1"/>
. . .
</process-type>
</ias-component>
In this example, the Oracle Application Server instance name is yellow.stadm21.ora.com and the Administration OC4J instance name is home.
Task 5: Start the Administration OC4J Instance
In an Oracle Application Server environment, reconfigure OPMN with the new opmn.xml file by reloading the opmn.xml file and starting the Administration OC4J instance. Use the following commands:
UNIX:
ORACLE_HOME/opmn/bin/opmnctl reload ORACLE_HOME/opmn/bin/opmnctl startproc ias-component=OC4J
Windows:
ORACLE_HOME\opmn\bin\opmnctl reload ORACLE_HOME\opmn\bin\opmnctl startproc ias-component=OC4J
See Also:
"Using SSL with OC4J in Oracle Application Server" in the Oracle Containers for J2EE Security Guide
"Using SSL with Standalone OC4J" in the Oracle Containers for J2EE Security Guide
Depending on your environment, you may choose to secure communication between components of Oracle Application Server. Each communication link is independent of the other, so you have complete flexibility over which links you want to secure and which you do not. You have the option to:
Encrypt communication between the Administration OC4J and remote OC4J instances (thereby encrypting the oc4jadmin password of the remote OC4J).
Secure OPMN so that only trusted Oracle Application Server instances can join the cluster.
A remote OC4J instance is an OC4J instance that is managed remotely by Application Server Control. The remote OC4J instance may reside in the same Oracle Home as the Administration OC4J, in a different Oracle Home and on the same host, or on a different host.
The following sections describe these topics:
Securing Communication Between the Administration OC4J and Remote OC4J Instances
Securing OPMN Communication in an Oracle Application Server Cluster
In an Oracle Application Server environment, when Application Server Control is used to manage OC4J instances other than the Administration OC4J, it uses the Remote Method Invocation (RMI) protocol to establish a JMX connection with remote OC4J instances. In establishing a JMX connection to a remote OC4J, Application Server Control authenticates itself by sending the oc4jadmin user credentials of the remote OC4J. By default, this communication happens in clear text.
Use the Secure Remote Method Invocation (ORMIS) protocol to secure communication between the Administration OC4J and remote OC4J instances.
The following procedure describes the tasks you must perform to enable RMIS for the Administration OC4J instance, as well as each of the OC4J instances you are managing with Application Server Control.
Note that this procedure is necessary only in a managed Oracle Application Server environment that you have installed with Oracle Universal Installer and the Oracle Application Server installation procedure.
See Also:
For complete information about securing ORMI connections for deployment and management, as well as for instructions on configuring ORMIS in a standalone environment, see the Oracle Containers for J2EE Security Guide.Task 1: Configure Each OC4J Instance with an RMIS Port
Configure a Secure RMI port on the Administration OC4J instance and on each remote OC4J instance that is being managed by Application Server Control Console:
Create a keystore with an RSA private/public keypair using the keytool executable. This creates an SSL certificate that OC4J can use for secure HTTP communication with browser clients. The keytool executable is located in the ORACLE_HOME/jdk/bin directory. Use the following command:
keytool -genkey -keyalg "RSA" -keystore keystore -storepass passwd -validity days
When you are prompted for a key password, press Return, rather than entering a different password. The key password is used to protect the private key of the generated key pair. You must use the same password as the keystore password for SSL to work properly.
See Also:
"Using Keys and Certificates with OC4J and Oracle HTTP Server" in the Oracle Containers for J2EE Security Guide
The description of the JSSE keytool command, which is available on the Sun Microsystems Web site:
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
Locate the rmi.xml configuration file for the OC4J instance.
The file is typically located in the following location; however, you can verify its location by checking the value of the <rmi-config> element in the server.xml file for the OC4J instance:
(UNIX) ORACLE_HOME/j2ee/instance_name/config/rmi.xml (Windows) ORACLE_HOME\j2ee\instance_name\config\rmi.xml
Open the rmi.xml file with a text editor and add the <ssl-config> element to the contents of the file.
Use the <ssl-config> element to specify the path to the keystore you created in step 1 and the keystore password. For example:
<ssl-config keystore="path_to_keystore" keystore-password="keystore_pwd" />
Use the ssl-port attribute in the <rmi-server> element to specify the SSL listener port. For example:
<rmi-server ... port="23791" ssl-port="23943" ... >
Task 2: Distribute the SSL Certificate of Each Remote OC4J Instance to the Administrative OC4J Instance
You must distribute the SSL certificate of each remote OC4J instance to the Administration OC4J instance. You can do this either by having each remote Administration OC4J instance use an SSL certificate that has been signed by a certificate authority that is trusted by the Administration OC4J's keystore or by importing the SSL certificate of each remote OC4J instance into the Administration OC4J's keystore.
To import the SSL certificate of each remote OC4J instance into the Administration OC4J's keystore, take the following steps for each remote OC4J instance:
From the remote OC4J Oracle home, use the keytool command to export the OC4J SSL certificate, which contains the RSA public key. This step places the certificate into a file that is accessible to the Administration OC4J.
keytool -export -file cert_file_name -keystore keystore_file_name
Import the OC4J SSL certificate into the Administration OC4J keystore, by executing the following command from the Administration OC4J Oracle home:
keytool -import -file cert_file_name -keystore keystore_file_name
Task 3: Configure OPMN to Enable RMIS
Perform the following steps for each Oracle Application Server instance that hosts an OC4J instance in your environment:
Locate the following configuration file in the Oracle home:
(UNIX) ORACLE_HOME/opmn/conf/opmn.xml (Windows) ORACLE_HOME\opmn\conf\opmn.xml
Open the opmn.xml file with a text editor and add a new <port> element for the RMIS protocol for each OC4J instance defined in the opmn.xml file:
<port id="rmis" range="12701-12800"/>
Task 4: Configure the Administration OC4J Instance for Secure RMIS Connection Policy
Locate the OPMN configuration file in the Oracle home where the Administration OC4J is installed:
(UNIX) ORACLE_HOME/opmn/conf/opmn.xml (Windows) ORACLE_HOME\opmn\conf\opmn.xml
Locate the <ias-component> element for the Administration OC4J (under ias-component ID OC4J and the process-type ID equal to the name of the Administration OC4J). Add the following property to the java-options start parameters for the Administration OC4J in the opmn.xml file:
oracle.oc4j.jmx.internal.connection.protocol
Application Server Control uses this property to determine when to use the secure RMI protocol to communicate with remote OC4J instances.
Table A-1 shows the values you can assign to this property depending on the level of security you want to enforce in your environment.
The following example shows a typical configuration for the <ias-component> element of the Administration OC4J with the RMIS property set to RMIS.
<ias-component id="OC4J">
<process-type id="home" module-id="OC4J" status="enabled">
<module-data>
<category id="start-parameters">
<data id="java-options" value="-server
-Doracle.oc4j.jmx.internal.connection.protocol=RMIS
-Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy
-Djava.awt.headless=true -Dhttp.webdir.enable=false"/>
</category>
</module-data>
</process-type>
</ias-component>
In this example, the name of the Administration OC4J is home.
Note that if you want to maintain secure connections when managing all your OC4J instances and applications, you must add the <ssl-config> element to the rmi.xml file for each OC4J instance you are managing. Otherwise, management connections to the OC4J instance from the Application Server Control will either fail or use the non-secure RMI protocol, depending upon the value of the connection protocol property in the opmn.xml file for the Administration OC4J instance.
Table A-1 Possible Values for the jmx.internal.connection.protocol Property
| Property Value | Description |
|---|---|
|
RMIS_RMI |
Use RMIS if available; otherwise use RMI. This is the default setting if the RMI connection protocol is not found in the |
|
RMI_RMIS |
Use RMI if available; otherwise use RMIS. |
|
RMIS |
Use RMIS; if RMIS is not available, then report a failed connection. |
|
RMI |
Use RMI; if RMI is not available, then report a failed connection. |
See "Enabling ORMIS for OC4J" in the Oracle Containers for J2EE Security Guide for more information.
If your environment includes a cluster topology, you must secure the cluster so that only trusted Oracle Application Server instances can join the cluster. Otherwise, a malicious Oracle Application Server instance can join the cluster and gain process control over the cluster components on the Cluster Topology page.
For more information, see the following sections:
During installation, OPMN is configured to use a default wallet containing a default SSL certificate. The default wallet is stored in the following directory in each Oracle Application Server Oracle home:
(UNIX) ORACLE_HOME/opmn/conf/ssl.wlt/default (Windows) ORACLE_HOME\opmn\conf\ssl.wlt\default
To secure OPMN effectively, you must replace this default wallet with a new wallet that contains a valid and unique certificate. You must perform this task for each Oracle Application Server instance in a cluster.
In addition, you must use mutual authentication (also referred to as Server and Client Authentication mode) when you are configuring the wallet and certificates for OPMN.
In mutual authentication mode, both the OPMN client and the OPMN server use X.509 certificates to authenticate each other before a connection is made. First, the client authenticates the server by validating its certificate. In return, the server also requires the client to send its certificate to prove its authenticity.
If you do not replace the default wallet in each OPMN in your cluster and ensure that you are using mutual authentication for all instances in your cluster, then any Oracle Application Server instance that uses the default wallet and certificate will be able to join the cluster. After it joins the cluster, the Application Server Control for the instance can start and stop components of the cluster on the Cluster Topology page.
The easiest way to secure OPMN connections between the Oracle Application Server instances in your cluster is to create a new wallet and distribute that wallet to each Oracle Application Server instance in the cluster.
In the following example, a self-signed (root) certificate is used to secure an Oracle Application Server cluster. In a more complex or production environment, you can use certificates obtained from a Certificate Authority.
Use the following example to understand how to set up mutual authentication using a self-signed certificate:
Use the orapki utility to create a new wallet and a new self-signed (root) certificate for the first Oracle Application Server instance in the cluster topology.
Modify the OPMN configuration file (opmn.xml) for the instance so that the <ssl> element points to the newly created wallet. For example:
<ssl enabled="true"
wallet-file="$ORACLE_HOME/opmn/conf/ssl.wlt/new_wallet"
wallet-password="welcome2"/>
Copy the new wallet, which contains the newly created root certificate, to each of the Oracle Application Server instances in the cluster and update the opmn.xml file for each instance as described in Step 2.
Restart each Oracle Application Server instance in the cluster using the following commands:
Unix:
ORACLE_HOME/opmn/bin/opmnctl stopall ORACLE_HOME/opmn/bin/opmnctl startall
Windows:
ORACLE_HOME\opmn\bin\opmnctl stopall ORACLE_HOME\opmn\bin\opmnctl startall
Use the Application Server Control Console to verify that the cluster is configured correctly:
Log in to the Application Server Control Console and review the contents of the Cluster Topology page.
Each of the Oracle Application Server instances in the cluster should be listed in the Members section of the page.
Scroll to the Administration section of the page and click Topology Network Configuration.
Select any one of the Oracle Application Server instances in the cluster from the View By menu near the top of the Topology Network Configuration page.
Scroll to the SSL section of the Topology Network Configuration page and verify that SSL is enabled and the instance is using the new wallet you created earlier in this procedure.
See the Oracle Process Manager and Notification Server Administrator's Guide for more information about OPMN and security.
Application Server Control provides its own set of log files, which you can configure by modifying a configuration file. How you configure logging depends upon whether or not you enable Oracle Diagnostic Logging (ODL).
For more information, see the following sections:
Enabling and Configuring ODL for the Application Server Control Log File
Controlling the Number of Entries Retrieved When Searching Log Files
By default, the log file generated for Application Server Control is saved in text format. However, you can configure Application Server Control so its log file will be saved using the Oracle Diagnostic Logging (ODL) format.
When you enable ODL for the Application Server Control log files, the logging and diagnostic information is saved in XML format and each log message is formatted to comply with the ODL standard.
See Also:
Chapter 5, "Managing Log Files"By default, Application Server Control logs information and errors to the following log file in the application server home directory:
(UNIX) ORACLE_HOME/j2ee/home/log/ascontrol.log (Windows) ORACLE_HOME\j2ee\home\log\ascontrol.log
After you perform the procedure in Section A.4.1.1, Application Server Control will instead log information and error messages to the following file, which formats the data according to the ODL standard:
(UNIX) ORACLE_HOME/sysman/log/log.xml (Windows) ORACLE_HOME\sysman\log\log.xml
Refer to the following sections for more information:
Section A.4.1.1, "Configuring the Application Server Control Logging Properties to Enable ODL"
Section A.4.1.2, "About the Application Server Control ODL Logging Properties"
Section A.4.2, "Configuring Logging Properties When ODL Is Not Enabled"
To configure the Application Server Control to support ODL:
Navigate to the following directory in the Oracle Application Server Oracle home:
(UNIX) ORACLE_HOME/j2ee/home/applications/ascontrol/ascontrol/WEB-INF/config (Windows) ORACLE_HOME\j2ee\home\applications\ascontrol\ascontrol\WEB-INF\config
Use a text editor to edit the following configuration file in the config directory:
ascontrollogging.properties
Follow the instructions in the file to replace the default properties with those that are commented by default.
Example A-1 shows the properties in the emiasconsolelogging.properties file that enable ODL for the Application Server Control log file.
Save and close the ascontrollogging.properties file.
Restart Application Server Control.
Example A-1 ODL Logging Properties for the Application Server Control Console
# To support the ODL log appender, replace the lines above # with the following and restart EM. The resulting ODL log files # will be read by the Log Loader and written to the Log Repository. # # log4j.appender.emiaslogAppender=oracle.core.ojdl.log4j.OracleAppender # log4j.appender.emiaslogAppender.ComponentId=EM # log4j.appender.emiaslogAppender.LogDirectory=/private/shiphomes/m21_infra/sysman/log # log4j.appender.emiaslogAppender.MaxSize=20000000 # log4j.appender.emiaslogAppender.MaxSegmentSize=5000000
Table A-2 describes the Oracle Diagnostic Logging (ODL) logging properties available in the emiasconsolelogging.properties file.
Table A-2 Oracle Diagnostic Logging (ODL) Properties
| Property | Description |
|---|---|
|
log4j.appender.emiaslogAppender.LogDirectory |
Determines the directory where the |
|
log4j.appender.emiaslogAppender.MaxSize |
Determines the maximum amount of disk space to be used by the |
|
log4j.appender.emiaslogAppender.MaxSegmentSize |
Determines the maximum size of the |
When you enable ODL, the resulting log.xml file increases in size over time as information is written to the file. The file is designed to reach a maximum size, determined by the MaxSegmentSize property described in Table A-2. When the file reaches the predefined maximum size, Application Server Control renames (or rolls) the logging or trace information to a new file name and starts a new log or trace file. This process keeps the log file from growing too large.
To be sure you have access to important log information, Application Server Control will roll over the log.xml file until the log file and its rollover files consume a predefined, maximum amount of disk space, determined by the MaxSize property shown in Example A-1. When the log file and its rollover files reach this predefined target, Application Server Control deletes the oldest rollover file.
As a result, you will often see multiple log files in the log directory. The following example shows three Application Server Control rollover files and the current log file in the log directory:
log.xml log1.xml log2.xml log3.xml
If you do not enable ODL, you can still configure the logging properties for the Application Server Control by modifying the ascontrollogging.properties file:
Navigate to the following directory in the Oracle Application Server home directory:
(UNIX) ORACLE_HOME/j2ee/home/applications/ascontrol/ascontrol/WEB-INF/config/ (Windows) ORACLE_HOME\j2ee\home\applications\ascontrol\ascontrol\WEB-INF\config\
Use a text editor to edit the following configuration file in the config directory:
ascontrollogging.properties
Modify the selected logging properties described in Table A-3.
Save and close the ascontrollogging.properties file.
Restart Application Server Control.
Table A-3 Logging Properties When ODL Is Not Enabled
| Property | Description |
|---|---|
|
log4j.appender.ascontrollogAppender.File |
The location and name of the Application Server Control (ascontrol) application. |
|
log4j.appender.ascontrollogAppender.MaxFileSize |
Determines the maximum amount of disk space to be used by the ascontrol application log file and its rollover log files. |
|
log4j.appender.ascontrollogAppender.MaxBackupIndex |
Indicates how many times Application Server Control will rollover its log file to a new file name before deleting the oldest rollover log file. |
To help you diagnose application errors or performance problems, Enterprise Manager provides a mechanism for searching the OC4J log files from the Application Server Control Console.
You can search not only all the OC4J instance log files associated with the current Oracle Application Server instance, but the log files associated with the applications you deploy on the instance.
See Also:
Section 5.1, "Listing and Viewing Log Files with Application Server Control"
"Searching OC4J Log Files" in the Application Server Control online help
On the Search Logs page in the Application Server Control Console, you can enter a set of search criteria and Enterprise Manager will return a list of log file entries that match your criteria. By the default, Enterprise Manager will return a maximum of 5,000 log file entries that you can browse or filter for more information.
To retrieve more than 5,000 entries during a log file search, or to limit searches so they return less than 5,000 entries, use the following procedure:
Use a text editor to open the emiaslogviewer.xml configuration file, which is located in following directory in the Oracle home of the administration OC4J:
(UNIX) ORACLE_HOME/j2ee/home/applications/ascontrol/ascontrol/WEB-INF/config (Windows) ORACLE_HOME\j2ee\home\applications\ascontrol\ascontrol\WEB-INF\config
Modify the following configuration file in the emiaslogviewer.xml file:
<LogViewerConfig maxEntries="5000">
The following sections provide information on the benefits of running Enterprise Manager in accessibility mode, as well as instructions for enabling accessibility mode:
Enterprise Manager takes advantage of user interface development technologies that improve the responsiveness of some user operations. For example, when you navigate to a new record set in a table, Enterprise Manager does not redisplay the entire HTML page.
However, this performance-improving technology is generally not supported by screen readers. When you enable accessibility mode, you disable this feature, and as a result, make the Enterprise Manager HTML pages more accessible for disabled users.
Throughout Enterprise Manager, charts are used to display performance data. For most users, these charts provide a valuable graphical view of the data that can reveal trends and help identify minimum and maximum values for performance metrics.
However, charts do not convey information in a manner that can be read by a screen reader. To remedy this problem, you can configure Enterprise Manager to provide a complete textual representation of each performance chart. When you enable accessibility mode, Enterprise Manager displays a small icon for each chart that can be used as a drill-down link to the textual representation.
Figure A-2 shows an example of the icon that appears below each chart after you enable accessibility mode.
Figure A-2 Icon Representing the Textual Representation of a Chart
To modify the uix-config.xml configuration file:
Locate the uix-config.xml configuration file in the Oracle Application Server home directory:
(UNIX) ORACLE_HOME/j2ee/home/applications/ascontrol/WEB-INF (Windows) ORACLE_HOME\j2ee\home\applications\ascontrol\WEB-INF
Open the uix-config.xml file using a text editor and locate the following entry:
<!-- An alternate configuration that disables accessibility features --> <default-configuration> <accessibility-mode>inaccessible</accessibility-mode> </default-configuration>
Change the value of the accessibility-mode property from inaccessible to accessible.
Save and close the file.
Restart the Application Server Control Console.
Use the following sections to learn more about managing and configuring the active Application Server Control:
Best Practices for Managing the Active Application Server Control
Stopping an Instance of ascontrol and Preventing the Application from Starting
Identifying and Configuring a New Active Application Server Control
Publishing Application Server Control to a Separate Web Site in the Same OC4J Instance
By default, each OC4J instance in an Oracle Application Server 10g Release 3 (10.1.3.2.0) cluster contains an ascontrol application, which represents an instance of the Application Server Control.
However, only one ascontrol application should be running in a cluster. The other instances of the application should be stopped or disabled. When you create a new OC4J instance, the new instance includes an ascontrol application, which is deployed to the OC4J instance. However, by default, a setting in the server.xml configuration file, which defines the characteristics of the OC4J instance, prevents the ascontrol application from starting automatically when the OC4J instance is started.
See Also:
Section A.6.3, "Stopping an Instance of ascontrol and Preventing the Application from Starting"Whenever you log in to the Application Server Control Console, only one ascontrol application is being used to manage your cluster. That ascontrol application is called the active Application Server Control.
To identify the active Application Server Control, navigate to the Cluster Topology page, click Expand All to view all components of the cluster, and then locate the ascontrol application that is identified by the active Application Server Control icon.
The OC4J instance that hosts the active Application Server Control is referred to as the administration OC4J.
Table A-4 lists a set of best practice guidelines that you should consider for managing the active Application Server Control.
Table A-4 Best Practices for Managing the Active Application Server Control
| Recommendation | Explanation | More information |
|---|---|---|
|
Select one OC4J instance that will serve as your administration OC4J. |
Do not use this instance to host any of your deployed applications. Instead, use it exclusively to host the Application Server Control and to create additional OC4J instances to deploy your applications. Note that if you are using Java SSO, you can also use the administration OC4J to host the active |
Section 6.1, "Adding and Deleting OC4J Instances" Section 6.5, "Configuring Instances to Use OC4J Java Single Sign-On" |
|
Shut down or disable instances of the |
Only the active Application Server Control should be running. |
Section A.6.3, "Stopping an Instance of ascontrol and Preventing the Application from Starting" |
|
Isolate the Application Server Control so it uses its own Web site or URL. |
Only your Oracle Application Server administrators need access to the Application Server Control Console so it makes sense to use a separate URL and port number to access the console. |
Section A.6.5, "Accessing the Administration OC4J Directly Through HTTP" |
If more than one ascontrol application is running in your cluster topology, the following warning message appears at the top of the Cluster Topology page:
You have more than one instance of the Application Server Control application running in this cluster. This is not a recommended configuration and could lead to unexpected problems. Please stop the additional instances of Application Server Control or disable routing to these instances.
This problem can occur, for example, if you have installed two or more separate Oracle Application Server instances and you later combine them into a single cluster topology. Before joining the cluster, each Oracle Application Server instance has its own Application Server Control that is used to manage the instance. After joining the cluster, only one Application Server Control is required to manage the entire cluster.
To remedy this problem, do the following:
Navigate to the Cluster Topology page and click Expand All to see all the OC4J instances and the applications deployed to the instances.
Select any ascontrol applications that are not marked with the green, diamond icon that identifies the active ascontrol application.
Click Stop.
This operation stops the selected non-active ascontrol applications. In addition, Application Server Control performs the following actions automatically whenever you stop a non-active ascontrol in a cluster:
To prevent the non-active ascontrol applications from starting the next time the host OC4J instance is restarted, Application Server Control modifies the server.xml file for the OC4J instance. Specifically, Application Server Control sets the start parameter for the application to false.
To prevent any Oracle HTTP Server instances from routing requests to the non-active ascontrol applications, Application Server Control modifies the default-web-site.xml file for the OC4J instance. Specifically, it sets the ohs-routing parameter for the ascontrol application to false.
As a result, if you later need to start any non-active ascontrol applications—for example, if you later separate the Oracle Application Server instance from the cluster and want to manage it separately—you must reset these configuration settings to their original value.
For more information, see Section A.6.4, "Identifying and Configuring a New Active Application Server Control".
In some situations, you might want to identify a different instance of the ascontrol application as your active Application Server Control. For example, if you are not using a dedicated administration OC4J instance, you might reconfigure your environment so that the ascontrol application is running in its own OC4J instance on its own host.
Similarly, if you installed a new Oracle Application Server instance and did not identify it as an administration OC4J during the installation, you could end up with no ascontrol applications running. In this case, you need to start one of the ascontrol applications and identify it as your active Application Server Control
In either of these scenarios, perform the following procedure:
For each instance of the ascontrol application that is deployed to your cluster, perform the following steps:
Use a text editor to open the server.xml file for the OC4J instance:
On UNIX systems:
ORACLE_HOME/j2ee/oc4j_instance_name/config/server.xml
On Windows systems:
ORACLE_HOME\j2ee\oc4j_instance_name\config\server.xml
In the example, oc4j_instance_name is the name of the OC4J instance where the ascontrol application is deployed.
For the active ascontrol application, make sure that the start argument is set to true. This ensures that the application will be started automatically whenever the OC4J instance is restarted.
<application name="ascontrol"
path="../../oc4j_instance_name/applications/ascontrol.ear"
parent="system"
start="true" />
For all other instances of the ascontrol application, make sure that the start argument is set to false. This ensures that the selected instance of the application will not be started automatically when the OC4J instance is restarted.
Save your changes and close the server.xml file.
Open the default-web-site.xml file, which is stored in the same directory as the server.xml file.
For the active ascontrol application, change the ohs-routing attribute of the web-app element to true:
<web-app application="ascontrol"
name="ascontrol"
load-on-startup="true"
root="/em"
ohs-routing="true" />
For all other instances of the ascontrol application, make sure that the ohs-routing attribute is set to false. This prevents Oracle HTTP Server from routing HTTP requests to the non-active instances of the ascontrol application.
Save your changes and close the default-web-site.xml file.
After you have configured the server.xml and default-web-site.xml files for each OC4J instance in the cluster, perform the following steps:
From the Cluster Topology page, stop and restart all of the OC4J instances, except the instance that is used to deploy the currently active ascontrol application.
Note that the currently active ascontrol application is identified by the green diamond icon.
After you restart the other OC4J instances, restart the administration OC4J instance that hosts the currently active ascontrol application.
When you restart the currently active ascontrol application, you will be logged out of the Application Server Control Console.
Log in to the Application Server Control Console using the URL for the new active ascontrol application.
For example:
http://new_admin_oc4j_hostname:port/em
One of the advantages of using a dedicated administration OC4J instance is that you can easily configure the administration OC4J to use its own HTTP listener.
For example, if your administration OC4J is currently accessed by using Oracle HTTP Server, you can reconfigure the instance to use the built-in OC4J HTTP listener, which means you can bypass Oracle HTTP Server and access the administration OC4J directly using the HTTP protocol.
Oracle Application Server administrators can then access the Application Server Control Console using a separate URL and port number. Meanwhile, the applications you deploy on the other OC4J instances can still be accessed by your application users by using Oracle HTTP Server.
To further protect access to the Application Server Control Console, the administration OC4J can reside on a separate host, but still manage the components of the cluster topology. Figure A-3 shows such a configuration.
Figure A-3 Managing the Cluster Topology Using the Administration OC4J HTTP Listener
To configure an OC4J instance to use its own HTTP URL, instead of a front-end Oracle HTTP Server, change the protocol for the OC4J instance from AJP to HTTP and specify an HTTP port, as follows:
From the Cluster Topology page, click the name of the administration OC4J instance.
From the OC4J Home page, click Administration.
Click the task icon in the Server Properties row of the table on the OC4J Administration page.
In the default-web-site row of the Web sites table, select http from the Protocol drop-down menu and enter a port number or port range in the Port field.
If the administration OC4J instance resides on the same host as Oracle HTTP Server, be sure to use a port or port range that is different from the port used by Oracle HTTP Server.
Click Apply to apply the changes.
Navigate to the Cluster Topology page and restart the administration OC4J instance.
After you restart the administration OC4J, you can then access the Application Server Control Console using the following URL:
http://admin_oc4j_hostname:port/em/
If you do not use a dedicated administration OC4J, you can still configure the OC4J instance so that administrators bypass Oracle HTTP Server and access the Application Server Control Console directly by using a separate HTTP port.
In this scenario, you can configure an additional Web site for the OC4J instance, migrate the existing Application Server Control bindings to the Web site, and configure OPMN to be aware of the Web site. The existing Web site (usually the default-web-site) is then still available for hosting your deployed applications, but Oracle Application Server administrators access the Application Server Control Console using the new Web site and port.
Perform these steps to migrate Application Server Control to its own OC4J Web site:
Copy the ORACLE_HOME/j2ee/home/config/default-web-site.xml file to ORACLE_HOME/j2ee/home/config/ascontrol-web-site.xml (or a file name of your choice).
Edit the ascontrol-web-site.xml file to remove any existing web application bindings. Leave only the <default-web-app> entry and the <web-app> entry for the Application Server Control Console application, shown in bold in the example. This maps the ascontrol application to the root context /em for the Web site. Ensure that the <web-site> element specifies protocol="http", port="1810", and that display-name is a unique name.
<?xml version = '1.0' standalone = 'yes'?> <web-site protocol="http" port="1810 display-name="OC4J 10g (10.1.3) ASControl Web Site" <default-web-app application="default" name="defaultWebApp" root="/j2ee" /> <web-app application="ascontrol" name="ascontrol" root="/em" /> <!-- Access Log, where requests are logged to --> <access-log path="../log/default-web-access.log"/> <!-- Uncomment this if you want to use ODL logging capabilities <odl-access-log path="../log/default-web-access" max-file-size="1000" max-directory-size="10000"/> --> <web-app application="bc4j" name="webapp" root="/webapp" load-on-startup="false"/> </web-site>
Change the access-log path to specify a unique log file for the ascontrol Web site.
Edit ORACLE_HOME/j2ee/home/config/server.xml to add a new <web-site> element that specifies the ascontrol-web-site.xml file, as shown in bold in the following example:
<application-server ...>
...
<web-site default="true" path="./default-web-site.xml" />
<web-site default="false" path="./ascontrol-web-site.xml" />...
</application-server>
Edit ORACLE_HOME/j2ee/home/config/default-web-site.xml to remove or comment out the web-app binding for the ascontrol application.
<web-site protocol="http" port="1810" display-name="OC4J 10g (10.1.3) ASControl Web Site" ... <!-- <web-app application="ascontrol" name="ascontrol" root="/em" / --> </web-site>
Update the OPMN configuration with the additional ascontrol Web site so that OPMN is aware of the port settings of the ascontrol Web site. Issue this command from ORACLE_HOME/opmn/bin:
opmnctl config port update ias-component=OC4J process-type=home portid=ascontrol-web-site protocol="http" range=1810-1820
Restart the server by issuing these commands in ORACLE_HOME/opmn/bin:
opmnctl stopall opmnctl startall
Application Server Control is now accessible at AppHost1:1810/em, and is isolated from Oracle HTTP Server. However, the default application and other applications (deployed as children to the default application) will still use Oracle HTTP Server.
