1. Simulator Labs
  2. Setting Up the Oracle Database Appliance Simulator

1 Setting Up the Oracle Database Appliance Simulator

Understand the tasks for setting up, deploying, and patching Oracle Database Appliance.

The Oracle Database Appliance X8-2 simulator application is a container-base simulator on Oracle Cloud Infrastructure (OCI) that simulates the operation of an Oracle Database Appliance X8-2 single-node or high-availability (2 nodes) system. You must have an OCI account to run the Oracle Database Appliance simulator. When you launch the Oracle Database Appliance simulator on the OCI Marketplace, a simulator VM is started in your tenancy. If you use the Always Free OCI account, due to the 1 GB memory limitation, it is recommended that you set up the simulator with the single-node option. Following are the steps to set up the simulator environment so that you can run the Oracle Database Appliance hands-on labs to learn how to deploy, patch, and manage an Oracle Database Appliance.

Prerequisites for Setting up the Simulator

Understand the prerequisites for setting up the Oracle Database Appliance simulator.

Requirements

  • You must have an OCI account and credentials.
  • You must also have the VM IP address to access the simulator VM and setup the environment for the Oracle Database Appliance hands-on labs.

Create a Key with PuTTYgen

If you use Putty to create a key, you must create a key with PuTTYgen:
  1. Generate key of type RSA.
  2. Save the private key.
  3. Under Public key for pasting into OpenSSH authorized_keys file: copy all contents in the box and paste into a text file and save as a .pub file. This is the key you use when you setup the Oracle Database Appliance simulator instance.

Important:

You must configure network security rules first to access Oracle Database Appliance BUI.

Configure Network Security Rules

  1. Open your OCI application VM and click on your VCN link above Virtual Cloud Network.
  2. Click Security Lists in the left panel and click on the Default Security List for your_vcn in the middle of the screen.
  3. Click Add Ingress Rules and fill in following information:
    SOURCE TYPE :CIDR 
SOURCE CIDR :  0.0.0.0/0
 IP PROTOCOL : TCP
  4. Click Add Ingress Rule. Similarly add egress rule for outgoing traffic, if not already added.

Parent topic: Setting Up the Oracle Database Appliance Simulator

Installing the Simulator

Follow these steps to install the simulator.

Docker is installed in the simulator VM by default.

  1. Log into the simulator VM:
    ssh -i key opc@IP address     (OCI public IP address)
  2. Switch to root user:
    $sudo -s
  3. Navigate to the simulator directory, where 19.xx.0.0.0 is the release number.
    # cd simulator_19.xx.0.0.0
  4. Run the following command to make sure that the docker is running:
    # docker ps
  5. You may see a default container running already, for example, oda-1. If that is the case, then you are set up to connect to the container to run the ODACLI commands already. Run the following command:
    # ./connectContainer.sh -n odasim-1
  6. No password is required for an OCI VM.

To access the Oracle Database Appliance simulator:

Ensure that you have access to the port number assigned to the container.

  1. Go to the simulator log directory.
    cd ${SIMULATOR_HOME}//log

    where SIMULATOR_HOME is the directory from which you ran the createOdaSimulatorContainer command.

  2. Run the cat command for the most recent log file.
    cat 
ODA Simulator system info:
Executed on: 2023_06_14_06_33_PM
Executed by:
num= 1         
dept= oda      
hostpubip=      

USERS:
Container : oda-1
ODA Console: https://ip_of_simulator_machine :7095/mgmt/index.html 
ODA cli access: Connect to the host and run following command:
sh connectContainer.sh -n oda-1

    Note the port number, for example, 7095.

Following are optional steps for manually managing the containers.

Note that if you are running the simulator standalone on a Linux system, then you must run the following steps.
  1. Run the following command to make sure the docker is running and to view which containers are running:
    #docker ps
  2. If you see any unwanted container running, run the cleanup script to start fresh:
    #./cleanup_odasimulator_sw.sh
  3. Run the simulator setup script:
    # ./setup_odasimulator_sw.sh noportainer

    For always free OCI account with 1GB memory, it is recommended that you set up the simulator with one user and the single node option.

  4. If a default container is not running, you can manually create a single node container for a user.
    # ./createOdaSimulatorContainer.sh -d oda -t single -o noportainer
  5. A single container called oda-1 is created. To view the options, use the following command:
    # ./createOdaSimulatorContainer.sh -help
  6. For standard OCI account with minimum 2GB memory, it is recommended that you set up the simulator with the high-availability option:
    # ./createOdaSimulatorContainer.sh -d oda -t ha -o noportainer
  7. For each Oracle Database Appliance X8-2-HA simulator user, two containers, oda-1-node0 and oda-1-node1, are created. Ignore any warning messages about Agent or Zookeeper. Ensure that you can connect to the container. Note the assigned port numbers in the following output. The port numbers are necessary for logging into the simulator Browser User Interface (BUI).
    ODA Simulator system info:
