Skip to content

Commit 4211b90

Browse files
s1saurabhs1saurabh
authored
Cmanchanges (#2939)
* fix for single RAC + add node issue * latest 23.5 changes * base image fix * CMAN README changes * lint fix * lint fixes
1 parent f599fa9 commit 4211b90

File tree

5 files changed

+200
-99
lines changed

5 files changed

+200
-99
lines changed

‎OracleDatabase/OracleConnectionManager/README.md

+142-78
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,24 @@
1-
# Oracle Connection Manager Container Image
2-
Sample container build files to facilitate installation, configuration, and environment setup for DevOps users. For more information about Oracle Database please see the [Oracle Connection Manager online Documentation](http://docs.oracle.com/en/database/).
3-
4-
## How to build and run
5-
This project offers sample container images for:
1+
# Oracle Connection Manager in Linux Containers
2+
Oracle Connection Manager is a proxy server that forwards connection requests to databases or other proxy servers. It operates at the session level, and usually resides on a computer separate from the database server and client computers.
3+
4+
This guide provides information about example container build files that you can use to facilitate installation, configuration, and environment setup of Oracle Connection Manager for DevOps users. For more information about Oracle Database, please see the [Oracle Connection Manager online Documentation](http://docs.oracle.com/en/database/).
5+
6+
## Using this documentation
7+
- [Oracle Connection Manager in Linux Containers](#oracle-connection-manager-in-linux-containers)
8+
- [Using this documentation](#using-this-documentation)
9+
- [How to build and run Oracle Connection Manager in Containers](#how-to-build-and-run-oracle-connection-manager-in-containers)
10+
- [Getting Oracle Connection Manager Image](#getting-oracle-connection-manager-image)
11+
- [Create Oracle Connection Manager Image](#create-oracle-connection-manager-image)
12+
- [Create Network Bridge](#create-network-bridge)
13+
- [How to deploy Oracle Connection Manager Container](#how-to-deploy-oracle-connection-manager-container)
14+
- [Create Oracle Connection Manager Container](#create-oracle-connection-manager-container)
15+
- [Create Oracle Connection Manager Container using `cman.ora`](#create-oracle-connection-manager-container-using-cmanora)
16+
- [Environment Variables Explained](#environment-variables-explained)
17+
- [License](#license)
18+
- [Copyright](#copyright)
19+
20+
## How to build and run Oracle Connection Manager in Containers
21+
This project offers example container images for the following:
622
* Oracle Database 23ai Client (23.5) for Linux x86-64
723
* Oracle Database 21c Client (21.3) for Linux x86-64
824
* Oracle Database 19c Client (19.3) for Linux x86-64
@@ -11,117 +27,165 @@ This project offers sample container images for:
1127

1228
To assist in building the container images, you can use the [buildContainerImage.sh](containerfiles/buildContainerImage.sh) script. See section **Create Oracle Connection Manager Image** for instructions and usage.
1329

14-
**IMPORTANT:** Oracle Connection Manager binds to a single port on your host and proxies incoming connections to multiple running containers. It can also proxy connections for users to Oracle RAC Databases running on internal container networks.
30+
**IMPORTANT:** Oracle Connection Manager binds to a single port on your host, and proxies incoming connections to multiple running containers. It can also proxy connections for users to Oracle Databases running on internal container networks.
31+
32+
For complete Oracle Connection Manager setup, please go though following steps and execute them as per your environment:
33+
34+
## Getting Oracle Connection Manager Image
35+
You can also deploy Oracle Connection Manager on Podman using the pre-built images available on the Oracle Container Registry. Refer [this documentation](https://docs.oracle.com/en/operating-systems/oracle-linux/docker/docker-UsingDockerRegistries.html#docker-registry) for details on using Oracle Container Registry.
1536

16-
If you are on Podman Host, please ensure that you have the `podman-docker` package installed on your OL8 Podman host to run the command using the docker utility.
37+
Example of pulling an Oracle Connection Manager Image from the Oracle Container Registry:
1738
```bash
18-
dnf install podman-docker -y
39+
podman pull container-registry.oracle.com/database/cman:23.5.0.0
40+
podman tag container-registry.oracle.com/database/cman:23.5.0.0 localhost/oracle/client-cman:23.5.0
1941
```
2042

21-
For complete Oracle Connection Manager setup, please go though following steps and execute them as per your enviornment:
43+
If you are using pre-built Oracle Connection Manager from [the Oracle Container Registry](https://container-registry.oracle.com), then you can skip the section [Create Oracle Connection Manager Image](#create-oracle-connection-manager-image) to build the Oracle Connection Manager Image.
2244

2345
### Create Oracle Connection Manager Image
24-
**IMPORTANT:** You will have to provide the installation binaries of Oracle ADMIN Client Oracle Database 23ai Client (23.5) for Linux x86-64 and put them into the `containerfiles/<version>` folder. You only need to provide the binaries for the edition you are going to install.
25-
26-
The binaries can be downloaded from the [Oracle Technology Network](http://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.html).
27-
28-
You also have to make sure to have internet connectivity for yum. Note that you must not uncompress the binaries.
46+
**IMPORTANT:** You must provide the installation binaries of the Oracle ADMIN Client Oracle Database 23ai Client for Linux x86-64 (client_cman_home.zip) and put them into the `containerfiles/<version>` folder. You only need to provide the binaries for the edition that you are going to install. The binaries can be downloaded from the [Oracle Technology Network](http://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.html).
47+
You also have to ensure you have internet connectivity for yum. You must not uncompress the binaries.
2948

30-
The `buildContainerImage.sh` script is just a utility shell script that performs MD5 checks and is an easy way for beginners to get started. Expert users are welcome to directly call `docker build` with their prefered set of parameters.
31-
32-
Before you build the image make sure that you have provided the installation binaries and put them into the right folder.
33-
34-
#### Create Oracle Connection Manager Image in Podman Hosts
35-
Go into the **containerfiles** folder and run the **buildContainerImage.sh** script as root or with sudo privileges:
49+
The `buildContainerImage.sh` script is just a utility shell script that performs MD5 checks. It provides an easy way for beginners to get started. Expert users are welcome to directly call `podman build` with their prefered set of parameters.
50+
Before you build the image, ensure that you have provided the installation binaries and put them into the right folder. Go into the **containerfiles** folder and run the **buildContainerImage.sh** script as root or with sudo privileges:
3651

3752
```bash
38-
cd <git-cloned-path>/docker-images/OracleDatabase/RAC/OracleConnectionManager/containerfiles
3953
./buildContainerImage.sh -v (Software Version)
4054
./buildContainerImage.sh -v 23.5.0
4155
```
4256
For detailed usage of command, please execute following command:
4357
```bash
44-
cd <git-cloned-path>/docker-images/OracleDatabase/RAC/OracleConnectionManager/containerfiles
4558
./buildContainerImage.sh -h
4659
```
60+
Note:
61+
- Usage of `./buildContainerImage.sh`-
62+
```text
63+
-v: version to build
64+
-i: ignores the MD5 checksums
65+
-t: user defined image name and tag (e.g., image_name:tag). Default is set to oracle/client-cman:<VERSION>.
66+
-o: passes on container build option (e.g., --build-arg ARGUMENT=value).
67+
```
68+
- If you are behind a proxy wall, then you must set the `https_proxy` or `http_proxy` environment variable based on your environment before building the image.
69+
## Create Network Bridge
70+
**Note:** You can change subnet according to your environment.
4771

48-
#### Create Oracle Connection Manager Image in Docker Hosts
49-
Go into the **dockerfiles** folder and run the **buildContainerImage.sh** script as root or with sudo privileges:
72+
Before creating the container, create the podman network. If you are using the same network which the Oracle RAC containers are created [using the documentation](../OracleRealApplicationClusters/README.md), then you can use the same IPs mentioned in the [Create Oracle Connection Manager Container](#create-oracle-connection-manager-container) section.
5073

5174
```bash
52-
cd <git-cloned-path>/docker-images/OracleDatabase/RAC/OracleConnectionManager/dockerfiles
53-
./buildContainerImage.sh -v (Software Version)
54-
./buildContainerImage.sh -v 21.3.0
75+
podman network create --driver=bridge --subnet=10.0.20.0/24 rac_pub1_nw
5576
```
56-
For detailed usage of command, please execute following command:
77+
Example of creating macvlan networks-
5778
```bash
58-
cd <git-cloned-path>/docker-images/OracleDatabase/RAC/OracleConnectionManager/dockerfiles
59-
./buildContainerImage.sh -h
79+
podman network create -d macvlan --subnet=10.0.20.0/24 -o parent=ens5 rac_pub1_nw
6080
```
6181

62-
### Create Network Bridge
63-
Before creating container, create the bridge. If you are using same bridge with same network then you can use same IPs mentioned in **Create Containers** section.
64-
82+
Example of creating ipvlan networks-
6583
```bash
66-
docker network create --driver=bridge --subnet=172.16.1.0/24 rac_pub1_nw
84+
podman network create -d ipvlan --subnet=10.0.20.0/24 -o parent=ens5 rac_pub1_nw
6785
```
68-
69-
**Note:** You can change subnet according to your environment.
70-
### Create Containers
71-
72-
Execute following command as root user to create connection manager container on `Docker Host`-
73-
74-
```bash
75-
docker run -d --hostname racnodedc1-cman --dns-search=example.com \
76-
--network=rac_pub1_nw --ip=172.16.1.164 \
77-
-e DOMAIN=example.com -e PUBLIC_IP=172.16.1.164 \
78-
-e PUBLIC_HOSTNAME=racnodedc1-cman -e SCAN_NAME=racnodedc1-scan \
79-
-e SCAN_IP=172.16.1.230 --privileged=false \
80-
-p 1521:1521 --name racnodedc1-cman oracle/client-cman:21.3.0
86+
If you want to use Jumbo Frames MTU Network Configuration as similar as with Oracle RAC containers networks, then refer [Jumbo Frames MTU Network Configuration](../OracleRealApplicationClusters/README.md#jumbo-frames-mtu-network-configuration) section
87+
88+
## How to deploy Oracle Connection Manager Container
89+
The Oracle Connection manager container (CMAN) can be used with either an Oracle Real Application Clusters (Oracle RAC) database or with an Oracle Database Single instance database. However, you must ensure that the the SCAN Name or the Single host instance database Hostname is resolvable from the connection manager container.
90+
Oracle highly recommends that you use a DNS Server so that name resolution can happen successfully.
91+
92+
### Create Oracle Connection Manager Container
93+
Before creating Oracle Connection Manager, we advise to review the **[Environment Variables Explained](#environment-variables-explained) section**. If you are planning to `cman.ora` file skip to [section](#create-oracle-connection-manager-container-using-cmanora)
94+
To create the connection manager container, run the following command as the root user:
95+
96+
```bash
97+
podman run -d \
98+
--hostname racnodepc1-cman \
99+
--dns-search=example.info \
100+
--dns 10.0.20.25 \
101+
--network=rac_pub1_nw \
102+
--ip=10.0.20.15 \
103+
--cap-add=AUDIT_WRITE \
104+
--cap-add=NET_RAW \
105+
-e DOMAIN=example.info \
106+
-e PUBLIC_IP=10.0.20.15 \
107+
-e DNS_SERVER=10.0.20.25 \
108+
-e PUBLIC_HOSTNAME=racnodepc1-cman \
109+
--privileged=false \
110+
-p 1521:1521 \
111+
--name racnodepc1-cman \
112+
oracle/client-cman:23.5.0
81113
```
82114

83-
Execute following command as root user to create connection manager container on `Podman Host`-
84-
115+
### Create Oracle Connection Manager Container using `cman.ora`
116+
If you want to provide your own pre-created `cman.ora` file, you can provide with `-e USER_CMAN_FILE=<cman-file-name>` and also add attach <cman-file-name> as podman volume to podman run command. Refer sample of [cman.ora](./containerfiles/cman.ora) and execute below command to create Oracle Connection Manager Container -
85117
```bash
86-
podman run -d \
87-
--hostname racnodepc1-cman \
88-
--dns-search=example.com \
89-
--dns 172.16.1.25 \
90-
--network=rac_pub1_nw \
91-
--ip=172.16.1.164 \
92-
--cap-add=AUDIT_WRITE \
93-
--cap-add=NET_RAW \
94-
-e DOMAIN=example.com \
95-
-e PUBLIC_IP=172.16.1.164 \
96-
-e DNS_SERVER=172.16.1.25 \
97-
-e PUBLIC_HOSTNAME=racnodepc1-cman \
98-
-e DB_HOSTDETAILS="HOST=racnodepc1-scan:RULE_ACT=accept,HOST=racnodep1:IP=172.16.1.170" \
99-
--privileged=false \
100-
-p 1521:1521 \
101-
--name racnodepc1-cman \
102-
oracle/client-cman:23.5.0
118+
podman run -d \
119+
--hostname racnodepc1-cman \
120+
--dns-search=example.info \
121+
--dns 10.0.20.25 \
122+
--network=rac_pub1_nw \
123+
--ip=10.0.20.15 \
124+
--cap-add=AUDIT_WRITE \
125+
--cap-add=NET_RAW \
126+
-v /opt/containers/cman.ora:/var/tmp/cman.ora \
127+
-e USER_CMAN_FILE=/var/tmp/cman.ora \
128+
-e DOMAIN=example.info \
129+
-e PUBLIC_IP=10.0.20.15 \
130+
-e DNS_SERVER=10.0.20.25 \
131+
-e PUBLIC_HOSTNAME=racnodepc1-cman \
132+
--privileged=false \
133+
-p 1521:1521 \
134+
--name racnodepc1-cman \
135+
oracle/client-cman:23.5.0
103136
```
104137

105-
In the above container, you can see that we are passing env variables using "-e". You need to change `PUBLIC_IP`, `PUBLIC_HOSTNAME`, `SCAN_NAME`, `SCAN_IP`, `DB_HOSTDETAILS` according to your environment. Also, container will be binding to port 1521 on your docker host.
106-
107-
**Note:** SCAN_NAME and SCAN_IP will be your Oracle RAC SCAN details. These will be registered in connection manager but will be accessible when you create Oracle RAC container.
108-
109-
To check the Cman container/services creation logs , please tail docker logs. It will take 2 minutes to create the Cman container service.
110-
111-
Check logs in `Docker Host` -
112-
```bash
113-
docker logs racnodedc1-cman
114-
```
138+
To check the Cman container/services creation logs, you can run a tail command on the podman logs. It should take two minutes to create the Cman container service.
115139

116-
Check logs in `Podman Host` -
117140
```bash
118141
podman logs racnodepc1-cman
119142
```
120143

121-
You should see following when cman container setup is done:
144+
You should see the following when the cman container setup is done:
122145

123146
```bash
124147
###################################
125148
CONNECTION MANAGER IS READY TO USE!
126149
###################################
127150
```
151+
152+
### Adding rules to the Oracle Connection Manager
153+
154+
You can add rules to the OracleConnectionManager using the following command line syntax.
155+
Run this command inside the OracleConnectionManager container.
156+
```bash
157+
podman exec -i -t racnodepc1-cman /bin/bash
158+
159+
/opt/scripts/startup/configCMAN.sh -addrule -e DB_HOSTDETAILS=<HOST-DETAILS>
160+
For example :
161+
/opt/scripts/startup/configCMAN.sh -addrule -e DB_HOSTDETAILS=HOST=racnodep9:IP=10.0.20.178:RULE_SRC=racnodepc2-cman
162+
```
163+
### Deleting rules from the Oracle Connection Manager
164+
165+
You can delete the rules from the OracleConnectionManager using the following command line syntax.
166+
Run this command inside the OracleConnectionManager container.
167+
```bash
168+
podman exec -i -t racnodepc1-cman /bin/bash
169+
170+
/opt/scripts/startup/configCMAN.sh -delrule -e RULEDETAILS=<RULE-DETAILS>
171+
For example :
172+
/opt/scripts/startup/configCMAN.sh -delrule -e RULEDETAILS=RULE_DST=racnodep8
173+
```
174+
## Environment Variables Explained
175+
| Environment Variable | Description |
176+
|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
177+
| DOMAIN | The domain name associated with the container environment. |
178+
| PUBLIC_IP | The public IP address assigned to the Oracle Connection Manager container. |
179+
| PUBLIC_HOSTNAME | The public hostname assigned to the Oracle Connection Manager container. |
180+
| DNS_SERVER | The default is set to `10.0.20.25`, which is the DNS container resolving the Connection Manager and Oracle Database containers. Replace this with your DNS server IP if needed. |
181+
| USER_CMAN_FILE | (Optional) If you want to provide your own pre-created `cman.ora` file, set this environment variable and attach the file as a Podman volume in the `podman run` command. |
182+
183+
## License
184+
185+
To download and run the Oracle ADMIN Client Oracle Database 23ai Client, regardless of whether inside or outside a container, you must download the binaries from the Oracle website and accept the license indicated on that page.
186+
187+
All scripts and files hosted in this repository which are required to build the container images are, unless otherwise noted, released under UPL 1.0 license.
188+
189+
## Copyright
190+
191+
Copyright (c) 2014-2025 Oracle and/or its affiliates.

‎OracleDatabase/OracleConnectionManager/containerfiles/23.5.0/configCMAN.sh

+13-4
Original file line numberDiff line numberDiff line change
@@ -49,15 +49,17 @@ export TRULESTR=" (rule=
4949
(action_list=(aut=off)(moct=0)(mct=0)(mit=0)(conn_stats=on))
5050
)"
5151

52+
export LOCAL_CMCTL_CONN_STR=" (rule=(src=###CMAN_HOSTNAME###.###DOMAIN###)(dst=127.0.0.1)(srv=cmon)(act=accept))"
53+
5254
all_check()
5355
{
5456
if [ -z ${DB_HOSTDETAILS} ]; then
55-
error_exit "DB_HOSTDETAILS not set. Exiting"
57+
print_message "DB_HOSTDETAILS not set. Setting to default"
5658
else
5759
print_message "DB_HOSTDETAILS name is ${DB_HOSTDETAILS}"
60+
get_dbhost_details
5861
fi
5962

60-
get_dbhost_details
6163
check_cman_env_vars
6264
}
6365

@@ -305,7 +307,11 @@ if [ -f $DB_HOME/network/admin/$CMANORA ]; then
305307
cp $DB_HOME/network/admin/$CMANORA $logdir/$CMANORA
306308
else
307309
cat $SCRIPT_DIR/$CMANORA >> $logdir/$CMANORA
308-
sh -c "echo $'/(rule=\n\Emk%d\'k\E:x\n' | vi $logdir/$CMANORA" 2>/dev/null
310+
if [ ! -z ${DB_HOSTDETAILS} ]; then
311+
sh -c "echo $'/(rule=\n\Emk%d\'k\E:x\n' | vi $logdir/$CMANORA" 2>/dev/null
312+
# Add the local CMCTL connection
313+
sh -c "echo $'/(rule_list=\n\Eo${LOCAL_CMCTL_CONN_STR}\E:x\n' | vi $logdir/$CMANORA" 2>/dev/null
314+
fi
309315
fi
310316

311317
sed -i -e "s|###CMAN_HOSTNAME###|$PUBLIC_HOSTNAME|g" $logdir/$CMANORA
@@ -391,6 +397,7 @@ eval $cmd
391397
start_cman ()
392398
{
393399
local cmd
400+
export ORACLE_HOME=$DB_HOME
394401
cmd="$DB_HOME/bin/cmctl startup -c CMAN_$PUBLIC_HOSTNAME.$DOMAIN"
395402
eval $cmd
396403
}
@@ -399,13 +406,15 @@ stop_cman ()
399406
{
400407
local cmd
401408
cmaninst=$1
409+
export ORACLE_HOME=$DB_HOME
402410
cmd="$DB_HOME/bin/cmctl shutdown -c $cmaninst"
403411
eval $cmd
404412
}
405413

406414
status_cman ()
407415
{
408416
local cmd
417+
export ORACLE_HOME=$DB_HOME
409418
cmd="$DB_HOME/bin/cmctl show service -c CMAN_$PUBLIC_HOSTNAME.$DOMAIN"
410419
eval $cmd
411420

@@ -502,4 +511,4 @@ print_message "Checking CMAN Status"
502511
status_cman
503512
print_message "################################################"
504513
print_message " CONNECTION MANAGER IS READY TO USE! "
505-
print_message "################################################"
514+
print_message "################################################"

‎OracleDatabase/OracleConnectionManager/containerfiles/23.5.0/runOracle.sh

+4-4
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@
1010
#
1111

1212

13-
#env > /tmp/envfile
13+
env > /tmp/envfile
1414

15-
#chmod 755 /tmp/envfile
16-
#source /tmp/envfile
15+
chmod 755 /tmp/envfile
16+
source /tmp/envfile
1717
source $SCRIPT_DIR/functions.sh
1818

1919
########### SIGINT handler ############
@@ -75,4 +75,4 @@ fi
7575

7676
tail -f /tmp/orod.log &
7777
childPID=$!
78-
wait $childPID
78+
wait $childPID

‎OracleDatabase/RAC/OracleRealApplicationClusters/README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -143,11 +143,11 @@ podman tag localhost/oracle/database-rac:21.3.0-slim localhost/oracle/database-r
143143
### Building Oracle RAC Database Container Base Image
144144
In this document, an `Oracle RAC Database Container Base Image` refers to a container image that does not include installation of Oracle Grid Infrastructure and Oracle Database Software Binaries during the Oracle RAC Database Container Image creation. This image is extended to build patched image or extensions. To build an Oracle RAC Database Container Base Image run the following command:
145145
```bash
146-
./buildContainerImage.sh -v <Software Version> -i -b
146+
./buildContainerImage.sh -v <Software Version> -b
147147
```
148148
Example: To build Oracle RAC Database Container Base Image for version 21.3.0, use the below command:
149149
```bash
150-
./buildContainerImage.sh -v 21.3.0 -i -b
150+
./buildContainerImage.sh -v 21.3.0 -b
151151
```
152152
To build an Oracle RAC Database Container Base Image, you need to use `-b`.
153153

0 commit comments

Comments
 (0)