Skip Headers

Oracle® Application Server Administrator's Guide 10g Release 3 (10.1.3) B25209-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# A Managing and Configuring Application Server Control

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

- Starting and Stopping Application Server Control

- Changing the Application Server Control Administrator Password

- Configuring Security for the Application Server Control Console

- Configuring Logging for Application Server Control

- Enabling Enterprise Manager Accessibility Mode

- Publishing Application Server Control Console to a Separate Web Site

## A.1 Starting and Stopping Application Server Control

For Oracle Application Server 10g Release 3 (10.1.3), 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 `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 `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.

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.

### A.1.1 Verifying That the Application Server Control Is Running

You can verify the Application Server Control is started by pointing your browser to the Application Server Control Console URL:

    http://hostname.domain:port/em

For example, on UNIX:

    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

See Also: Section 2.3.1, "Displaying the Application Server Control Console"

## A.2 Changing the Application Server Control Administrator Password

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.

The `oc4jadmin` user represents the default administrator account for the Application Server Control Console. Administrators who log in using the `oc4jadmin` account—as well as administrators who have been assigned the `ascontrol_admin` role—can create additional Application Server Control users with specific management roles.

See Also: Section 2.3.3, "Creating Administrative Users and Assigning Administrative Roles"

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 Your Own Administrator Account

- Changing the oc4jadmin Password for the Administration OC4J Instance

- Changing the oc4jadmin Password for a Remote OC4J Instance

### A.2.1 Changing Your Own Administrator Account

To change your own administrator account:

1. Log in to the Application Server Control Console using your administrator username and password.

2. 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.2, "Changing the oc4jadmin Password for the Administration OC4J Instance" for more information.

3. 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 the following characters; 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.

4. Click OK to reset the password.

   The next time you log in, you must use the new password.

### A.2.2 Changing the oc4jadmin Password for the Administration OC4J Instance

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.

The following considerations are especially important if you have installed or configured a cluster and if you are using groups:

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

  See Also: Section 2.3.5.1, "Viewing the Cluster Topology and Locating the Active Application Server Control"

- If you have created a group and are performing any group operations, note that all OC4J instances that are part of the group must have the same `oc4jadmin` password; otherwise, Enterprise Manager displays an error message when you attempt to display the Group home page.

  Additionally, the `oc4jadmin` password for the Administration OC4J must also be the same as the `oc4jadmin` password used by all OC4J instances in the group.

### A.2.3 Changing the oc4jadmin Password for a Remote OC4J Instance

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 perform the following steps:

1. 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.5.1, "Viewing the Cluster Topology and Locating the Active Application Server Control"

   Enterprise Manager displays the OC4J home page for the selected remote instance.

2. Click Administration to display the list of administration tasks you can perform on the selected OC4J instance.

3. Click the task icon in the Security Providers row of the table.

4. On the Security Providers page, click Instance Level Security.

5. On the Instance Level Security page, click Realms.

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

7. Click oc4jadmin to modify the `oc4jadmin` user account.

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

9. Return to the Cluster Topology page and restart the remote OC4J instance.

## A.3 Configuring Security for the Application Server Control Console

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:

- Securing Communication Between Browser Clients and Web Servers That Host Application Server Control Console

- Securing Communication Between Components of Oracle Application Server

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: Oracle Containers for J2EE Security Guide Oracle HTTP Server Administrator's Guide

### A.3.1 Securing Communication Between Browser Clients and Web Servers That Host Application Server Control Console

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:

1. Stop the Administration OC4J instance.

2. 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 mykeystore -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 the section "Using Keys and Certificates with OC4J and Oracle HTTP Server" in the Oracle Containers for J2EE Security Guide for more information about the keystore command.

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:

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

2. 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" />

3. 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:

