OUDbase environment scripts for Oracle Unified Directory Part 1

Almost two years ago I started writing environment scripts for my Oracle Unified Directory installations. At the beginning there were only 2-3 scripts, from which at some point a small project on GitHub emerged. A lot has changed since my blog post Environment Scripts for OUD. The current version of OUDbase (v1.5.5) has a number of useful functions that make working with OUD on the command line much easier. This is one reason it is time to write about OUDbase once again. Or better to start a small blog series.

Features at a Glance

At the end of the day, it’s just a script that sets a series of aliases and environment variables. But this script does exactly what it should, it simplifies the work of the administrator. Initially it has been developed for Oracle Unified Directory (OUD), but to a certain degree other Oracle directory server and tools like Oracle Unified Directory Services Manager (OUDSM), Oracle Directory Server Enterprise Edition (ODSEE) and Oracle Internet Directory (OID) are supported as well.

  • Support of various Oracle directory servers and tools
  • Support for Oracle directory servers on Docker
  • Small foot print and minimal requirements
  • Simple and quick installation
  • Auto-configure for common environments and Oracle homes
  • Provide a kind of OFA environment for Oracle directory servers
  • Flexible environment handling eg. easy switching between different environments
  • Alias definitions
  • Platform-independent
  • More flexible and powerful than… wait, there is not oraenv for Oracle directory servers 🙂
  • Customization of environment variables and aliases globally or per instance
  • Miscellaneous templates for cron.d, logrotate.d, systemd service and instance creation

In particular OUDbase provides the following scripts:

  • oudtab as a central configuration file for instance names, ports and directory types
  • oudenv.sh script to source and set the environment
  • oud_backup.sh script to backup specific or all Oracle Unified Directory instances
  • oud_export.sh script to export specific or all Oracle Unified Directory instances
  • oud_status.sh script to check the status of an Oracle Unified Directory instance including replication status
  • oud12c_eus template and scripts to create an Oracle Unified Directory server with Enterprise User Security integration
  • oud12c_eus_ad_proxy template and scripts to create an Oracle Unified Directory proxy server with Enterprise User Security and MS Active Directory integration
  • generic template and scripts as base for customisation

Requirements

OUDbase is modest. You just need a bash shell to run it and tar/gzip to install it. This is also one of the reasons why it perfectly fits on OUD Docker images. Although you do not run several directory servers in one Docker container, it is convenient to work on the command line. A little further up I mentioned that OUDBase is platform-independent. At least one operating system, which does not support bash out of the box. Guess which one? Yes, exactly Microsoft Windows. Basically, OUDbase should also run on MS Windows if bash is installed there. However, this has not yet been tested.

Installation

Before you can start the installation of OUDbase, you have to download the latest version from the GitHub repository oehrlis/oudbase. OUDbase is available as TAR file or as shell installation script. The shell script itself is regular Bash script with additional payload. This means that the TAR file is appended directly at the end of the script. Since the embedded TAR is base64 encoded, the installation script can be sent by mail without any problems. If you are interested in how to do this I recommend the How-To Add a Binary Payload to your Shell Scripts written by Mitch Frazier / Linux Journal.

The script does relay on the directory structure optimal flexible architecture (OFA) introduced by Oracle a couple of years ago. Starting from an ORACLE_BASE path, the installation script evaluates the required parameters based on OFA. If you do use a different structure you can give the necessary directory path via parameters. The following code block does show the oudbase_install.sh usage.

oracle@oudad:/u00/app/oracle/ [oud_ad] ./oudbase_install.sh -h
Start of oudbase_install.sh (Version v1.5.5) with -h
processing commandline parameter
Usage, oudbase_install.sh [-hav] [-b ]
[-i ] [-B ]
[-m ] [-f ] [-j ]

-h Usage (this message)
-v enable verbose mode
-a append to profile eg. .bash_profile or .profile
-b ORACLE_BASE Directory. Mandatory argument. This
directory is use as OUD_BASE directory
-o OUD_BASE Directory. (default $ORACLE_BASE).
-d OUD_DATA Directory. (default /u01 if available otherwise $ORACLE_BASE).
This directory has to be specified to distinct persistant data from software
eg. in a docker containers
-A Base directory for OUD admin (default $OUD_DATA/admin)
-B Base directory for OUD backups (default $OUD_DATA/backup)
-i Base directory for OUD instances (default $OUD_DATA/instances)
-m Oracle home directory for OUD binaries (default $ORACLE_BASE/products)
-f Oracle Fusion Middleware home directory. (default $ORACLE_BASE/products)
-j JAVA_HOME directory. (default search for java in $ORACLE_BASE/products)

