Connection Manager's Programs

At an internal level, Oracle Connection Manager's running architecture is built from three pieces: the listener, CMGW (the Connection Manager Gateway), and CMADMIN (Connection Manager Administration). A fourth name, CMCTL (the Connection Manager Control Utility), is the command line tool administrators use to start, stop, and manage the other three. CMCTL is not itself a running server process the way the listener, CMGW, and CMADMIN are, but Oracle's own documentation has grouped it alongside CMGW and CMADMIN as "the three programs" of Connection Manager since at least the Net8 era, and this lesson follows that same traditional grouping while being precise about what each piece actually does.

Let us examine the function of each, and then walk through how a single client connection moves through all four pieces from start to finish.

A client connects to the listener first, not to CMGW directly. The listener evaluates the incoming request against CMAN's access control rules and decides whether to allow it. If the request is allowed, the listener forwards it to whichever CMGW gateway process currently has the fewest connections, spreading load across gateways rather than piling every new connection onto the same one. CMGW then relays the request to its next hop, either another Connection Manager or the database server itself, and keeps relaying data for as long as the session lasts. If a connection to that same destination already exists, CMGW multiplexes the new session through it instead of opening a second one.
Laid out step by step, a single connection attempt looks like this:

1. A client sends a connection request to CMAN's configured listening address.
2. The listener checks the request against the access control rules defined in cman.ora and either allows or rejects it.
3. An allowed request is handed to the CMGW process with the fewest current connections.
4. CMGW either opens a new connection to the next hop or, if one already exists, multiplexes the request through it.
5. CMGW relays data between client and destination for the life of the session.

Oracle's own architecture documentation illustrates this with a concrete example worth repeating here: a gateway process registers with CMADMIN, and CMADMIN in turn registers with the listener. When three valid client connections arrive, the gateway process multiplexes all three through a single network protocol connection to the database. A fourth connection, if it fails the access control check, is simply denied before it ever reaches the gateway at all. That is the whole point of putting the listener's rule evaluation first in the chain: a rejected client never gets as far as consuming a CMGW resource.

Meanwhile, CMADMIN is watching the listener and every CMGW process in the background, starting or stopping them as needed and registering each gateway's location and current load with the listener. It also answers any administrative requests sent in through CMCTL. One more detail ties the whole chain together: the listener itself carries no service information to hand out until Oracle's Listener Registration process, LREG, registers it, the same background process responsible for registering database services with any Oracle Net listener.

Why the Work Is Split Across Three Programs

It is worth pausing on why Oracle built Connection Manager as three separate pieces rather than one monolithic process. The listener and CMGW together form the data path, the part of CMAN that touches every byte of client traffic and therefore needs to be as fast and lean as possible. CMADMIN is deliberately kept separate from that data path. It handles bookkeeping, monitoring, and restart logic instead, work that would otherwise compete with CMGW for the same resources under heavy connection load. CMCTL, in turn, is separate again: it is the interface a human uses, and it has no reason to run continuously the way the other three do. Keeping the control interface, the administrative brain, and the data path as independent pieces is what lets CMADMIN restart a failed CMGW process without interrupting the listener, and what lets an administrator run CMCTL commands without touching the processes actually carrying live traffic.

Connection Manager Gateway (CMGW)

CMGW is the data path. It is worth being precise about one point that older course material and older third party summaries sometimes get backwards: CMGW does not listen for incoming client connections itself. That is the listener's job. CMGW only sees a request after the listener has already screened it and handed it off.

Once that handoff happens, CMGW takes over three distinct responsibilities. First, it forwards the request to the next hop, which can be another Connection Manager or the database server directly. Second, it relays data between client and server for the entire lifetime of that session, and it multiplexes multiple client sessions through a single transport connection whenever one already exists to the destination, which is the same session multiplexing behavior covered in the previous lesson. Third, it enforces the access control rules defined in cman.ora as traffic passes through it, giving CMGW a firewall-like role in addition to its routing role. CMGW can also perform protocol conversion, letting a client and a server that are configured for different underlying network protocols still reach each other through the gateway.

Connection Manager Administration (CMADMIN)

CMADMIN is the control process. Its job is to monitor the state of the listener and every CMGW process, starting or stopping them as needed, to register each gateway's location and load with the listener so new connections get distributed to the least busy gateway, and to answer administrative requests coming in from CMCTL. The registration chain runs in one direction: a gateway process registers with CMADMIN, and CMADMIN registers with the listener, which is how the listener always knows which gateway process is currently least busy without having to track that information itself.

A note is worth adding here for anyone working from older course material or older third party summaries of CMAN. CMADMIN's role has sometimes been described as maintaining address information in an Oracle Names Server, locating local Oracle Names servers, and updating that Names Server as the network changes. That description has not been accurate for a long time. Oracle Names was desupported starting with Oracle Database 10g, as covered in the previous lesson, and Oracle's current documentation of CMADMIN's role makes no mention of it at all. For a broader look at where Oracle naming and connectivity have moved since the Oracle Names era, see our guide to modern Oracle connection methods. The load balancing and process monitoring role described above, registering gateway location and load with the listener and starting or stopping processes as needed, is what CMADMIN actually does today, and that role has nothing to do with directory servers of any kind.

Connection Manager Control Utility (CMCTL)

