a collection of scripts to ease the day-to-day work of an Oracle DBA
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
izzy 380fb7a77e ohenv: determine ohpath based on script location (instead of using hardcoded path) 2 years ago
README.md ohctl: add hint on initial deployment on a virgin machine to README 2 years ago
create_sqlite_db adding Oracle Home ConTroL (ohctl) 2 years ago
move_db_home.md move_db_home: add hint on how to update ORACLE_HOME in OEM via CLI 2 years ago
ohctl ohctl: also output which config files are linked (not just which are skipped) 2 years ago
ohenv ohenv: determine ohpath based on script location (instead of using hardcoded path) 2 years ago


Oracle Home Management with Golden Images

This work is heavily based on a blog series by Ludovico Caldara, which can be found here. Ludovico is an Oracle ACE Director currently working at CERN.

ALL CREDITS ON THIS GO TO LUDOVICO! To me (Izzy) just the SQLite part and some minor improvements.

His ohctl (Oracle Home ConTroL) script manages Oracle homes based on „Golden Images” (also called „Gold Images” in some places) – which basically means:

  • You have one Oracle Home where no database is running
  • On this home, you can apply patches without the need of any downtime
  • You convert the patched home into a „Golden Image” which you then can deploy with minimal downtime, and erasing the need for multiple patches (patch once, deploy many)

Many of the steps required are automated by this script:

  • Cloning an existing Oracle Home to create an (initial) Golden Image
  • Managing existing Golden Images for deployment
  • Deploying Golden Images to a new environment (including your „Management Environment” you will use for patching)
  • Basic adjustment of the new environment (deploying centrally stored tnsnames.ora, sqlnet.ora etc)

Patches still need to be performed manually, but the deployment process is almost fully automated. In addition to an existing Oracle Environment (what else would you need this for), Ludovico's script needs:

  • An NFS Export (or other network drive available on all your Oracle servers) to store the Golden Images on
  • The Oracle Instant Client (for initial deployment on a server that does not yet have Oracle available); can be downloaded from https://www.oracle.com/database/technologies/instant-client/downloads.html You will need the instaclient-basic[lite] and instaclient-sqlplus
  • A centrally available Oracle Database to store its own repository table in.

The latter sometimes is a no-go with isolated environments (where one doesn't want cross-environment access). For those I've adjusted the script. So the version you find here replaces the second requirement by „SQLite3 executable must be available in the $PATH” – and uses an SQLite database in a location you can configure inside the script (replacing the third requirement). This modified script is what is referred to by the following chapters.


First a disclaimer: No guarantees what-so-ever. Please check the script yourself thoroughly, you might need adjustments. Test things first before using it in production. Make backups. And all that stuff.

Configure ohctl

Configuration can be done at the top of the script (in the original script, this was in the middle of the script – after the function definitions and before the main logic started). Each setting is accompanied by a short description, so please see there for details. ohctl also relies on ohenv, where you might need to adjust ORAINSTLOC.

Preparing the SQLite database

Just run the Bash script create_sqlite_db and then copy the (empty) initial database file ohctl.db to the location you configured in the previous chapter.

Preparing the environment for ohctl

ohctl calls to one Bash function called setoh (to set up the environment for the database to work on). You find this function in ohenv. You might wish to integrate this (and the lsoh() function contained in the same script) with your environment, e.g. by copying it into your .bashrc. If you do so, do NOT comment out the call that sources ohenv from ohctl as it otherwise does not find the function.

Second thing you need to have ready is the directory holding your Golden Images. You might wish to store the script(s) in the same place, to have them available in all environments you want to use them; this location should be on a network drive (e.g. a NFS export).

Running ohctl

To get available parameters and options, simply start the script with the parameter -h („help”) or -?.

Working with these scripts

List available homes

The function lsoh() can be used for this. Simply call it without any parameters and check the output. You should see something like

oracle $> lsoh
HOME                        LOCATION                            VERSION      EDITION
--------------------------- ----------------------------------- ------------ -------
OraGI12Home1                /u01/app/grid/product/grid   GRID
OraDB12Home1                /u01/app/oracle/product/   DBMS EE

Creating your first Golden Image

When you start, you won't have a single Golden Image available. So the first thing you certainly want to do is to create one, cloning it from an existing Oracle Home. While doing so, you might wish to take care for naming conventions (read the blog articles for why and other details on this).

./ohctl -c -n <new_name>

will create your Golden Image from the current ORACLE_HOME and give it the name you passed with -n. Assuming you have a „fresh install” of Oracle at /u01/app/oracle/product/ (as in the above example), and followed the blog and its reasoning, your actual command line could look like this:

./ohctl -c -n DB12_1_0_2

Follow the progress to see if everything worked out as it should: the new Golden Image should have been created and recorded with ohctl's repository. If at any time you need to start over with the same Golden Image, add the -f parameter to the command to tell ohctl you want to replace the existing copy (else it will refuse to do so, assuming you made a mistake):

./ohctl -c -n DB12_1_0_2 -f

List available Golden Images

Now you've created one, it should be recorded to the repository. Let's check:

oracle $> ./ohctl -l

Listing existing golden images:

OH_Name                             Created    Installed locally?
----------------------------------- ---------- ------------------
12_1_0_2                            2018-02-06 Not installed

No, it's not installed – but that's correct: you didn't install the Golden Image to an ORACLE_HOME but rather walked the opposite direction: created a Golden Image from an existing ORACLE_HOME. So all is fine (though the real reason for showing "Not installed" is that the names don't match).