Logfile : /u01/log/oudbase_install.log

The following table does provide an overview of installation path, environment variables, parameters and there default values.

Parameter ENV Variable Default Value Description
-v n/a n/a Enable verbose mode
-a n/a n/a Append to profile eg. .bash_profile or .profile
-b $ORACLE_BASE /u00/app/oracle Mandatory argument. This directory is use as ORACLE_BASE from which all other directories are evaluated.
-b $ORACLE_BASE /u00/app/oracle Mandatory argument. This directory is use as ORACLE_BASE from which all other directories are evaluated.
-o $OUD_BASE $ORACLE_BASE OUDbase base directory where the scripts, config etc. will be installed. Usually this is the same directory as used for ORACLE_BASE. Due to some legacy requirement this can be separate directory.
-d $OUD_DATA /u01 or $ORACLE_BASE Directory to store the persistant data eg. the OUD instance homes, backup and admin directories etc. It defaults /u01 if available otherwise $ORACLE_BASE. This directory has to be specified to distinct persistant data from software eg. in a docker containers.
-A $OUD_ADMIN_BASE $OUD_DATA/admin Base directory for an instance specific admin directory, similar to the admin directory of Oracle databases.
-B $OUD_BACKUP_BASE $OUD_DATA/backup Base directory for an instance specific directory to store backup’s and LDIF exports.
-i $OUD_INSTANCE_BASE $OUD_DATA/instances Base directory for the OUD instance homes.
-m $ORACLE_HOME $ORACLE_BASE/products Oracle home directory for binaries. The installation script does search below this path for the corresponding binaries.
-f $ORACLE_FMW_HOME $ORACLE_BASE/products Oracle Fusion Middleware home directory when separating the OUD and OUDSM binaries. The installation script does search below this path for the corresponding binaries.
-j $JAVA_HOME $ORACLE_BASE/products Location of the java home. The installation script does search below this path for the corresponding java binaries.

The installation script will guess the required parameter based on OFA. All parameter specified at the command line will be stored for future use in oudenv_core.conf. If something went wrong during installation, you always have the option of adjusting them manually.

Let’s create an installation as an example. We will use /u00/app/oracle as ORACLE_BASE, /u01 as OUD_DATA and /u00/app/oracle/product/fmw12.2.1.3.0 as ORACLE_HOME. Below you find the command and an excerpt of the output. Ok actually everything except the output of the TAR command.

