Structure and Function of the cman.ora File

The cman.ora file is Oracle Connection Manager's configuration file, and it governs the listener, CMGW, and CMADMIN processes covered in the second lesson of this module. CMAN will not start without a valid cman.ora file. It plays a role for Connection Manager similar to the one sqlnet.ora and listener.ora play elsewhere in Oracle Net Services: a plain text file that Oracle Net components read at startup, editable by hand or through configuration tools such as Oracle Net Configuration Assistant.

File Sections

A cman.ora configuration is wrapped under a top level CMAN= identifier and consists of three sections, all encapsulated within a single name value string:

• Listening address, preceded by ADDRESS=, specifying the protocol address CMAN listens on
• Rule list, preceded by RULE_LIST= (or RULE_GROUP= when rules are organized by service, as covered in the previous lesson), specifying which connections are accepted, rejected, or dropped
• Parameter list, preceded by PARAMETER_LIST=, specifying every other configuration setting: connection pooling, logging, tracing, resource limits, and security

Every CMAN instance needs at least the listening address and a rule list to do anything useful; the parameter list is where everything else, from trace levels to bandwidth limits, gets tuned. The rule list specifically needs at least one rule covering client connections and one covering CMCTL connections; omitting either type means every connection of that type is rejected, not just unmatched ones, since an empty rule list for a connection type is treated the same as a rule list with no matches.

Example: Listening on Multiple Protocol Addresses

A cman.ora file can be configured to listen on more than one address at once, the same way listener.ora can. The example below shows CMAN listening on both TCP and TCPS, letting it accept an encrypted connection from one kind of client and a plain connection from another on the same instance, consistent with the TLS coverage in the previous lesson:

CMAN=
  (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=cman-server)(PORT=1521))
    (ADDRESS=(PROTOCOL=tcps)(HOST=cman-server)(PORT=1522))
  )

Two refinements to this basic address syntax are worth knowing. First, an individual address can be tagged as an admin endpoint by adding (ADMIN=YES) to it, which is useful when you want to close off the regular client facing endpoints without losing the ability to run CMCTL admin commands against the instance. Second, CMAN can be configured to receive a client's real IP address from a load balancer sitting in front of it, by enabling the PROXY protocol on a listening address and supplying an EXPECTED_PROXIES list of the load balancer addresses CMAN should trust:

(ADDRESS_LIST=
  (ADDRESS=(PROTOCOL=tcp)(HOST=host_name)(PORT=port_number_1))
  (ADDRESS=(PROTOCOL=tcp)(HOST=host_name)(PORT=port_number_2)
    (EXPECTED_PROXIES=ip_address_1, ip_address_2)))

The plain listening address without EXPECTED_PROXIES must come before the PROXY enabled address in the file, and database registration is not supported on the PROXY protocol enabled endpoint itself.

Default File Location

By default, cman.ora is located in ORACLE_HOME/network/admin for a database installation. It can also live in the directory specified by the TNS_ADMIN environment variable, in GRID_HOME/network/admin for an Oracle Grid Infrastructure installation, or in ORACLE_BASE_HOME/network/admin for a read only Oracle home.

When more than one of these locations exists on a system, Oracle Net searches them in a fixed order, the same order it uses for its other configuration files: the directory named by TNS_ADMIN takes priority if it is set and the file is found there, followed by ORACLE_HOME/network/admin (or ORACLE_BASE_HOME/network/admin for a read only home) on Linux and UNIX, with Windows using the equivalent backslash paths. For a read only Oracle home specifically, if the file is not found under the Oracle base home, Oracle Net falls back to ORACLE_HOME/network/admin as a last resort.

cman.ora Trace Parameters

Table 6-4 describes the trace parameters that can be set in the cman.ora file.

Table 6-4 cman.ora Trace Parameters

