Configuring OKV automation using REST APIs

 This post will go through the process of creating a few simple scripts to automate OKV installation using the REST API capability of OKV.

NOTE: This information was provided by the product manager Peter Wahl who has a great blog on the features of OKV and some great "Ask Tom" sessions on OKV (and other security pieces),you can watch and learn more.

Step #1 Configure RESTful Services and download client tool

First you need to configure the OKV server for RESTful Services. The instructions can be found here. This is done by navigating to the System tab and clicking on RESTful Services.

This bring up the window below.

 There are three things you want to do from this window.

1. Click on the "Enable" box to enable RESTful services
2. Download the okvrestcliepackage.zip which are the client utilities.
3. Save this setting to enable RESTful services.

Now that we have this file, we need to download it our client and start creating the scripts to automate this process.

I downloaded the zip file to my DB host to configure it. I unzipped it in /home/oracle/okv/rest

NOTE: you can also download it directly from the OKV hosts

wget --no-check-certificate https://ip_address:5695/okvrestclipackage.zip curl -k https://ip_address:5695/okvrestclipackage.zip -o okvrestclipackage.zip curl -O -k https://ip_address:5695/okvrestclipackage.zip

Step #2 unzip and configure the client tool 

I unzipped the client tool into my home directory on a DB server so I can put together the automation scripts. In my case I unzipped it into /home/oracle/okv/rest. This creates 3 sub directories. I am going to format the output using this command.

find . | sed -e "s/[^-][^\/]*\// |/g" -e "s/|\([^ ]\)/|-\1/"

Below is what the output looks like

.
 |-lib
 | |-okvrestcli.jar
 |-bin
 | |-okv.bat
 | |-okv
 |-conf
 | |-okvrestcli.ini
 | |-okvrestcli_logging.properties

Step #3 - Set the environment for the CLI

In order to configure OKV, I am going to need some variables set in my environment. I can do this manually, but in my case I decided to create a "setenv.sh" script that will set the variables and add the OKV script to my path to be executed.  The 2 main variables I will be using are

OKV_RESTCLI_HOME - Location of the scripts that I am going to be installing. If I source the setenv.sh script, it will set the home to this location.

OKV_RESTCLI_CONFIG - Name of the configuration file that contains the rest CLI configuration.

###Ensure that the setenv file is sourced from the current directory to properly set variables if [ "${BASH_SOURCE[0]}" != "${0}" ] then echo " " else echo " " echo "the setenv.sh file must be sourced with \". ./setenv.sh \"" exit 0 fi FILE=`pwd`/setenv.sh if [ -f "$FILE" ] then echo " " else echo " " echo "source this from RESTful install directory" return fi echo "create environment variables OKV_RESTCLI_HOME and OKC_RESTCLI_CONFIG " ## set variables export OKV_RESTCLI_HOME=`pwd` export OKV_RESTCLI_BIN=$OKV_RESTCLI_HOME/bin export OKV_RESTCLI_CONFIG=$OKV_RESTCLI_HOME/conf/okvrestcli.ini ##add the OKV script to the path echo " " echo "\$OKV_RESTCLI_HOME : $OKV_RESTCLI_HOME " echo "\$OKV_RESTCLI_CONFIG : $OKV_RESTCLI_CONFIG " echo " " echo "Adding \$OKV_RESTCLI_BIN to the \$PATH " echo " " if [[ "$PATH" =~ (^|:)"${OKV_RESTCLI_BIN}"(:|$) ]] then echo " " else PATH=${OKV_RESTCLI_BIN}:$PATH fi

Step #4 - Set initialization parameters in okvrestcli.ini file

Next, I am going to configure the initialization parameters. These are found in the okvrestcli.ini file.

You can see that the file contains a "[Default]" profile and a few other example profiles. We will start with the default profile. In this we are going to set a few of the properties.

LOG_PROPERTY - Location of the logging properties. Default location is ./conf directory.

SERVER - IP address (or DNS) of one or more OKV hosts 

 OKV_CLIENT_CONFIG - location of the config file. Default location is ./conf directory

USER - OKV user that has authority to administer endpoints an wallets.

PASSWORD - Password for the user, or location of wallet containing the password. I am NOT going to use this as I am going to use a wallet file.

 CLIENT_WALLET - I am going to use a wallet to store the password, and this is the location of the wallet file. I will be creating the autologin wallet later.

 

Below is what my "[Default]" configuration file looks like after my changes. I am going to use the environmental variables I set in the setenv.sh script. 

NOTE: I am choosing to store my password in wallet rather than clear text in the .ini file.

 

[Default]
log_property=$OKV_RESTCLI_HOME/conf/okvrestcli_logging.properties
server=10.0.0.150
okv_client_config=$OKV_RESTCLI_HOME/conf/okvclient.ora
user=bgrenn
client_wallet=$OKV_RESTCLI_HOME/conf

Step #5 - Change the okv script to use the variables

Since I chose to use variables (OKV_RESTCLI_HOME) I am changing the OKV script to use those variables

#!/bin/bash if [ -z "$OKV_RESTCLI_HOME" ] then echo "OKV_RESTCLI_HOME environment variable is not set. source the setenv.sh script" exit 1 fi export OKV_RESTCLI_CONFIG=$OKV_RESTCLI_HOME/conf/okvrestcli.ini if [ -z "$JAVA_HOME" ] then echo "JAVA_HOME environment variable is not set." exit 1 fi if [ -z "$OKV_RESTCLI_CONFIG" ] then echo "OKV_RESTCLI_CONFIG environment variable is not set." exit 1 fi java -jar $OKV_RESTCLI_HOME/lib/okvrestcli.jar "$@"