oracle@oudad:/tmp/ [oud_ad] ./oudbase_install.sh -v -b /u00/app/oracle -d /u01 -m /u00/app/oracle/product/fmw12.2.1.3.0
2018-07-16_20:45:46 START: Start of oudbase_install.sh (Version v1.5.5) with -v -b /u00/app/oracle -d /u01 -m /u00/app/oracle/product/fmw12.2.1.3.0
2018-07-16_20:45:46 INFO : processing commandline parameter
2018-07-16_20:45:46 INFO : Define default values
2018-07-16_20:45:46 INFO : Using the following variable for installation
2018-07-16_20:45:46 INFO : ORACLE_BASE = /u00/app/oracle
2018-07-16_20:45:46 INFO : OUD_BASE = /u00/app/oracle/local/oudbase
2018-07-16_20:45:46 INFO : LOG_BASE = /u01/log
2018-07-16_20:45:46 INFO : ETC_CORE = /u00/app/oracle/local/oudbase/etc
2018-07-16_20:45:46 INFO : ETC_BASE = /u01/etc
2018-07-16_20:45:46 INFO : OUD_DATA = /u01
2018-07-16_20:45:46 INFO : OUD_INSTANCE_BASE = /u01/instances
2018-07-16_20:45:46 INFO : OUD_ADMIN_BASE = /u01/admin
2018-07-16_20:45:46 INFO : OUD_BACKUP_BASE = /u01/backup
2018-07-16_20:45:46 INFO : ORACLE_PRODUCT =
2018-07-16_20:45:46 INFO : ORACLE_HOME = /u00/app/oracle/product/fmw12.2.1.3.0
2018-07-16_20:45:46 INFO : ORACLE_FMW_HOME = /u00/app/oracle/product/fmw12.2.1.3.0
2018-07-16_20:45:46 INFO : JAVA_HOME = /usr/java/jdk1.8.0_172
2018-07-16_20:45:46 INFO : SCRIPT_FQN = /tmp/oudbase_install.sh
2018-07-16_20:45:46 INFO : Installing OUD Environment
2018-07-16_20:45:46 INFO : Create required directories in ORACLE_BASE=/u00/app/oracle
2018-07-16_20:45:46 INFO : Create Directory /u01/log
2018-07-16_20:45:46 INFO : Create Directory /u01/etc
2018-07-16_20:45:46 INFO : Create Directory /u00/app/oracle/local
2018-07-16_20:45:46 INFO : Create Directory /u01/admin
2018-07-16_20:45:46 INFO : Create Directory /u01/backup
2018-07-16_20:45:46 INFO : Create Directory /u01/instances
2018-07-16_20:45:46 INFO : Create Directory /u00/app/oracle/local/oudbase
2018-07-16_20:45:46 INFO : Backup existing config files
2018-07-16_20:45:47 INFO : Backup oudtab to oudtab.save
2018-07-16_20:45:47 INFO : Backup oud.<em>DEFAULT</em>.conf to oud.<em>DEFAULT</em>.conf.save
2018-07-16_20:45:47 INFO : Start processing the payload
2018-07-16_20:45:47 INFO : Payload is available as of line 470.
2018-07-16_20:45:47 INFO : Extracting payload into /u00/app/oracle/local
2018-07-16_20:45:47 INFO : Payload is set to base64. Using base64 decode before untar.
...
2018-07-16_20:45:47 INFO : Store customization in core config file /u00/app/oracle/local/oudbase/etc/oudenv_core.conf
2018-07-16_20:45:47 INFO : save customization for OUD_DATA (/u01)
2018-07-16_20:45:47 INFO : save customization for ORACLE_BASE (/u00/app/oracle)
2018-07-16_20:45:47 INFO : save customization for ORACLE_HOME (/u00/app/oracle/product/fmw12.2.1.3.0)
2018-07-16_20:45:47 INFO : Please manual adjust your .bash_profile to load / source your OUD Environment
2018-07-16_20:45:47 INFO : using the following code
#Check OUD_BASE and load if necessary
if [ "${OUD_BASE}" = "" ]; then
if [ -f "${HOME}/.OUD_BASE" ]; then
. "${HOME}/.OUD_BASE"
else
echo "ERROR: Could not load ${HOME}/.OUD_BASE"
fi
fi

#define an oudenv alias
alias oud='. ${OUD_BASE}/bin/oudenv.sh'

#source oud environment
. /u00/app/oracle/local/oudbase/bin/oudenv.sh
2018-07-16_20:45:47 INFO : update your .OUD_BASE file /home/oracle/.OUD_BASE
2018-07-16_20:45:47 END : of oudbase_install.sh

As you can see from the output above, you just have to source .OUD_BASE and ${OUD_BASE}/bin/oudenv.sh to start using OUDbase. The installation script either provides an example of what you need to add to your .bash_profile or adjusts it directly by specifying the parameter -a.

#Check OUD_BASE and load if necessary
if [ "${OUD_BASE}" = "" ]; then
if [ -f "${HOME}/.OUD_BASE" ]; then
. "${HOME}/.OUD_BASE"
else
echo "ERROR: Could not load ${HOME}/.OUD_BASE"
fi
fi

#define an oudenv alias
alias oud='. ${OUD_BASE}/bin/oudenv.sh'

#source oud environment
. /u00/app/oracle/local/oudbase/bin/oudenv.sh

The next time you login, you’ll see the status of you OUD instance. If you do not have an OUDTAB file, OUDbase will create one for you based on existing OUD instances, Oracle homes etc.

If you haven’t yet installed any Oracle software or created an OUD instance OUDbase can not guess your environment. Therefore you have to manually create an OUDTAB file.

WARN : oudtab (/u00/app/oracle/local/oudbase/etc/oudtab) does not exist or is empty. Create a new one.
WARN : No OUD Instance yet available or defined.

Conclusion

The first blog post of the serie on the OUDbase environment scripts should give you first impression. The installation is straight forward and simple. In the next blog post I’ll show how you can configure and customize OUDbase. Beside a couple of use cases, I’ll provide a deeper insight into environment variables, aliases and scripts. So stay tuned. If you can not wait get the latest version of OUDbase from GitHub and start using it. By the way, my Docker build scripts are configured to use OUDbase.

References

Below you find a few references related to the topics discussed in this post: