Note:

Install and Configure Oracle Connection Manager

Introduction

Oracle Connection Manager (CMAN) is an Oracle utility that acts as a proxy server to forward connection requests from clients to databases. It operates on the session level and is usually installed on a separate server.

image

CMAN Use Cases

Objectives

Prerequisites

Task 1: Initial Setup for Oracle Connection Manager Installation

In this tutorial, we will use the following IP addresses.

Open Firewall Connection

Port should be open from client VM to CMAN VM on 1999 and from CMAN VM to database server on 1521.

Task 2: Install Oracle Connection Manager on Oracle Connection Manager Virtual Machine

  1. Prepare the CMAN VM for installation. Run the following command to create the Oracle user, install packages, change kernel parameters, and so on.

    $sudo su - root
$yum install oracle-database-preinstall-21c.x86_64

  2. Run the mkdir -p $HOME/stage command to create the directory.

  3. Download Oracle Client 21.3.0 from: Oracle Database 21c, copy on the CMAN VM using winscp or any other file transfer utility under $HOME/stage.

    If you cannot use SSH, open the Oracle Database 21c client download page in the browser and click to download the LINUX.X64_213000_client.zip file for Linux. Open the browser, right-click the file in Downloads and select the Copy Download Link as follows.

    The AuthParam URL parameter will vary every time you click the download link. On your Linux machine, navigate to the required directory (for example, $HOME/stage) and enter the following command:

    $ wget "https://download.oracle.com/otn/linux/oracle21c/LINUX.X64_213000_client.zip?AuthParam=1631008911_576110421cdef54a2d47d9562bee0e5a" -O LINUX.X64_213000_client.zip

  4. Unzip client software as Oracle user. A directory named client will be created.

    [oracle@cman stage]$ ls -ltr /home/oracle/stage
drwxr-xr-x. 5 oracle oinstall         90 Jul 27  2021 client
-rwxr-xr-x. 1 oracle oinstall 1075931428 Sep  1 10:40 LINUX.X64_213000_client.zip

  5. Now, install CMAN and SQL*Plus.

    Run the following command to create the new Oracle user (oracle), base, and home directories for running CMAN (install the pre-install libraries of the latest version of Oracle Database for setting up the Oracle user in Linux) .

    $ sudo su - root
$ yum install oracle-database-preinstall-21c.x86_64
$ mkdir /u01
$ chown oracle:oinstall /u01
$ su - oracle
$ mkdir -p /u01/app/oracle/product/cman2130

  6. Prepare the response file for installing CMAN and SQL*Plus.

    $ cat <<EOF > $HOME/client21.rsp
oracle.install.responseFileVersion=/oracle/install/rspfmt_clientinstall_response_schema_v21.0.0
ORACLE_HOSTNAME=$(hostname)
UNIX_GROUP_NAME=oinstall
INVENTORY_LOCATION=/u01/app/oraInventory
SELECTED_LANGUAGES=en
ORACLE_HOME=/u01/app/oracle/product/cman2130
ORACLE_BASE=/u01/app/oracle
oracle.install.client.installType=Custom
oracle.install.client.customComponents="oracle.sqlplus:21.0.0.0.0","oracle.network.client:21.0.0.0.0","oracle.network.cman:21.0.0.0.0","oracle.network.listener:21.0.0.0.0"
EOF

  7. Run the following command to install CMAN.

    $HOME/stage/client/runInstaller -silent -responseFile $HOME/client21.rsp  ORACLE_HOME_NAME=cman2130

  8. Finalize the installation as root user. Run as root user to complete the installation.

    $ /u01/app/oraInventory/orainstRoot.sh
$ /u01/app/oracle/product/cman2130/root.sh

  9. Append the following lines to your .bash_profile file ($HOME/.bash_profile) to enable easy access to the cmctl and SQL*Plus utilities, whenever you log in as the Oracle user.

    export ORACLE_HOME=/u01/app/oracle/product/cman2130
export LD_LIBRARY_PATH=/u01/app/oracle/product/cman2130/lib
export PATH=/u01/app/oracle/product/cman2130/bin:$PATH:$HOME
export TNS_ADMIN=/u01/app/oracle/product/cman2130/network/admin/

  10. Run the following command to ensure that both SQL*Plus and CMAN are running.

    [oracle@cman ~]$ sqlplus /nolog

SQL*Plus: Release 21.0.0.0.0 - Production on Wed Sep 11 05:37:26 2024
Version 21.3.0.0.0

Copyright (c) 1982, 2021, Oracle.  All rights reserved.

