Databases

Oracle DB 23ai Client User Guide

| Product: Oracle DB 23ai Client

Overview

This guide covers the deployment and configuration of Oracle Database Client 23ai on Linux using cloudimg AMIs from the AWS Marketplace. Oracle Database Client 23ai is the latest generation Oracle Client, providing the tools and libraries needed to connect to and manage remote Oracle Database instances. Oracle 23ai brings AI vector search and other advanced capabilities. This AMI includes SQL*Plus, Oracle Net, and other client utilities without requiring a full database installation.

What's included in this AMI:

  • Oracle Database Client 23ai installed at /u01
  • Dedicated oracle OS user with environment script (setEnv.sh)
  • SQL*Plus for connecting to remote Oracle databases
  • OS package update script for keeping the system current
  • AWS CLI v2 for AWS service integration
  • Systems Manager Agent (SSM) for remote management
  • CloudWatch Agent for monitoring
  • Latest security patches applied at build time
  • 24/7 cloudimg support with guaranteed 24 hour response SLA

Prerequisites

Before launching this AMI, ensure you have:

  1. An active AWS account
  2. An active subscription to the Oracle DB 23ai Client listing on AWS Marketplace
  3. An EC2 key pair for SSH access
  4. The hostname, port, and service name of the Oracle Database you wish to connect to

Recommended Instance Type: t3.small (2 vCPU, 2 GB RAM) or larger. The minimum requirements are 1 vCPU, 1 GB RAM, and 20 GB disk space.

Step 1: Launch the AMI

  1. Navigate to the AWS Marketplace and search for "Oracle DB 23ai Client cloudimg"
  2. Click Continue to Subscribe, accept the terms, then Continue to Configuration
  3. Select your preferred Region and Software Version
  4. Click Continue to Launch
  5. Choose Launch through EC2 for full control over instance configuration
  6. Select your instance type (t3.small recommended)
  7. Configure storage: 20 GB gp3 minimum
  8. Configure your Security Group with the following inbound rules:
Port Protocol Source Purpose
22 TCP Your IP SSH access
  1. Select your EC2 key pair and launch the instance

Step 2: Connect via SSH

Once your instance is running and has passed both status checks (2/2), connect using SSH:

ssh -i your-key.pem ec2-user@<public-ip-address>

To switch to the root user:

sudo su -

Important: Wait for the EC2 instance to reach 2/2 successful status checks before connecting. Early connection attempts may produce permission denied errors while the instance is still initialising.

Step 3: Switch to the Oracle User and Set Environment

The Oracle Client software is owned by the dedicated oracle OS user. Switch to this user and source the environment. Please type this command rather than copying and pasting:

sudo su - oracle
cd $HOME
. ./setEnv.sh

The setEnv.sh script sets the Oracle environment variables required for utilities such as sqlplus.

Step 4: Configure tnsnames.ora

Before connecting to a remote Oracle Database, you need to create a tnsnames.ora configuration file. Run the following commands as the oracle user, replacing the placeholder values with your target database details:

cd $HOME
. ./setEnv.sh

echo 'MY_DATABASE =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = YOUR_DB_HOSTNAME)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = YOUR_SERVICE_NAME)
    )
  )
' > "$ORACLE_HOME/network/admin/tnsnames.ora"

Replace the following values: - YOUR_DB_HOSTNAME with the IP address or DNS name of your Oracle Database server - 1521 with the port number if different from the default - YOUR_SERVICE_NAME with the service name of the target database

Step 5: Connect to a Remote Database via SQL*Plus

Set the Oracle environment variables and connect to your remote database:

cd $HOME
. ./setEnv.sh
sqlplus 'system/password@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=your-db-host)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=your-service-name)))'

Replace system, password, your-db-host, and your-service-name with your actual database connection details.

Expected output:

SQL*Plus: Release 23.x.x.x Production

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

Connected to:
Oracle Database 23ai ...

SQL>

Type EXIT to leave the SQL*Plus session.

Server Components

Component Version Install Path
Oracle Client 23ai 23ai /u01

Note: Component versions may be updated on first boot by the automatic OS package update script.

Filesystem Layout

Mount Point Size Description
/ 38 GB Root filesystem
/boot 2.0 GB Operating system kernel files
/u01 20 GB Oracle software installation directory

On Startup

An OS package update script runs on first boot to ensure the image is fully up to date. You can disable this by removing the script and its crontab entry:

rm -f /stage/scripts/initial_boot_update.sh

crontab -e
# Delete the following line, save and exit:
@reboot /stage/scripts/initial_boot_update.sh

Troubleshooting

Cannot connect via SSH

  1. Verify the instance has reached 2/2 status checks in the EC2 console
  2. Confirm your security group allows inbound TCP port 22 from your IP
  3. Ensure you are using the correct key pair and connecting as ec2-user

SQL*Plus cannot connect to remote database

  1. Verify the target database is running and accepting connections
  2. Check the hostname, port, and service name are correct
  3. Ensure the security group of the target database allows inbound port 1521 from this client instance
  4. Test network connectivity: telnet <db-host> 1521

ORA-12541: TNS:no listener

  1. The target database listener is not running. Contact the database administrator.

ORA-12514: TNS:listener does not currently know of service

  1. The service name in your connection string does not match the target database. Verify the correct service name with the database administrator.

Security Recommendations

  • Restrict SSH access: Only allow port 22 from trusted IP addresses
  • Secure credentials: Never store database passwords in plain text files
  • Use Oracle Wallet: Configure Oracle Wallet for secure credential storage
  • Encrypt connections: Configure Oracle Net Services to use SSL/TLS encryption
  • Keep the system updated: Apply OS security patches regularly

Support

If you encounter any issues with this product, contact cloudimg support:

  • Email: support@cloudimg.co.uk
  • Website: www.cloudimg.co.uk
  • Support hours: 24/7 with guaranteed 24 hour response SLA