1 Overview of Configuration Files and Directories

The configuration and behavior of Oracle Traffic Director is determined by a set of configuration files. You can use the Oracle Fusion Middleware Control and the WebLogic Scripting Tool (WLST) to change the configuration file settings. You can also manually edit these files.

This chapter includes the following topics:

1.1 Configuration Files

Each server instance has its own directory, referred to as INSTANCE_HOME in this document. The INSTANCE_HOME/config directory contains configuration files for Oracle® Fusion Middleware components. The exact number and names of the configuration files depend on the components that were enabled or loaded into the server. For the default location of the INSTANCE_HOME, see Section 1.1.5, "Default Paths".

The following sections describe the configuration files and related information pertaining to Oracle Traffic Director:

1.1.1 The server.xml File

The server.xml file contains the Oracle® Fusion Middleware configuration. For more information about the server.xml file, see Chapter 2, "Syntax and Use of server.xml".

1.1.2 The obj.conf File

The obj.conf file contains directives for HTTP request processing. For more information about the obj.conf file, see Chapter 4, "Syntax and Use of obj.conf.".

1.1.3 The certmap.conf File

The certmap.conf file describes how a certificate is mapped to an LDAP entry designated by issuerDN.

1.1.3.1 Syntax

certmap name issuerDNname:property1 [value1]
name:property2 [value2]
...

The default certificate is named default, and the default issuerDN is also named default. Therefore, the first line defined in the certmap.conf file must be as follows:

certmap default default

Use # at the beginning of a line to indicate a comment.

1.1.3.2 Properties

Table 1-1 describes the properties of certmap.conf file.

Table 1-1 certmap.conf properties

Attribute Allowed Values Default Value Description

DNComps

See description

Commented out

Used to form the base DN for performing an LDAP search while mapping the certificate to a user entry. Values are as follows:

  • Commented out - Takes the user's DN from the certificate as is

  • Empty - Searches the entire LDAP tree (DN == suffix)

  • Comma-separated attributes - Forms the DN

FilterComps

See description

Commented out

Used to form the filter for performing an LDAP search while mapping the certificate to a user entry. Values are as follows:

  • Commented out or empty - Sets the filter to "objectclass=*"

  • Comma-separated attributes - Forms the filter

verifycert

on or off

off (commented out)

Specifies whether certificates are verified.

CmapLdapAttr

Name of the LDAP attribute

certSubjectDN (commented out)

Specifies the name of the attribute in the LDAP database that contains the DN of the certificate.

library

Path to shared lib or dll

None

Specifies the library path for custom certificate mapping code.

InitFn

Name of initialization function

None

Specifies the initialization function in the certificate mapping code referenced by library.


1.1.4 NZ Wallet Files

Wallet files are stored in the INSTANCE_HOME/config directory:

  • ewallet.p12 - an editable wallet, with PIN

  • cwallet.sso - a 'single sign-on' wallet, with obfuscated password (no PIN needed)

There are three NZ wallet operational modes. All three modes are supported by the OTD core server, but the admin may not support all of them. The modes are:

  • only ewallet.p12 - a PIN is always needed, whether OTD accesses the wallet in read-only mode, or the admin accesses the wallet in read-write mode. OTD prompts for the PIN on startup. The PIN is not stored in server.xml.

  • only cwallet.sso - called "auto-login only" mode in orapki. No PIN is required, whether OTD accesses the wallet in read-only mode, or the admin accesses the wallet in read-write mode.

  • both ewallet.p12 and cwallet.sso - called "auto-login" mode in orapki. OTD doesn't require a PIN to access the wallet in read-only mode, but the admin requires a PIN to access the wallet in read-write mode. Edits are made to ewallet.p12. After each edit, ewallet.p12 is converted to cwallet.sso.

Use the Oracle orapki command line utility to manage public key infrastructure (PKI) elements such as wallets. For more information, see the appendix Using the orapki Utility to Manage PKI Elements in the Oracle Database Security Guide

1.1.5 Default Paths

The default paths used in Oracle® Fusion Middleware are listed below. Table 1-2 describes the default paths and file names.

Table 1-2 Default Paths

Placeholder Description

ORACLE_HOME