1. 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`.

2. 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 browsers 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.

3. 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:

1. Locate the `server.xml` file in the `ORACLE_HOME` `/j2ee``/Admin_OC4J_instance_name/``config` directory.

2. 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" />

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

### A.3.2 Securing Communication Between Components of Oracle Application Server

Depending on your operational 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 the Oracle Application Server Cluster 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

#### A.3.2.1 Securing Communication Between the Administration OC4J and Remote OC4J Instances

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:

1. Create a keystore with an RSA private/public keypair using the `keytool` command. This creates the SSL certificate that OC4J will use for secure RMI communication with other OC4J instances. The keytool executable is located in the `ORACLE_HOME``/jdk/bin` directory. Use the following command:

       keytool -genkey -keyalg "RSA" -keystore mykeystore -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 the section, "Using Keys and Certificates with OC4J and Oracle HTTP Server" in the Oracle Containers for J2EE Security Guide for more information about the keystore command.

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

3. Open the `rmi.xml` file with a text editor and add the `<ssl-config>` element to the contents of the file.

4. 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" />

5. 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:

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

2. 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:

1. Locate the following configuration file in the Oracle home:

       (UNIX) ORACLE_HOME/opmn/conf/opmn.xml
       (Windows) ORACLE_HOME\opmn\conf\opmn.xml

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

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

2. 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 `opmn.xml` file.
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.

#### A.3.2.2 Securing OPMN Communication in an Oracle Application Server Cluster

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 instance can gain process control over the cluster.

During installation, OPMN is configured to use a default wallet containing a default SSL certificate. If you do not replace the default wallet in each OPMN in your cluster, then any default installation of Oracle Application Server will be able to join your cluster.

To secure your cluster, take the following steps in each Oracle Application Server instance:

1. Use Oracle Wallet Manager to replace the default wallet used by OPMN with a secure wallet containing a unique certificate. (See Section 11.1.3, "How To Create a Complete Wallet: Process Overview" for information on how to create a wallet.)

   Note the following:

   - You must generate a certificate request: For the Common Name, specify the name or alias of the site you are configuring.

   - You must enable the auto-login feature.

2. Ensure that the SSL certificate of each OPMN instance is trusted by all other OPMN instances. For example, if the SSL certificate of one OPMN instance is not signed by a Certificate Authority that a second OPMN instance trusts, then the SSL certificate of the first OPMN instance needs to be imported into the wallet of the second OPMN instance. Take the following steps:

   1. For each OPMN instance, use Oracle Wallet Manager to export the certificate. See Section 11.1.5.2, "Managing Trusted Certificates" for more information on exporting certificates.

   2. Use Oracle Wallet Manager to import the certificate into each of the other OPMN instances. See Section 11.1.5.2, "Managing Trusted Certificates" for more information on importing certificates.

See the Oracle Process Manager and Notification Server Administrator's Guide for more information about OPMN and security.

## A.4 Configuring Logging for Application Server Control

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

- Configuring Logging Properties When ODL Is Not Enabled

### A.4.1 Enabling and Configuring ODL for the Application Server Control Log File

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, "Configuring the Application Server Control Logging Properties to Enable ODL", 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:

- Configuring the Application Server Control Logging Properties to Enable ODL

- About the Application Server Control ODL Logging Properties

- Configuring Logging Properties When ODL Is Not Enabled

#### A.4.1.1 Configuring the Application Server Control Logging Properties to Enable ODL

To configure the Application Server Control to support ODL:

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

2. Use a text editor to edit the following configuration file in the `config` directory:

       ascontrollogging.properties

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

4. Save and close the `ascontrollogging.properties` file.

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

#### A.4.1.2 About the Application Server Control ODL Logging Properties

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 `log.xml` file will be saved.
log4j.appender.emiaslogAppender.MaxSize | Determines the maximum amount of disk space to be used by the `log.xml` file and the logging rollover files.
log4j.appender.emiaslogAppender.MaxSegmentSize | Determines the maximum size of the `log.xml` file. When the `log.xml` file reaches this size, a rollover file is created.

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

### A.4.2 Configuring Logging Properties When ODL Is Not Enabled

If you do not enable ODL, you can still configure the logging properties for the Application Server Control by modifying the `ascontrollogging.properties` file:

1. 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\

2. Use a text editor to edit the following configuration file in the `config` directory:

       ascontrollogging.properties

3. Modify the selected logging properties described in Table A-3.

4. Save and close the `ascontrollogging.properties` file.

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

## A.5 Enabling Enterprise Manager Accessibility Mode

The following sections provide information on the benefits of running Enterprise Manager in accessibility mode, as well as instructions for enabling accessibility mode:

- Making HTML Pages More Accessible

- Providing Textual Descriptions of Enterprise Manager Charts

- Modifying the uix-config.xml File to Enable Accessibility Mode

### A.5.1 Making HTML Pages More Accessible

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.

### A.5.2 Providing Textual Descriptions of Enterprise Manager Charts

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-1 shows an example of the icon that appears below each chart after you enable accessibility mode.

Figure A-1 Icon Representing the Textual Representation of a Chart

Description of "Figure A-1 Icon Representing the Textual Representation of a Chart"

### A.5.3 Modifying the uix-config.xml File to Enable Accessibility Mode

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

2. Open the `uix-config.xml` file using your favorite text editor and locate the following entry:

       <!-- An alternate configuration that disables accessibility features  -->
       <default-configuration>
         <accessibility-mode>inaccessible</accessibility-mode>
       </default-configuration>

3. Change the value of the `accessibility-mode` property from `inaccessible` to `accessible`.

4. Save and close the file.

5. Restart the Application Server Control Console.

## A.6 Publishing Application Server Control Console to a Separate Web Site

For security reasons, you may want Application Server Control Console to be available on a separate Web site. For example, suppose you have two Oracle Application Server instances, WebHost1 and WebHost2 and they are exposed as external sites. However, you want Application Server Control Console not to be exposed. In this case, you must change Application Server Control Console to listen on a different port for the OC4J installations.

To do this, you create an additional Web site for OC4J, migrate the existing Application Server Control Console bindings to the Web site, and configure OPMN to be aware of the Web site.

Perform these steps on a separate host (AppHost1 in this example) to make Application Server Control Console accessible on a separate Web site:

1. 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).

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

3. Change the `access-log path` to specify a unique log file for the ascontrol Web site.

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

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

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

7. 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 the Oracle HTTP Server. However, the default application and other applications (deployed as children to the default application) will still use Oracle HTTP Server.