CMCTL is the executable name for Connection Manager's command line control utility. You run it as cmctl, either passing a command directly on the same line or working from its own interactive CMCTL> prompt. A single cmctl STARTUP command starts the listener, CMADMIN, and the gateway processes together for a given CMAN instance, and cmctl SHUTDOWN stops all three the same way. At the interactive prompt, the equivalent sequence is to run ADMINISTER against the instance name first, then issue STARTUP or SHUTDOWN.

Beyond starting and stopping CMAN, CMCTL is how administrators view or change configuration settings, check the current status of the listener and gateway processes, inspect access control rules, and manage logging and tracing. A few of its other built-in commands are worth knowing by name: RELOAD picks up configuration changes from cman.ora without a full restart, SET and SHOW let an administrator change or inspect an individual parameter at runtime rather than editing the file directly, and HELP gives command syntax from within the utility itself. Taken together, CMCTL is the single interface for everything an administrator needs to do to CMADMIN and CMGW without editing cman.ora and restarting the whole service.

One thing has genuinely changed here for Oracle AI Database 26ai: password access to CMAN administration through CMCTL is desupported. In its place, Oracle provides Local Operating System Authentication, abbreviated LOSA, which permits only the operating system user who originally started CMAN to perform admin operations against it through CMCTL. This brings CMAN's administrative access model in line with how operating system authentication already works elsewhere in the database, and it closes off a class of problem that password based admin access always carried: a password that can be guessed, shared, or left at a default. Anyone still relying on a CMAN password today should remove it and rely on LOSA instead.

---

Summary of Internal Components

Component	Purpose
Listener	Receives client connections and evaluates them against CMAN's access control rules before handing allowed requests to a gateway.
CMGW	Relays and multiplexes client sessions to their destination, enforces access control rules in transit, and can perform protocol conversion.
CMADMIN	Monitors and controls the listener and gateway processes, registers gateway load with the listener, and answers CMCTL.
CMCTL	Command line utility used to start, stop, configure, and monitor the other three components; administered today through LOSA rather than a CMAN password.

These four pieces, the listener screening requests, CMGW relaying and multiplexing them, CMADMIN keeping the first two running and balanced, and CMCTL giving administrators a single point of control, work together to provide a robust and flexible mechanism for managing client connections in both traditional and cloud enabled Oracle database environments.

CMADMIN Log File Example
The excerpt below is a real CMADMIN log capture, originally dated 2003, and it is worth keeping around because it is a genuinely useful illustration of what a CMADMIN log record actually looks like. The first block records CMAN's parameter list at startup: the listener address it is bound to (usunnae16 on port 1574), connection limits such as max_connections=256 and max_gateway_processes=1, timeout values governing how long an idle or inbound connection is allowed to sit before CMAN closes it, and logging and tracing settings, followed by the shared memory size CMADMIN allocated for itself. The second block shows CMADMIN's event stream once it is running: a GMON Attributes validated event confirming its internal generic monitor state is sound, an NS Listen Successful event showing the address it successfully bound to, and then a series of received commands with the outcome of each, ending in a normal shutdown.

One thing is worth flagging explicitly before you read through it. Several of the commands in this capture are verify password requests, and one of the logged parameters is password=OFF. Both reflect the old CMAN password authentication model this lesson just covered as desupported in Oracle AI Database 26ai in favor of LOSA. The log format itself is still representative of what you will see from a current CMADMIN instance. The authentication method it happens to be exercising in this particular capture is not current, so treat the verify password lines as a historical artifact of the log sample rather than something to replicate in a 26ai environment.

-------------------------------
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:46:40)(EVENT=Parameter list)
(listener_address=(address=(protocol=tcp)(host=usunnae16)(port=1574)))
(aso_authentication_filter=OFF)
(connection_statistics=ON)
(log_directory=/home/user/network/admin/log)
(log_level=support)
(max_connections=256)
(idle_timeout=5)
(inbound_connect_timeout=0)
(session_timeout=20)
(outbound_connect_timeout=0)
(max_gateway_processes=1)
(min_gateway_processes=1)
(password=OFF)
(remote_admin=ON)
(trace_directory=/home/user/network/admin/log)
(trace_level=off)
(trace_timestamp=OFF)
(trace_filelen=0)
(trace_fileno=0)
)
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:46:40)(EVENT=Shared Memory Size)

(BYTES=82524))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:46:40)(EVENT=GMON Attributes validated)
(Type=Information))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:46:40)(EVENT=NS Listen Successful)
((ADDRESS=(PROTOCOL=tcp)(HOST=usunnae16)(PORT=55878))))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:46:44)(EVENT=Received command)(CMD=verify
password))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:46:44)(EVENT=Received command)
(CMD=version))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:46:44)(EVENT=Received command)
(CMD=show status))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:46:44)(EVENT=Failed to get procedure id))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:49:12)(EVENT=Received command)(CMD=verify
password))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:49:15)(EVENT=Failed to get procedure id))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:49:29)(EVENT=Received command)(CMD=verify
password))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:49:46)(EVENT=Failed to get procedure id))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:49:50)(EVENT=Received command)(CMD=verify
password))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:49:50)(EVENT=Received command)
(CMD=probe monitor))
(LOG_RECORD=(TIMESTAMP=08-MAY-2003 08:49:50)(EVENT=Received command)
(CMD=shutdown normal))
-------------------------------

In the next lesson, you will examine some features of CMAN that warrant more detailed discussion.