SQL> exit

[oracle@cman ~]$ cmctl

CMCTL for Linux: Version 21.0.0.0.0 - Production on 11-SEP-2024 05:37:30

Copyright (c) 1996, 2021, Oracle.  All rights reserved.

Welcome to CMCTL, type "help" for information.

CMCTL>

Task 3: Configure Oracle Connection Manager

In this task, we will configure CMAN. First, open the port the CMAN listener should use on the CMAN VM. In this example, we are using port 1999 to demo that it must not necessarily be 1521 and to distinguish it from the database listener port. As root:

$firewall-cmd --permanent --add-port=1999/tcp
$firewall-cmd –reload

  1. Normal CMAN configuration.

    As Oracle user, create the CMAN configuration file cman.ora under $TNS_ADMIN with the following content.

    Note: Change the host IP address to your CMAN VM IP!

    $cat $TNS_ADMIN/cman.ora

cman =
(configuration=
    (address=(protocol=tcp)(host=192.168.0.199)(port=1999))
    (parameter_list =
        (aso_authentication_filter=off)
        (connection_statistics=yes)
        (log_directory=/u01/app/oracle/product/cman2130/network/log)
        (log_level=support)
        (max_connections=256)
        (idle_timeout=0)
        (inbound_connect_timeout=0)
        (session_timeout=0)
        (outbound_connect_timeout=0)
        (max_gateway_processes=16)
        (min_gateway_processes=2)
        (remote_admin=on)
        (trace_directory=/u01/app/oracle/product/cman2130/network/trace)
        (trace_level=support)
        (trace_timestamp=off)
        (trace_filelen=1000)
        (trace_fileno=1)
        (max_cmctl_sessions=4)
        (event_group=init_and_term,memory_ops)
        (registration_invited_nodes = *)
        (service_affinity=off)
    )
        (rule_list=
        (rule=
            (src=*)(dst=*)(srv=*)(act=accept)
            (action_list=(aut=off)(moct=0)(mct=0)(mit=0)(conn_stats=on))
        )
    )
    )
)

VALID_NODE_CHECKING_REGISTRATION_CMAN = OFF

  2. Rule based CMAN configuration.

    If you go back and check the rule in the cman.ora file, you will find the following content.

    (src=*)(dst=*)(srv=*)(act=accept)

    So, we are allowing connections from any source, to any target, and to any service. Using the rule list, it is possible to define your own rules to allow or reject connections from specific clients, to specific targets, or to specific services. For example:

    $cat cman.ora
cman =
(configuration=
    (address=(protocol=tcp)(host=192.168.0.199)(port=1999))
    (parameter_list =
        (aso_authentication_filter=off)
        (connection_statistics=yes)
        (log_directory=/u01/app/oracle/product/cman2130/network/log)
        (log_level=support)
        (max_connections=256)
        (idle_timeout=0)
        (inbound_connect_timeout=0)
        (session_timeout=0)
        (outbound_connect_timeout=0)
        (max_gateway_processes=16)
        (min_gateway_processes=2)
        (remote_admin=on)
        (trace_directory=/u01/app/oracle/product/cman2130/network/trace)
        (trace_level=support)
        (trace_timestamp=off)
        (trace_filelen=1000)
        (trace_fileno=1)
        (max_cmctl_sessions=4)
        (event_group=init_and_term,memory_ops)
        (registration_invited_nodes = 192.168.0.48)
        (service_affinity=off)
    )
    (rule_list=
        (rule=
            (src=cman)(dst=127.0.0.1)(srv=cmon)(act=accept)
            (action_list=(aut=off)(moct=0)(mct=0)(mit=0)(conn_stats=on))
        )
    (rule=
            (src=192.168.0.74)(dst=192.168.0.48)(srv=GGC1_SJ.sub02090543360.vcnsj.oraclevcn.com)(act=accept)
            (action_list=(aut=off)(moct=0)(mct=0)(mit=0)(conn_stats=on))
    )
(rule=
            (src=192.168.0.75)(dst=192.168.0.48)(srv=GGC1_SJ.sub02090543360.vcnsj.oraclevcn.com)(act=Reject)
            (action_list=(aut=off)(moct=0)(mct=0)(mit=0)(conn_stats=on))
    )

    )
)

VALID_NODE_CHECKING_REGISTRATION_CMAN = OFF

    CMAN is a powerful tool. This is just a sample and simple configuration. Check the Oracle documentation for more configuration details, especially regarding security.

Task 4: Start Oracle Connection Manager Services

Connect to the source and target container database using the wallet and create a configuration using Oracle Data Guard Command-Line Interface (DGMGRL). This is the same as for a normal Oracle Data Guard configuration. Only difference is, that we have to do this for both Container Databases, as both are primary databases.

cmctl

CMCTL for Linux: Version 21.0.0.0.0 - Production on 04-SEP-2024 08:59:37

Copyright (c) 1996, 2021, Oracle.  All rights reserved.

Welcome to CMCTL, type "help" for information.

CMCTL> admin cman
Current instance cman is not yet started
Connections refer to (DESCRIPTION=(address=(protocol=tcp)(host=192.168.0.199)(port=1999))).
The command completed successfully.

CMCTL:cman> startup
Starting Oracle Connection Manager instance cman. Please wait...
CMAN for Linux: Version 21.0.0.0.0 - Production
Status of the Instance
----------------------
Instance name             cman
Version                   CMAN for Linux: Version 21.0.0.0.0 - Production
Start date                04-SEP-2024 08:59:43
Uptime                    0 days 0 hr. 0 min. 9 sec
Num of gateways started   2
Average Load level        0
Log Level                 SUPPORT
Trace Level               SUPPORT
Instance Config file      /u01/app/oracle/product/cman2130/network/admin/cman.ora
Instance Log directory    /u01/app/oracle/diag/netcman/cman/cman/alert
Instance Trace directory  /u01/app/oracle/diag/netcman/cman/cman/trace
The command completed successfully.

Run the following command to check status and services.

CMCTL:cman> show status
CMCTL:cman> show services

Task 5: Connection to Database through Oracle Connection Manager

Approach 1: Using Target Database Parameter

For CMAN to forward incoming connections to databases, CMAN must know of these databases. To achieve that we need to set REMOTE_LISTENER on the target database. Also set VALID_NODE_CHECKING_REGISTRATION_CMAN = OFF in the cman.ora file for successfull registration.

Target database:

alter system set REMOTE_LISTENER='10.0.0.8:1999' scope=both sid='*';
alter system register;

Add the following line in the cman.ora file.

VALID_NODE_CHECKING_REGISTRATION_CMAN = OFF

Run the following command to restart CMAN and check whether database is registered with the CMAN listener.

CMCTL:cman> show services

Validate Connection:

Connect to the database from the client VM using the CMAN IP and port. Create a new TNS alias in the tnsnames.ora file on the client VM.

GGC1_CM=
  (DESCRIPTION=
    (ADDRESS=
      (PROTOCOL=tcp)
      (HOST=192.168.0.199)(PORT=1999)) -- CMAN IP and Port
    (CONNECT_DATA=
      (SERVICE_NAME=GGC1_SJ.sub0209xxxx0543360.vcnsj.oraclevcn.com)))

Above service name should be visible in CMAN> show services, output.

$sqlplus system/MyPasswd__48@GGC1_CM

Check the CMAN trace file.

/home/oracle/base/diag/netcman/cman/cman/trace/cman.log
/u01/app/oracle/diag/netcman/cman/cman_test/trace/ log.xml

Approach 2: Using Hop

In case changing the REMOTE_LISTENER database parameter is not possible at target database, we need to use hop either in the cman.ora file or at client TNS file.

Option 1: Add Hop in the cman.ora File

$cat cman.ora
cman =
(configuration=
    (address=(protocol=tcp)(host=192.168.0.199)(port=1999))
    (parameter_list =
        (aso_authentication_filter=off)
……
        (service_affinity=off)
    )
    (next_hop=(description=(address=(protocol=tcp)(port=1521)(host=192.168.0.48))))
    (rule_list=
        (rule=
            (src=cman)(dst=127.0.0.1)(srv=cmon)(act=accept)
            (action_list=(aut=off)(moct=0)(mct=0)(mit=0)(conn_stats=on))
        )
    )
)

Option 2: Add Hop in Client’s TNS File

GGC1_SJ_CM =
(DESCRIPTION =
    (SOURCE_ROUTE = YES)
    (ADDRESS =
        (PROTOCOL = TCP)(HOST = 192.168.0.199)(PORT = 1999)
    )
    (ADDRESS =
        (PROTOCOL = TCP)(HOST = 192.168.0.48)(PORT = 1521)
    )
        (CONNECT_DATA = (SERVICE_NAME=GGC1_SJ.sub02090543360.vcnsj.oraclevcn.com)
    )
)

Run the following command to validate connection.

$sqlplus system/MyPasswd__48@GGC1_CM

Acknowledgments

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.