Step #6 Create the wallet to save the password encrypted

Since I chose to put my password in a wallet, I now need to create that wallet. Using the instructions in the document (linked to at the beginning of this blog), I execute the command from the directory I installed into (/home/oracle/okv/rest)

cd /home/oracle/okv/rest
. ./setenv.sh


   create environment variables OKV_RESTCLI_HOME and OKC_RESTCLI_CONFIG

   $OKV_RESTCLI_HOME    :  /home/oracle/okv/rest
   $OKV_RESTCLI_CONFIG  :  /home/oracle/okv/rest/conf/okvrestcli.ini

   Adding $OKV_RESTCLI_BIN to the $PATH



okv admin client-wallet add --client-wallet $OKV_RESTCLI_HOME/conf --wallet-user bgrenn
Password: {my password}
{
  "result" : "Success"
}

Step #7 Create the run-me.sh script

The last step is to create the script that will be executed  on the host to create the provision script.  In my script, I took the default and did some checking. This script will

• Ensure the variable OKV_RESTCLI_HOME is set before it can be executed.
• Determine the DB_UNIQUE_NAME from the $ORACLE_BASE/diag/rdbms/*/$ORACLE_SID directory. Solving for the  * should give us the DB_UNIQUE_NAME
• While executing, it tells you what it believes the DB_UNIQUE_NAME is, and gives you a chance to change it if incorrect.
• It will validate if the wallet exists by accessing OKV. If the wallet already exists, it does not try to create it again. If it doesn't exist it will create the wallet and endpoint group.
• It will install the client software in $ORACLE_BASE/admin/$DBUNQNAME/wallet/okv

Below is the script I am using.

#!/bin/bash if [ -v OKV_RESTCLI_HOME ] then echo " " echo "executing script with \$OKV_RESTCLI_HOME=$OKV_RESTCLI_HOME" echo " " echo " " else echo " " echo "\$OKV_RESTCLI_HOME not set" echo " " echo "source the setenv.sh script in the RESTful Services install directory and try again." echo " " exit 0 fi pushd $ORACLE_BASE/diag/rdbms/*/$ORACLE_SID > /dev/null cd .. export DB_NAME=`printf '%s\n' "${PWD##*/}"` popd > /dev/null echo "DB Name is identified as $DB_NAME and ORACLE_SID is set to $ORACLE_SID setting" echo " " echo "Press enter to keep this default [$DB_NAME], or enter the DB Name" read -p 'DB Name [enter for Default] : ' newdbname if [ -z "$newdbname" ] then export DBNAME=`echo $DB_NAME` else export DBNAME=`echo $newdbname` fi echo " " echo "Using DB Name : $DBNAME" echo " " export EP_NAME=`echo ${ORACLE_SID^^}_on_${HOSTNAME/.*} | sed 's/\-/\_/g'` export wallet_exists=`okv manage-access wallet check-status --wallet ${DBNAME^^} | grep Success | wc -l` if [ $wallet_exists -ne 0 ] then export create_wallet="## Wallet ${DBNAME^^} already exists skipping wallet creation" else export create_wallet=`echo 'okv manage-access wallet create --wallet ${DBNAME^^} --description "wallet for database ${DBNAME^^)"--unique FALSE'` fi cat > $OKV_RESTCLI_HOME/okv-ep.sh << EOF1 #!/bin/bash mkdir -pv ${ORACLE_BASE}/admin/$ORACLE_SID/wallet mkdir -pv ${ORACLE_BASE}/admin/$ORACLE_SID/wallet/okv EOF1 export wallet_exists=`okv manage-access wallet check-status --wallet ${DBNAME^^} | grep Success | wc -l` if [ $wallet_exists -ne 0 ] then echo " Wallet ${DBNAME^^} already exists skipping wallet creation. assuming this is NOT the first node in the cluster" else cat >> $OKV_RESTCLI_HOME/okv-ep.sh << EOF2 okv manage-access wallet create --wallet ${DBNAME^^} --description "wallet for database ${DBNAME^^}"--unique FALSE EOF2 fi cat >> $OKV_RESTCLI_HOME/okv-ep.sh << EOF3 okv admin endpoint create --endpoint ${EP_NAME} --description "$HOSTNAME, $(hostname -i)" --type ORACLE_DB --platform LINUX64 --unique FALSE okv manage-access wallet set-default --wallet ${DBNAME^^} --endpoint ${EP_NAME} expect << _EOF set timeout 120 spawn okv admin endpoint provision --endpoint ${EP_NAME} --location ${ORACLE_BASE}/admin/$ORACLE_SID/wallet/okv --auto-login FALSE expect "Enter Oracle Key Vault endpoint password: " send "change-on-install\r" expect eof _EOF EOF3 chmod +x $OKV_RESTCLI_HOME/okv-ep.sh more $OKV_RESTCLI_HOME/okv-ep.sh

Step #8 Zip it all up and place it in a location to be downloaded

Below is the scripts that will be part of the zip file.

.
 |-lib
 | |-okvrestcli.jar
 |-bin
 | |-okv.bat
 | |-okv
 |-conf
 | |-okvrestcli_logging.properties
 | |-ewallet.p12.lck
 | |-ewallet.p12
 | |-cwallet.sso.lck
 | |-cwallet.sso
 | |-okvrestcli.ini
 |-setenv.sh
 |-run-me.sh

Now I am ready to download this zip file to my Database Host and enroll a database.

NOTE: To change the script to work on another OKV all host I only had to make 3 changes.

• Update the okvrestcli.ini file with OKV host IP
• Update the okvrestcli.ini file with the the user
• recreate the wallet file that contains the password for the OKV user