cman.ora Parameter	Description
TRACE_DIRECTORY	The destination directory for trace files. The default is ORACLE_BASE_HOME/network/trace.
TRACE_FILELEN	The size of the trace file, in KB. When the size is reached, the trace information is written to the next file. The number of files is specified with the TRACE_FILENO parameter. Unlimited by default.
TRACE_FILENO	The number of trace files for tracing. When this parameter is set along with TRACE_FILELEN, trace files are used in a cyclical fashion: the first file is filled, then the second, and so on, and when the last file has been filled the first file is reused. The trace file names are distinguished from one another by their sequence number. For example, if this parameter is set to 3, the gateway trace files are named instance_name_cmgw1_pid.trc, instance_name_cmgw2_pid.trc, and instance_name_cmgw3_pid.trc, and each trace event is preceded by its file's sequence number. The default is 1.
TRACE_LEVEL	The level of detail the trace facility records. Values are off for no tracing, user to identify user induced error conditions, admin to identify installation specific problems, and support for the detail Oracle Support Services needs to troubleshoot. The default is off. The Oracle Connection Manager listener, gateway, and CMADMIN processes each create their own trace files, on both Linux and Microsoft Windows.
TRACE_TIMESTAMP	Adds a timestamp in the form dd-mmm-yyyy hh:mi:ss:mil to every trace event in the trace file when enabled. Values are on/true or off/false, and the default is on.

Logging and tracing are configured separately but follow a similar pattern. LOG_LEVEL, the logging counterpart to TRACE_LEVEL, accepts the same four named values, off, user, admin, and support, each of which also has a numeric equivalent (0, 4, 10, and 16 respectively) if you prefer to set it that way, and it defaults to support rather than off. Where TRACE_LEVEL controls how much detail goes into the trace files used to diagnose a specific problem, LOG_LEVEL controls the ongoing log of what CMAN has been doing, and the two are usually tuned independently: a busy production instance might run with light logging all the time and tracing turned up only while actively troubleshooting an issue.

ADR and Non-ADR Diagnostics

One detail in the trace parameter table above is easy to miss and matters in practice: Oracle's Automatic Diagnostic Repository (ADR), the fault diagnosability infrastructure introduced in Oracle Database 11g, is enabled for Oracle Connection Manager by default. While ADR is enabled, TRACE_DIRECTORY, TRACE_FILELEN, and TRACE_FILENO are non-ADR parameters and are simply ignored; CMAN writes its diagnostic data into the ADR instead, under a base directory controlled by the ADR_BASE parameter, which defaults to ORACLE_BASE or to ORACLE_HOME/log if ORACLE_BASE is not defined. TRACE_LEVEL and TRACE_TIMESTAMP are the two exceptions in the table: both apply whether ADR is enabled or not.

If you want the classic, manually sized and numbered trace files the table describes, set DIAG_ADR_ENABLED=off in the parameter list first. Only then do TRACE_DIRECTORY, TRACE_FILELEN, and TRACE_FILENO take effect. Leaving ADR enabled, the default and generally the recommended setting, means CMAN's critical error diagnostics get the same incident based capture and tagging the rest of Oracle AI Database 26ai uses, rather than a set of plain rotating trace files you have to size and manage yourself.

Putting the Sections Together

A complete cman.ora file combines everything covered so far and in the previous lesson into the three sections described at the top of this lesson. The skeleton below shows the shape of a realistic configuration, with an address list, a rule list, and a parameter list that enables bandwidth control and sets a support level trace with ADR left at its default:

CMAN=
  (CONFIGURATION=
    (ADDRESS_LIST=
      (ADDRESS=(PROTOCOL=tcp)(HOST=cman-server)(PORT=1521))
      (ADDRESS=(PROTOCOL=tcps)(HOST=cman-server)(PORT=1522)))
    (RULE_LIST=
      (RULE=(SRC=app-tier)(DST=sales-server)(SRV=sales.us.example.com)(ACT=accept))
      (RULE=(SRC=cman-admin-host)(DST=*)(SRV=cmon)(ACT=accept)))
    (PARAMETER_LIST=
      (MAX_GATEWAY_PROCESSES=16)
      (MIN_GATEWAY_PROCESSES=4)
      (BANDWIDTH=524288)
      (MAX_BANDWIDTH_GROUP=10)
      (TRACE_LEVEL=support)))

Reading a file like this now, you should be able to pick out the listening addresses, see where incoming connections are accepted or rejected, and recognize the operational parameters, the same bandwidth and gateway process settings covered earlier in this module, all living inside the parameter list.

With the structure of cman.ora covered, the remaining lessons in this module build on this file directly, since every feature discussed so far, access control rules, session multiplexing, TLS, compression, bandwidth limits, and Traffic Director Mode, is ultimately configured through the sections described above.