The directory in which Oracle® Fusion Middleware is installed.

INSTANCE_HOME

The directory that contains the files pertaining to the Oracle® Fusion Middleware administration server and Oracle® Fusion Middleware instances.


1.2 Directory Structure

This section describes the directory structures that are created when you first install Oracle® Fusion Middleware. In a typical OTD installation, all directories are located in the ORACLE_HOME directory, except for the admin-server directory and net-server-id instance subdirectory. The admin-server directory and the net-server-id subdirectory are located in the INSTANCE_HOME directory. Creating an administration server or an administration node requires you to execute the configure-server command. To create an administration node in OTD, you must make sure that the administration server is up and running. The newly created administration node will be registered with the administration server. Before creating any instances, create an administration server by running the configure-server command. Later, execute the create-instance command to create instances in OTD. For more information about the CLI commands, see Oracle Traffic Director Command-line Reference. For more information about the default locations for these directories, see Section 1.1.5, "Default Paths".

The following directories exist under the Oracle® Fusion Middleware installation directory, ORACLE_HOME:

1.2.1 bin

The bin directory contains the commands to administer Oracle Traffic Director, including the WebLogic Scripting Tool Command interface (WLST).

1.2.2 Legal

The Legal directory contains the third party information pertaining to the Oracle® Fusion Middleware software.

1.2.3 lib

The lib directory contains internal binaries, scripts, libraries, and bundled plug-ins. These are private files, for internal use only.

For information about the admin-server directory and net-server-id subdirectory see:

1.2.4 admin-server

The admin-server directory contains the following subdirectories:

  • bin - contains binary files used to start, stop, and restart Oracle® Fusion Middleware. On UNIX systems, this directory also contains the file required for rotating logs.

  • config - contains private configuration files for the administration server. These files are for internal use.

  • config-store - contains files used by the administration server to track server configuration information.

Note:

The files in this directory are created by Oracle® Fusion Middleware for internal use. Do not edit, run scripts on, or otherwise access any files in the config-store directory.
  • generated - contains files generated by the instance, such as Java class files corresponding to JavaServer Pages (JSP).

  • logs - contains any error messages or access log files generated by a server instance.

1.2.5 net-server-id

A net-server-id directory is created for every instance you create in OTD. This directory has the following subdirectories and files:

  • bin - contains the commands for starting, stopping, restarting, and reconfiguring the server. It also contains the command for rotating the log files.

  • config - contains the following instance-specific configuration files:

    • <C1>-obj.conf - virtual server specific directory.

    • obj.conf - Oracle® Fusion Middleware directives for handling HTTP requests from clients.

    • pkcs11.txt - NSS PKCS #11 module database.

    • server.xml - most of the server configuration settings.

  • logs - contains log files generated by this server instance.

1.3 Dynamic Reconfiguration

Dynamic reconfiguration enables you to make configuration changes to a running Oracle Traffic Director instance, without having to stop and restart it in order for the changes to take effect.

Dynamic configuration happens:

  • When you deploy a configuration through the Administration Console or CLI

  • When you run the reconfig script in the server instance's bin directory

You can dynamically change the configuration settings in the obj.conf file without restarting the server. In addition, most settings in the server.xml file can be changed without restarting the server. If you must restart the server, a warning message appears in the server log when you deploy the configuration or run the reconfig command.

You cannot dynamically reconfigure the following server.xml configuration parameters:

  • user

  • temp-path

  • log (with the exception of log-level)

  • thread-pool

  • pkcs11

  • stats

  • dns

  • dns-cache

  • ssl-session-cache

  • access-log-buffer

When you run the reconfig command, a new configuration object is created, and all new incoming requests are processed based on this new configuration object. The current configuration object is removed when no HTTP requests are using the object.

In case an erroneous configuration occurs during dynamic reconfiguration, the server displays an error message. The server logs the error message to a log file specified by the last configuration that worked.

Certain erroneous configurations result in warning messages but do not cause the server to reject the configuration. Other erroneous configurations trigger error messages and cause the server to reject the configuration. If the server rejects a configuration during startup, the server does not start. If the server rejects a configuration during a dynamic reconfiguration, the server reverts to the last configuration that worked.