Merge branch 'oracle:main' into main

OracleDatabase/SingleInstance/FAQ.md

@@ -4,11 +4,13 @@
 
 Yes, this feature is supported version 19.3 onwards.
 
-Versions prior to 19.3 available on the [Oracle Container Registry](https://container-registry.oracle.com/), like the Oracle Database 12c Standard Edition 2 and Enterprise Edition images, are not based on any of the Dockerfiles contained in this repository. For such versions, if you require the runtime functionality documented in this repository, you will need to build an image from the appropriate Dockerfile.
+Versions prior to 19.3 available on the [Oracle Container Registry](https://container-registry.oracle.com/), like the Oracle Database 12c Standard Edition 2 and Enterprise Edition images, are not based on any of the Dockerfiles contained in this repository.
+For such versions, if you require the runtime functionality documented in this repository, you will need to build an image from the appropriate Dockerfile.
 
 ## How do I change the timezone of my container
 
-As of Docker 17.06-ce, Docker does not yet provide a way to pass down the `TZ` Unix environment variable from the host to the container. Because of that all containers run in the UTC timezone. If you would like to have your database run in a different timezone you can pass on the `TZ` environment variable within the `docker run` command via the `-e` option. An example would be: `docker run ... -e TZ="Europe/Vienna" oracle/database:12.2.0.1-ee`. Another option would be to specify two read-only volume mounts: `docker run ... -v /etc/timezone:/etc/timezone:ro -v /etc/localtime:/etc/localtime:ro oracle/database:12.2.0.1-ee`. This will synchronize the timezone of the the container with that of the Docker host.
+As of Docker 17.06-ce, Docker does not yet provide a way to pass down the `TZ` Unix environment variable from the host to the container. Because of that all containers run in the UTC timezone. If you would like to have your database run in a different timezone you can pass on the `TZ` environment variable within the `docker run` command via the `-e` option.
+An example would be: `docker run ... -e TZ="Europe/Vienna" oracle/database:12.2.0.1-ee`. Another option would be to specify two read-only volume mounts: `docker run ... -v /etc/timezone:/etc/timezone:ro -v /etc/localtime:/etc/localtime:ro oracle/database:12.2.0.1-ee`. This will synchronize the timezone of the the container with that of the Docker host.
 
 ## Can I run Oracle Database containers on Apple M1 (Arm) devices?
 
@@ -25,7 +27,8 @@ which are not available for that architecture.
 
 This error is thrown when there is no sufficient space available within the container to unzip the install binaries and run the installation of the Oracle database. The container runs the `df` Unix command, meaning that even if you think there should be enough space, there certainly isn't within the container.
 
-Please make sure that you have enough space available. If you use a storage diver such as `overlay2`, make sure that the output of `docker info` shows a `Base Device Size:` that is bigger than the required space. If not, please change the Base Device Size via the `--storage-opt dm.basesize=` option for the Docker daemon, see [this thread on Docker forums](https://forums.docker.com/t/increase-container-volume-disk-size/1652/4) for more information on that. **Note: You will have to delete all images afterwards to make sure that the new setting is picked up!**
+Please make sure that you have enough space available. If you use a storage diver such as `overlay2`, make sure that the output of `docker info` shows a `Base Device Size:` that is bigger than the required space.
+If not, please change the Base Device Size via the `--storage-opt dm.basesize=` option for the Docker daemon, see [this thread on Docker forums](https://forums.docker.com/t/increase-container-volume-disk-size/1652/4) for more information on that. **Note: You will have to delete all images afterwards to make sure that the new setting is picked up!**
 
 ## Error: The container doesn't have enough memory allocated. A database XE container needs at least 1 GB of shared memory (/dev/shm)
 
@@ -37,7 +40,8 @@ CRC errors by the Unix unzip command during image build can be caused by a lack
 
 ## "Cannot create directory" error when using volumes
 
-This is a Unix file system permission issue. Docker by default will map the `uid` inside the container to the outside world. The `uid` for the `oracle` user inside the container is `54321` and therefore all files are created with this `uid`. If you happen to have your volume pointed at a location outside there container where this `uid` doesn't have any permissions for, the container can't write to it and therefore the database files creation fails. There are several remedies for this situation:
+This is a Unix file system permission issue. Docker by default will map the `uid` inside the container to the outside world. The `uid` for the `oracle` user inside the container is `54321` and therefore all files are created with this `uid`.
+If you happen to have your volume pointed at a location outside there container where this `uid` doesn't have any permissions for, the container can't write to it and therefore the database files creation fails. There are several remedies for this situation:
 
 * Use named volumes
 * Change the ownership of your folder to `54321`
@@ -110,3 +114,83 @@ Refer to the [module documentation](https://python-oracledb.readthedocs.io/en/la
 ## ORA-01157: cannot identify/lock data file
 
 This error occurs when the database cannot find a data file (used for tablespaces) that was previously present. This is most likely because the data file has been located outside the volume in a previous container and was hence not persisted. Ensure that when you add tablespaces and/or data files that they are located within the volume location, i.e. $ORACLE_BASE/oradata/$ORACLE_SID, (e.g. `/opt/oracle/oradata/XE`).
+
+## Running Oracle Database 23c Free on Apple Silicon (ARM) chip
+
+### Setup Database
+Below are the steps to run Oracle Database 23c Free on Apple Silicon (ARM) machine
+
+1. Install [Podman Lima](https://github.com/lima-vm/lima) on Mac
+
+    ```brew install podman lima```
+
+2. Start a lima instance (vm)
+
+    ```limactl start --name podman-amd64  --set='.arch = "x86_64" | .memory = "10GiB"'  template://podman```
+
+    Wait for the VM to boot up. Above command may error out if the VM takes a while to boot up. Ultimately it comes up fine.
+
+3. Set the address or hostname of the lima container runtime
+
+    ```export CONTAINER_HOST=unix://Users/$USER/.lima/podman-amd64/sock/podman.sock```
+
+4. Pull the oracle database 23c free image
+
+    ```podman pull container-registry.oracle.com/database/free:latest```
+
+5. Run the container with the pulled image
+
+    ```podman run -e ORACLE_PWD=<password> -d -P container-registry.oracle.com/database/free:latest```
+
+6. Check whether the database came up healthy.
+
+```shell
+    $ podman ps -a
+        CONTAINER ID  IMAGE                                               COMMAND               CREATED        STATUS                  PORTS                    NAMES 
+        825dcbd3e822  container-registry.oracle.com/database/free:latest  /bin/sh -c exec $...  4 minutes ago  Up 4 minutes (healthy)  0.0.0.0:42439->1521/tcp  hopeful_yalow
+```
+
+### Connect
+1. Install sqlplus
+
+   ```cd $HOME/Downloads```
+
+   ```curl -O https://download.oracle.com/otn_software/mac/instantclient/198000/instantclient-basic-macos.x64-19.8.0.0.0dbru.dmg```
+
+   ```curl -O https://download.oracle.com/otn_software/mac/instantclient/198000/instantclient-sqlplus-macos.x64-19.8.0.0.0dbru.dmg```
+
+   ```hdiutil mount instantclient-basic-macos.x64-19.8.0.0.0dbru.dmg```
+
+   ```hdiutil mount instantclient-sqlplus-macos.x64-19.8.0.0.0dbru.dmg```
+
+   ```/Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru/install_ic.sh```
+
+   ```hdiutil unmount /Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru```
+
+   ```hdiutil unmount /Volumes/instantclient-sqlplus-macos.x64-19.8.0.0.0dbru```
+
+2. Test the connection:
+
+   ```$HOME/Downloads/instantclient_19_8/sqlplus sys@localhost:<PORT>/FREE as sysdba```
+
+   ```$HOME/Downloads/instantclient_19_8/sqlplus system@localhost:<PORT>/FREE```
+
+   ```$HOME/Downloads/instantclient_19_8/sqlplus pdbadmin@localhost:<PORT>/FREEPDB1```
+
+    PORT is 42439 in above e.g. (Step 6 output of "podman ps -a").
+
+Alternative (Using SQLcl):
+
+1. Install [Java](https://download.oracle.com/java/20/latest/jdk-20_macos-aarch64_bin.dmg)
+
+2. Install [SQLcl](https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip)
+
+3. Test the connection:
+
+   ```sqlcl/bin/sql sys@localhost:<PORT>/FREE as sysdba```
+
+   ```sqlcl/bin/sql system@localhost:<PORT>/FREE```
+
+   ```sqlcl/bin/sql pdbadmin@localhost:<PORT>/FREEPDB1```
+
+   PORT is 42439 in above e.g. (Step 6 output of "podman ps -a").

OracleDatabase/SingleInstance/README.md

@@ -218,17 +218,17 @@ To enable TCPS connections while creating the database, use the `-e ENABLE_TCPS=
 To enable TCPS connections after the database is created, please use the following sample command:
 
     # Creates Listener for TCPS at container port 2484
-    docker exec -it <container name> /opt/oracle/configTcps.sh
+    docker exec <container name> /opt/oracle/configTcps.sh
 
 Similarly, to disable TCPS connections for the database, please use the following command:
 
     # Disable TCPS in the database
-    docker exec -it <container name> /opt/oracle/configTcps.sh disable
+    docker exec <container name> /opt/oracle/configTcps.sh disable
 
 To configure  wallet password, please use the following command:
 
     # Setup TCPS for port 16002 and pass wallet password as argument
-    docker exec -it <container name> /opt/oracle/configTcps.sh 16002 localhost <WALLET_PWD>
+    docker exec <container name> /opt/oracle/configTcps.sh 16002 localhost <WALLET_PWD>
 
 **NOTE**:
 
@@ -237,10 +237,20 @@ To configure  wallet password, please use the following command:
 * When TCPS is enabled, a self-signed certificate will be created. For users' convenience, a client-side wallet is prepared and stored at the location `/opt/oracle/oradata/clientWallet/$ORACLE_SID`. You can use this client wallet along with SQL\*Plus to connect to the database. The sample command to download the client wallet is as follows:
 
         # ORACLE_SID default value is ORCLCDB
-        docker cp <container name>:/opt/oracle/oradata/clientWallet/<ORACLE_SID> <destination directory>
+        docker cp <container name>:/opt/oracle/oradata/clientWallet/<ORACLE_SID> <destination wallet directory>
 
-* The client wallet directory above will include wallet files, along with sample `sqlnet.ora` and `tnsnames.ora` files. You should edit the `HOST` and `PORT` fields accordingly in the `tnsnames.ora` before connecting using TCPS.
-* After `tnsnames.ora` is modified, go inside the downloaded client wallet directory and set TNS_ADMIN for SQL\*Plus by using the `export TNS_ADMIN=$(pwd)` command. Then users can connect via TCPS with, for example, the following commands:
+* The client wallet directory above will include wallet files, along with sample `sqlnet.ora` and `tnsnames.ora` files.
+* To connect to the database via TCPS you can use SQL*Plus as shown:
+
+        sqlplus sys@tcps://<host>:<port>/<service_name>?wallet_location=<destination wallet directory> as sysdba
+        # Default value for host is localhost unless specified while running configTcps.sh
+        # port is mapped port of host where container is running
+        # destination wallet directory is where client wallet is copied to.
+
+    OR
+
+* Edit the `HOST` and `PORT` fields in the tnsnames.ora accordingly.
+* After tnsnames.ora is modified, go inside the downloaded client wallet directory and set TNS_ADMIN for SQL*Plus by using the `export TNS_ADMIN=$(pwd)` command. Then users can connect via TCPS with, for example, the following commands:
 
         # Connecting Enterprise Edition
         sqlplus sys@ORCLCDB as sysdba
@@ -249,7 +259,7 @@ To configure  wallet password, please use the following command:
 
 * The certificate used with TCPS has validity for 1 year. After the certificate is expired, you can renew it using the following command:
 
-        docker exec -it <container name> /opt/oracle/configTcps.sh
+        docker exec <container name> /opt/oracle/configTcps.sh
 
     After certificate renewal, the client wallet should be updated by downloading it again.
 * Supports Oracle Database XE version 21.3.0 onwards.

OracleDatabase/SingleInstance/dockerfiles/19.3.0/configTcps.sh

@@ -84,6 +84,9 @@ function configure_netservices() {
    echo "WALLET_LOCATION = (SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = $WALLET_LOC)))
 SSL_CLIENT_AUTHENTICATION = FALSE" | tee -a "$ORACLE_BASE"/oradata/dbconfig/"$ORACLE_SID"/{sqlnet.ora,listener.ora} > /dev/null
 
+   # Disable OOB in sqlnet.ora of DB wallet
+   echo "DISABLE_OOB=ON" >> "$ORACLE_BASE"/oradata/dbconfig/"$ORACLE_SID"/sqlnet.ora
+
    # Add listener for TCPS
    sed -i "/TCP/a\
 \ \ \ \ (ADDRESS = (PROTOCOL = TCPS)(HOST = 0.0.0.0)(PORT = ${TCPS_PORT}))
@@ -95,6 +98,9 @@ SSL_CLIENT_AUTHENTICATION = FALSE" | tee -a "$ORACLE_BASE"/oradata/dbconfig/"$OR
 function reconfigure_listener() {
   lsnrctl stop
   lsnrctl start
+
+  # To quickly register a service
+  echo 'alter system register;' | sqlplus -s / as sysdba
 }
 
 # Function for disabling the tcps and restore the previous Oracle Net configuration
@@ -116,11 +122,14 @@ function disable_tcps() {
 ################## MAIN ###################
 ###########################################
 
+export ORACLE_SID
 ORACLE_SID="$(grep "$ORACLE_HOME" /etc/oratab | cut -d: -f1)"
+
 # Export ORACLE_PDB value
 export ORACLE_PDB=${ORACLE_PDB:-ORCLPDB1}
 ORACLE_PDB=${ORACLE_PDB^^}
 
+
 # Oracle wallet location which stores the certificate
 WALLET_LOC="${ORACLE_BASE}/oradata/dbconfig/${ORACLE_SID}/.tls-wallet"
 
@@ -171,15 +180,15 @@ EOF
 echo -e "\nOracle Wallet location: ${WALLET_LOC}\n"
 
 # Create a self-signed certificate using orapki utility; VALIDITY: 365 days
-orapki wallet add -wallet "${WALLET_LOC}" -dn "CN=localhost" -keysize 2048 -self_signed -validity 365 <<EOF
+orapki wallet add -wallet "${WALLET_LOC}" -dn "CN=${HOSTNAME:-localhost}" -keysize 2048 -self_signed -validity 365 <<EOF
 ${WALLET_PWD}
 EOF
 
 # Reconfigure listener to enable TCPS (Reload wouldn't work here)
 reconfigure_listener
 
 # Export the cert to be updated in the client wallet
-orapki wallet export -wallet "${WALLET_LOC}" -dn "CN=localhost" -cert /tmp/"$(hostname)"-certificate.crt <<EOF
+orapki wallet export -wallet "${WALLET_LOC}" -dn "CN=${HOSTNAME:-localhost}" -cert /tmp/"$(hostname)"-certificate.crt <<EOF
 ${WALLET_PWD}
 EOF
 

OracleDatabase/SingleInstance/dockerfiles/21.3.0/configTcps.sh

@@ -84,6 +84,9 @@ function configure_netservices() {
    echo "WALLET_LOCATION = (SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = $WALLET_LOC)))
 SSL_CLIENT_AUTHENTICATION = FALSE" | tee -a "$ORACLE_BASE"/oradata/dbconfig/"$ORACLE_SID"/{sqlnet.ora,listener.ora} > /dev/null
 
+   # Disable OOB in sqlnet.ora of DB wallet
+   echo "DISABLE_OOB=ON" >> "$ORACLE_BASE"/oradata/dbconfig/"$ORACLE_SID"/sqlnet.ora
+
    # Add listener for TCPS
    sed -i "/TCP/a\
 \ \ \ \ (ADDRESS = (PROTOCOL = TCPS)(HOST = 0.0.0.0)(PORT = ${TCPS_PORT}))
@@ -95,6 +98,9 @@ SSL_CLIENT_AUTHENTICATION = FALSE" | tee -a "$ORACLE_BASE"/oradata/dbconfig/"$OR
 function reconfigure_listener() {
   lsnrctl stop
   lsnrctl start
+
+# To quickly register a service
+  echo 'alter system register;' | sqlplus -s / as sysdba
 }
 
 # Function for disabling the tcps and restore the previous Oracle Net configuration
@@ -115,7 +121,9 @@ function disable_tcps() {
 ################## MAIN ###################
 ###########################################
 
+export ORACLE_SID
 ORACLE_SID="$(grep "$ORACLE_HOME" /etc/oratab | cut -d: -f1)"
+
 # Export ORACLE_PDB value
 if [ "$ORACLE_SID" == "XE" ]; then
   export ORACLE_PDB="XEPDB1"
@@ -124,6 +132,8 @@ else
 fi
 ORACLE_PDB=${ORACLE_PDB^^}
 
+
+
 # Oracle wallet location which stores the certificate
 WALLET_LOC="${ORACLE_BASE}/oradata/dbconfig/${ORACLE_SID}/.tls-wallet"
 
@@ -174,15 +184,15 @@ EOF
 echo -e "\nOracle Wallet location: ${WALLET_LOC}\n"
 
 # Create a self-signed certificate using orapki utility; VALIDITY: 365 days
-orapki wallet add -wallet "${WALLET_LOC}" -dn "CN=localhost" -keysize 2048 -self_signed -validity 365 <<EOF
+orapki wallet add -wallet "${WALLET_LOC}" -dn "CN=${HOSTNAME:-localhost}" -keysize 2048 -self_signed -validity 365 <<EOF
 ${WALLET_PWD}
 EOF
 
 # Reconfigure listener to enable TCPS (Reload wouldn't work here)
 reconfigure_listener
 
 # Export the cert to be updated in the client wallet
-orapki wallet export -wallet "${WALLET_LOC}" -dn "CN=localhost" -cert /tmp/"$(hostname)"-certificate.crt <<EOF
+orapki wallet export -wallet "${WALLET_LOC}" -dn "CN=${HOSTNAME:-localhost}" -cert /tmp/"$(hostname)"-certificate.crt <<EOF
 ${WALLET_PWD}
 EOF
 

OracleDatabase/SingleInstance/dockerfiles/23.2.0/configTcps.sh

@@ -84,6 +84,9 @@ function configure_netservices() {
    echo "WALLET_LOCATION = (SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = $WALLET_LOC)))
 SSL_CLIENT_AUTHENTICATION = FALSE" | tee -a "$ORACLE_BASE"/oradata/dbconfig/"$ORACLE_SID"/{sqlnet.ora,listener.ora} > /dev/null
 
+   # Disable OOB in sqlnet.ora of DB wallet
+   echo "DISABLE_OOB=ON" >> "$ORACLE_BASE"/oradata/dbconfig/"$ORACLE_SID"/sqlnet.ora
+
    # Add listener for TCPS
    sed -i "/TCP/a\
 \ \ \ \ (ADDRESS = (PROTOCOL = TCPS)(HOST = 0.0.0.0)(PORT = ${TCPS_PORT}))
@@ -95,6 +98,9 @@ SSL_CLIENT_AUTHENTICATION = FALSE" | tee -a "$ORACLE_BASE"/oradata/dbconfig/"$OR
 function reconfigure_listener() {
   lsnrctl stop
   lsnrctl start
+
+  # To quickly register a service
+  echo 'alter system register;' | sqlplus -s / as sysdba
 }
 
 # Function for disabling the tcps and restore the previous Oracle Net configuration
@@ -115,7 +121,9 @@ function disable_tcps() {
 ################## MAIN ###################
 ###########################################
 
+export ORACLE_SID
 ORACLE_SID="$(grep "$ORACLE_HOME" /etc/oratab | cut -d: -f1)"
+
 # Export ORACLE_PDB value
 if [ "$ORACLE_SID" == "FREE" ]; then
   export ORACLE_PDB="FREEPDB1"
@@ -166,15 +174,15 @@ EOF
 echo -e "\nOracle Wallet location: ${WALLET_LOC}\n"
 
 # Create a self-signed certificate using orapki utility; VALIDITY: 365 days
-orapki wallet add -wallet "${WALLET_LOC}" -dn "CN=localhost" -keysize 2048 -self_signed -validity 365 <<EOF
+orapki wallet add -wallet "${WALLET_LOC}" -dn "CN=${HOSTNAME:-localhost}" -keysize 2048 -self_signed -validity 365 <<EOF
 ${WALLET_PWD}
 EOF
 
 # Reconfigure listener to enable TCPS (Reload wouldn't work here)
 reconfigure_listener
 
 # Export the cert to be updated in the client wallet
-orapki wallet export -wallet "${WALLET_LOC}" -dn "CN=localhost" -cert /tmp/"$(hostname)"-certificate.crt <<EOF
+orapki wallet export -wallet "${WALLET_LOC}" -dn "CN=${HOSTNAME:-localhost}" -cert /tmp/"$(hostname)"-certificate.crt <<EOF
 ${WALLET_PWD}
 EOF
 

OracleManagementAgent/dockerfiles/latest/container-scripts/watchdog.sh

@@ -158,13 +158,13 @@ function deploy_agent_initial_plugins()
     local java_exec
     java_exec=$(/bin/sh $MGMTAGENT_HOME/agent_inst/bin/javaPath.sh)
     log "Java executable path: [$java_exec]"
-    local java_cp="$MGMTAGENT_HOME/$current_version/jlib/agent-configure-*.jar"
+    local java_cp="$MGMTAGENT_HOME/$current_version/jlib"
     local java_class="oracle.polaris.configure.DeployPlugins"
     local jvm_args="-Djava.security.egd=file:///dev/./urandom"
 
     # plugin(s) must be deployed from agent_inst/bin
     pushd "$MGMTAGENT_HOME/agent_inst/bin"
-    $java_exec "$jvm_args" -cp "$java_cp" "$java_class" &
+    $java_exec "$jvm_args" -cp "$java_cp/"agent-configure-*.jar "$java_class" &
     log "$APPNAME plugin deployment outcome [status: $?]"
     popd
     return 0