Deploying (installing) a Golden Image

Now you want to work with your first Golden Image. You want deploy it to a location where no database runs in (maybe even on a different machine) to bring it up to snuff – i.e. apply the latest patch. While when you're reading this that will certainly be a different one, let's stick to Ludovico's examples and assume the July 2017 patch:

./ohctl -i DB12_1_0_2 -n DB12_1_0_2_BP170718

This installs the DB12_1_0_2 image while naming the new home differently, e.g. DB12_1_0_2_BP170718 – so the name reflects the patch set as well. Follow the output and read it carefully. It will tell you there's an additional step you need to perform manually: running the root.sh to complete the setup of the new home. Check with lsoh and see it is available now:

oracle $> lsoh
HOME                  LOCATION                            VERSION      EDITION
--------------------- ----------------------------------- ------------ -------
OraGI12Home1          /u01/app/grid/product/grid   GRID
OraDB12Home1          /u01/app/oracle/product/   DBMS EE
DB12_1_0_2_BP170718   /u01/app/oracle/product/DB12_1_0_2_BP170718   DBMS EE

'''Note:''' when deploying a Golden Image to a machine that does not yet have any Oracle installation, OUI might forget to create the global oraInst.log file (Linux: /etc/oraInst.loc; Solaris: /var/opt/oracle/oraInst.loc); you will find that mentioned at the end of ohctl's output, like

grep: /etc/oraInst.loc: No such file or directory
grep: /ContentsXML/inventory.xml: No such file or directory
The image DB12_1_0_2_RU190716 has been installed but it is not in the inventory. Please check.

To fix this, copy the file manually from the machine the Golden Image was created on, and adjust it correspondingly (permissions and ownership).


Now is patching time. And no need to ask a downtime for that: there's no database running in this environment. So apply the 170718 patchset to the new ORACLE_HOME. When done successfully, you want to create a Golden Image of this patched home. The new naming conventions are already met, so we can go easy:

oracle $> ./ohctl -c
oracle $> ./ohctl -l

Listing existing golden images:

OH_Name                             Created    Installed locally?
----------------------------------- ---------- ------------------
DB12_1_0_2_BP170718                 2018-02-07 Installed
12_1_0_2                            2018-02-06 Not installed

Now you can deploy the patched ORACLE_HOME to your real environments. The only downtime you will need is for switching your databases to the new home – which is significantly smaller than the patching time alone. Please refer to move_db_home.md for things you might need to do in this phase.

Removing Golden Images

Over the years, you'd accumulate quite a lot of Golden Images this way. And you will certainly want to reclaim space of those you no longer need. ohctl of course also provides means for this:

oracle $> ./ohctl -d 12_1_0_2

Removing Oracle Homes

Similarly, you'll wish to remove the old ORACLE_HOMEs once it's clear they'll no longer be used. This can be done with the Oracle Universal Installer, from the command line:

runinstaller -deinstall -silent ORACLE_HOME=current_oracle_home "REMOVE_HOMES={oracle_home_to_be_removed}"

Command line options are described e.g. here. This should de-register the specified home from the central inventory -- but not remove any files. Check afterwards with lsoh to make sure, then continue the cleanup manually by removing the entire old ORACLE_HOME dir.

Note: this command can also be useful if your inventory got messed up, see e.g. How to delete/add Oracle Home entry from central inventory (remove a home, then re-attach it). For a list of options and variables to be used with runInstaller, please see here.

Here be dragons:

With Oracle 12c and up, there's also a the separate Oracle Deinstallation Tool -- but this does NOT seem to be what you want in this case.

export ORACLE_HOME=<Oracle-Home-To_remove>
$ORACLE_HOME/deinstall/deinstall [-silent]

CAUTION: Oracle documentation on the deinstall tool writes:

The deinstallation tool deletes Oracle Database configuration files, user data, and fast recovery area (FRA) files even if they are located outside of the Oracle base directory path.

I have not yet tried this and thus cannot tell its outcome. After patching and moving on to a new home, you certainly stick to your database files and also to your FRA, so it seems this is not the suited tool (and rather intended to remove an installation completely). Again, having a decent backup strategy is strongly advised. Then, a sane starting point would be running

./runInstaller -deinstall -home <path> -silent -checkonly -o <opath> -logdir <lpath>

where <lpath> is the directory to save log files into, and <opath> to store generated files -- which should (thanks to -checkonly) include a response file for deinstallation after investigating and adjusting it, without anything being removed in this run.