Executed on: 2023_06_11_03_23_PM
Executed by:
num= 1         
dept= oda      
hostpubip= ip_of_simulator_machine  

USERS:
Container : oda-1-node0
ODA Console: https://ip_of_simulator_machine:7095/mgmt/index.html
ODA cli access: Connect to the host and run following command:
sh connectContainer.sh -n oda-1-node0
Container : oda-1-node1
ODA Console: https://ip_of_simulator_machine:7097/mgmt/index.html 
ODA cli access: Connect to the host and run following command:
sh connectContainer.sh -n oda-1-node1
After you have completed the labs, you must clean up the environment by deleting the user containers. The following command deletes instances oda-1-node0 and oda-1-node1:
#  ./deleteOdaSimulatorContainer.sh -t ha -i 1 -n 1 -d oda
Clean up your log files from the lab by deleting your logs in the /simulator_19.23.0.0.0/log directory. To completely reset the lab, run the following command:
# ./cleanup_odasimulator_sw.sh

This deletes all the containers and the volumes.

Parent topic: Setting Up the Oracle Database Appliance Simulator

Accessing the Oracle Database Appliance Simulator

Follow these steps to access the simulator.

For CLI access, connect by SSH to the simulator VM, connect by sudo to root, and connect to the container, for example, odasim-1. No password is required.
# ./connectContainer.sh -n odasim-1
For a high-availability system, you can access both nodes, for example, oda-1-node0 , oda-1-node1.
# ./connectContainer.sh -n oda-1-node1
For BUI access, use the VM IP address and port number, for example, 7095, 7097.
# https://server_IP:xxxx/mgmt/index.html

Parent topic: Setting Up the Oracle Database Appliance Simulator

Creating a Restore Point or Snapshot for the Oracle Database Simulator

You can create a restore point or snapshot at the end of a lab and go back to it, so you do not have to restart the lab from the beginning.

For example, once you complete Lab 3, you create a restore point at the beginning of Lab 4. During Lab 4, if there is any error, then you can go back to the restore point at the beginning of Lab 4 instead of starting from Lab 1 again.  To create a snapshot, run the following command from the simulator directory:
# ./snapshot.sh  
Usage: snapshot.sh [-c | -r  | -l]  [] | -h                                                                                                                                                                                                                                                                                       

Options:                                                                                                                                                                                            
  create  [ha|single]         Create a new snapshot of the simulator                                                                                                            
  restore   [ha|single]       Restore the simulator to a previous snapshot
  list  [ha|single]           List all snapshots created with their IDs
  help, -h                    Display this help and exit is mandatory. You only need the name of the environment without 'node0' or 'node1' in case the simulator environment is HA is either 'ha' or 'single'. Default is 'single'
Use this script to create and restore snapshots of the Oracle Database Appliance simulator. This is useful when trying different scenarios or for creating backups.   
# ./snapshot.sh create oda-1 
/scratch/user/simulator_19.23_ade/simulator_19.23.0.0.0/snapshots.dat doesn't exist. Creating a new one...
Snapshot with ID: 1 has been created successfully. Timestamp: Wed Jun 22 14:01:24 PDT 2023
# ./snapshot.sh list oda-1
ID      CONTAINER NAME             DEPLOYMENT TYPE  TIMESTAMP
1       oda-1                      single           Wed Jun 22 14:01:24 PDT 2023
#  ./snapshot.sh restore 1 oda-1
Snapshot with ID: 1 has been restored successfully!

Parent topic: Setting Up the Oracle Database Appliance Simulator

About BUI Agent Certificate Issue

Understand the common BUI issues you may encounter when setting up the Oracle Database Appliance simulator.

Requirements

You may encounter a BUI Agent Certificate Issue. See the following example:
https://server IP:7095/mgmt/index.html    
Your assigned port number maybe different

You may see a BUI agent security certificate error message:

Description of bui_certificates_error.png follows
Description of the illustration bui_certificates_error.png
To fix it, you must add a certificate exception to the BUI agent port, with is your assigned port number -1. In this case, the port number is 7097-1 or 7096.
https://server IP:7096 
( Your port number maybe different)
Go through the certificate exception process and add the exception. Then go back to your assigned port.
https://server IP:7095/mgmt/index.html

Go through the certificate exception process again and add the exception. Then you can access the BUI to create the appliance.

Parent topic: Setting Up the Oracle Database Appliance Simulator

Restarting the Simulator in a Container

If the ODACLI commands fails, then check if the Oracle Database simulator is running in the container.

Run the following command to check the status of the simulator:
# /opt/oracle/dcs/bin/statusOdaStack.sh
If the simulator is not running, then start the simulator as follows:
# /opt/oracle/dcs/bin/startOdaStack.sh

Parent topic: Setting Up the Oracle Database Appliance Simulator