Using Connection Manager Control Utility (CMCTL)

CMCTL, the Connection Manager Control Utility introduced in the second lesson of this module, remains the tool for starting and administering CMAN in Oracle AI Database 26ai. It is relevant anywhere CMAN itself is deployed, for session multiplexing, network access control, or any of the other features covered earlier in this module. CMCTL runs in two modes: command mode, either interactive through a CMCTL> prompt or as a single command issued from the operating system, and batch mode, running a sequence of commands from a text file.

Setting Up the Environment

Before running CMCTL, the usual Oracle Net environment variables need to be set correctly: ORACLE_HOME, the path to the Oracle installation, and TNS_ADMIN, the directory containing cman.ora, as covered in the fourth lesson of this module. On Linux:

export ORACLE_HOME=/u01/app/oracle/product/26ai/dbhome_1
export PATH=$ORACLE_HOME/bin:$PATH
export TNS_ADMIN=$ORACLE_HOME/network/admin

And on Windows:

set ORACLE_HOME=C:\app\oracle\product\26ai\dbhome_1
set PATH=%ORACLE_HOME%\bin;%PATH%
set TNS_ADMIN=%ORACLE_HOME%\network\admin

Command Syntax and Modes

The basic syntax from the operating system is:

cmctl [command] [argument1 . . . argumentN] [-c instance_name]

If you omit the instance name, CMCTL assumes a default instance name of cman_hostname. The same commands work from the interactive CMCTL> prompt, reached by running cmctl with no arguments. Batch mode runs a file of commands with cmctl @input_file. CMCTL is not limited to administering one instance at a time either: a single CMCTL session can administer one or more Oracle Connection Manager instances, which is what makes it a genuinely centralized administration point rather than a tool you run once per instance.

Selecting an Instance: ADMINISTER

Before starting an instance or changing its settings, select it with ADMINISTER:

CMCTL> ADMINISTER [-c] instance_name

Instance names are defined in cman.ora. Omitting the instance name administers the local instance by default; the -c option is for administering an instance other than the local one. A successful ADMINISTER reports back the instance's current state and the address it is reachable on, something like:

CMCTL> ADMINISTER cman1
Current instance cman1 is already started
Connections refer to (address=(protocol=TCP)(host=proxysvr)(port=1521)).
The command completed successfully

Starting and Stopping: STARTUP and SHUTDOWN

With an instance selected, STARTUP starts it:

CMCTL> STARTUP

STARTUP starts all of an instance's components together, the listener, CMADMIN, and the gateway processes covered in the second lesson of this module, and fails if any of them is already running. A successful startup reports a status summary covering the instance name, version, start time, uptime, the number of gateways started, the current log and trace levels, and the configuration, log, and trace directories in use, roughly:

CMCTL> STARTUP
Starting Oracle Connection Manager instance cman1. Please wait...
Status of the Instance
-----------------------
Instance name            cman1
Version                  CMAN for Linux: Version 26.0.0.0.0
Start date               01-OCT-2026 09:00:00
Uptime                   0 days 0 hr. 0 min. 5 sec
Num of gateways started  4
Average Load level       0
Log Level                SUPPORT
Trace Level              OFF
Instance Config file     $ORACLE_HOME/network/admin/cman.ora
The command completed successfully

SHUTDOWN stops an instance, or specific gateways within it:

cmctl SHUTDOWN [gateways gateway] [normal | abort] [timeout value] [notify] [-c instance_name]

normal, the default, rejects new connections and waits for existing ones to close before terminating. abort shuts CMAN down immediately, closing every open connection. notify tells connected clients that CMAN is shutting down, and timeout sets how long, in seconds, CMAN waits before shutting down. Running SHUTDOWN with no gateway argument shuts down every gateway. A few examples:

CMCTL> SHUTDOWN GATEWAYS 0
CMCTL> SHUTDOWN ABORT
CMCTL> SHUTDOWN NOTIFY

Reconfiguring Without a Restart: RELOAD

As covered in the sixth lesson of this module, RELOAD makes CMCTL dynamically reread both parameters and rules while CMAN keeps running, without needing a STARTUP/SHUTDOWN cycle:

CMCTL> RELOAD

This is the normal way to apply a changed access control rule or a changed parameter in production, reserving a full SHUTDOWN/STARTUP cycle for changes that genuinely require one.

Monitoring Commands: SHOW

SHOW and its variants report on a running instance: SHOW STATUS for overall health, SHOW RULES for the configured access control rules from the sixth lesson of this module, SHOW GATEWAYS for active gateway processes, SHOW CONNECTIONS for current client connections, SHOW PARAMETERS and SHOW DEFAULTS for configuration, SHOW SERVICES for registered services, SHOW STATS for statistics, SHOW EVENTS for logged events, SHOW VERSION for the CMAN version, and SHOW ALL for everything at once.

Adjusting Settings Live: SET

SET and its variants change configuration while CMAN is running, including SET LOG_LEVEL, SET TRACE_LEVEL, SET EVENT, and SET CONNECTION_STATISTICS. These changes take effect immediately but only last until CMAN shuts down; SET cannot write a change back to cman.ora, so anything you want to persist still needs to be added to the file directly and picked up with STARTUP or RELOAD.

Gateway and Connection Control

RESUME GATEWAYS restarts gateway processes that have been suspended, which matters because a suspended gateway stops accepting new work without actually going away, so an administrator has to explicitly bring it back. CLOSE CONNECTIONS terminates specific connections immediately, which is a faster, narrower alternative to a full SHUTDOWN when the goal is to drop a handful of stuck or unwanted sessions rather than the whole instance. CLOSE NON_ADMIN_ENDPOINTS closes every listening endpoint except the administrative one, a way to stop accepting new client traffic without losing the ability to administer the instance, useful when you want to drain an instance for maintenance without losing your own access to it.

Administration in Oracle AI Database 26ai

As covered in the second and fifth lessons of this module, password based administration of CMAN is desupported in Oracle AI Database 26ai. Administration instead uses Local Operating System Authentication (LOSA), which permits only the operating system user who started CMAN to perform admin operations, and a REST interface is also available for remote management through the REST_ADDRESS parameter covered in the third lesson. There is no password prompt anywhere in a current CMCTL session; ADMINISTER selects an instance by name alone, and whether you are allowed to administer it is determined entirely by which operating system account you are running CMCTL as.

A Typical Session

Put together, a routine CMCTL session to check on an instance and apply a configuration change looks like this: run cmctl to reach the interactive prompt, ADMINISTER cman1 to select the instance, SHOW STATUS to confirm it is running and see its current load, edit cman.ora in a text editor to add or change a rule, RELOAD to pick up that change without disrupting existing connections, SHOW RULES to confirm the new rule list took effect, and EXIT or QUIT to leave the utility. A full STARTUP/SHUTDOWN cycle is only necessary for the smaller set of changes RELOAD cannot pick up live.

Troubleshooting a misbehaving instance follows a similar shape, just leaning on different commands: SHOW STATS and SHOW CONNECTIONS to see what the instance is actually doing right now, SET TRACE_LEVEL to turn up tracing temporarily without touching cman.ora, reproduce the problem, then set tracing back down once the trace files have what is needed. Because every SET command here is temporary, there is no cleanup step required in cman.ora itself, a quick RELOAD or restart returns the instance to whatever is actually written in the file.
The next lesson covers the specific commands used to start and stop Oracle Connection Manager in more detail.