From the Command Line into the to the Oracle Cloud – the ORACLE-DBCS-CLI Utility

The Oracle ORACLE-DBCS-CLI utility is a command-line interface tool to manage the lifecycle of your Database as as Service instances in cloud.oracle.com. You can create and delete instances, verify and apply patches, scale your instances up and down and many more. The advantage is that you can work with configuration files. And I like to work with such files, if I need 10 instances with the same shape, I have only to search and replace the instance name – fire!

The ORACLE-DBCS-CLI utility is available for Unix platforms at the moment. I have installed ORACLE-DBCS-CLI on a Oracle Linux 6.5, JDK version 1.7 or higher is required.

Download and Documents

The software can be downloaded here: http://www.oracle.com/technetwork/database/database-cloud/public/downloads/index.html

The  ORACLE-DBCS-CLI documentation starts here: https://docs.oracle.com/cloud/latest/dbcs_dbaas/CSDBI/GUID-E9F2219D-EBDC-44B3-BE22-BEED6C2BAB74.htm#CSDBI-GUID-E9F2219D-EBDC-44B3-BE22-BEED6C2BAB74

Installation

After download the software has to be extracted on target server. My install directory is /u00/app/oracle/tools/dbcs-cli/ – take care about the release number.

$ tar -vxzf ./oracle-dbcs-cli_15.4.2.tar.gz

What you get:

oracle@solothurn:/u00/app/oracle/tools/dbcs-cli/ [rdbms12102] ll
total 6192
drwxr-xr-x. 2 oracle oinstall 4096 Feb 18 08:05 .
drwxr-xr-x. 3 oracle oinstall 4096 Feb 18 08:06 ..
-r-xr-xr-x. 1 oracle oinstall 6556 Feb 18 08:05 dboplan.dat.external.tmpl
-r-xr-xr-x. 1 oracle oinstall 6556 Feb 18 08:05 dboplan.dat.tmpl
-rw-r--r--. 1 oracle oinstall 3329598 Feb 18 08:05 dborch.jar
-r-xr-xr-x. 1 oracle oinstall 11372 Feb 18 08:05 oracle-dbcs-cli
-rw-r--r--. 1 oracle oinstall 2964193 Feb 18 08:05 oracle-dbcs-cli_15.4.2.tar.gz
-r-xr-xr-x. 1 oracle oinstall 6438 Feb 18 08:05 readme.txt

The dboplan.dat.tmpl is a template file which contains all required variables for working with cloud.oracle.com. For some actions you only need a subset of them.

Get Domain Information

To gather information about your created instances, you need this four parameters.

sm_url Endpoint URL – Attention: for EMEA it’s https://dbcs.emea.oraclecloud.com/paas/service/dbcs/api/v1.1/instances and not https://dbaas.oraclecloud.com/paas/service/dbcs/api/v1.1/instances as written in the documentation
user_name Your cloud.oracle.com user name
password Your cloud.oracle.com password
identity domain Your identity domain – e.g. trivadis4703

 

For this action, I have created a small configuration file which contains these four lines:

#-------------------------------------------------------------------------------
# Specify the SM related info
#-------------------------------------------------------------------------------
sm_url= https://dbcs.emea.oraclecloud.com/paas/service/dbcs/api/v1.1/instances
user_name= <YOUR_USERNAME_HERE>
password= <YOUR_PASSWORD_HERE>
identity_domain= trivadis4703

Now I can execute ORACLE-DBCS-CLI with the configuration file, all my instances in the specified domain are listed:

oracle@solothurn:/u00/app/oracle/tools/dbcs-cli/ [rdbms12102] ./oracle-dbcs-cli list -cfg trivadis4703.cfg

Database Cloud Orchestration Tool:Release 2.0.289.15.52 on Thu Feb 18 09:44:58 CET 2016
Copyright ©2014,2015, Oracle. All rights reserved.

CLOUD02 OCPUs: 2
Version: 12.1.0.2 Date Created: Thu Feb 18 5:59:59 UTC 2016 Memory: 15 GB
Edition: Enterprise Edition - High Performace

CLOUD01 OCPUs: 2
Version: 12.1.0.2 Date Created: Tue Dec 29 21:10:21 UTC 2015 Memory: 15 GB
Edition: Enterprise Edition - Extreme Performance

DBOrch execution ended.

Get Patch Information

For this action you need your cloud SSH key and the host, IP does also work if the host name is not resolved by DNS, /etc/hosts etc.

oracle@solothurn:/u00/app/oracle/tools/dbcs-cli/ [rdbms12102] ./oracle-dbcs-cli patch list -key ssh/cloudtrialprivatekey.openssh -host cloud01
Database Cloud Orchestration Tool:Release 2.0.289.15.52 on Thu Feb 18 09:54:08 CET 2016
Copyright ©2014,2015, Oracle. All rights reserved.

{
"last_async_precheck_txn_id": " ",
"last_async_apply_txn_id": " ",
"err": "",
"errmsg": "",
"current_version": "12.1.0.2.5",
"last_async_precheck_patch_id": "",
"current_patch": "",
"last_async_apply_patch_id": "",
"patches": [
{
"patchid": "21948354-EE",
"last_precheck_txnid": "",
"description": "DB 12.1.0.2.160119 Jan 2016 PSU Enterprise Edition image"
}
]
}
DBOrch execution ended.

Creating a new Instance

It is very easy to create a new instance, but here you need the full content from the configuration template. I have created my own template called cloud10.dat to create an instance with shape OC3 and no backup, a new ssh key will be created and uploaded by the ORACLE-DBCS-CLI. I have specified these parameters, all other I let them on default values:

sm_url Endpoint URL – Attention: for EMEA it’s https://dbcs.emea.oraclecloud.com/paas/service/dbcs/api/v1.1/instances and not https://dbaas.oraclecloud.com/paas/service/dbcs/api/v1.1/instances as written in the documentation
user_name Your cloud.oracle.com user name
password Your cloud.oracle.com password
identity domain Your identity domain – e.g. trivadis4703
vm_name Your new instance name – e.g. CLOUD10
vm_shape Your shape – e.g. OC3
db_sid Your SID – e.g. cloud10
db_dbname Your DB name – e.g. cloud10
db_passwd Your SYS password – it have to contain a numer, a # or a _ character
db_bkup_disk Backup = No

 

Executing ORACLE-DBCS-CLI with my Configuration File cloud04.dat

Unfortunately there is no logfile available, but If you have set a wrong shape or a too simple password, you will get an error.

oracle@solothurn:/u00/app/oracle/tools/dbcs-cli/ [rdbms12102] ./oracle-dbcs-cli create -dat cloud04.dat
Database Cloud Orchestration Tool:Release 2.0.289.15.52 on Thu Feb 18 10:13:14 CET 2016
Copyright ©2014,2015, Oracle. All rights reserved.

Creating VM
.
sshkey generated
Created public sshkey file CLOUD04_public
Created private sshkey file CLOUD04_private
Done...
DBOrch execution ended.

That’s all folks – in cloud.oracle.com you can see now that your instance will be created immediately.

cloud04

My Template cloud04.dat

##############################################################
## Copyright(c) Oracle Corporation 1998,2015. All rights reserved.##
## ##
## Specify values for the variables listed below to customize ##
## your DB Orchestation ##
## ##
####################################################################

#-------------------------------------------------------------------------------
# Specify the SM related info
#-------------------------------------------------------------------------------
sm_url= https://dbcs.emea.oraclecloud.com/paas/service/dbcs/api/v1.1/instances
user_name= <YOUR_USERNAME_HERE>
password= <YOUR_PASSWORD_HERE>
identity_domain= trivadis4703
subscriptionType= monthly

#-------------------------------------------------------------------------------
# Specify the VM related info
#-------------------------------------------------------------------------------
vm_name=CLOUD04 # ex : dbinst
vm_shape=oc3 # ex : oc2

# if no seclist then one is created with name sl_<vm-name>, if there is seclist name
# and it does not exist then the given seclist name will be used instead of sl_<vm-name>
# dbsecrules are applied to the created seclist only
vm_seclist=

# specify the list of appcations, port and the source IP and port to be configured
# There are two pre-defined IP Lists named "site" and "public".
# most common DBaaS ports are being configured by default
# the syntax is <source-ip>:<app-name>:<port>
vm_dbsecrules=public:ssh:22:enabled, public:listener:1521:disabled, public:gfish:80:disabled, public:dbconsole:1158:enabled, public:dbexpress:5500:enabled

vm_nat= # nat ip pool, ex : /oracle/public/ippool
vm_ha="monitor" # ha policy, active/monitor
vm_boot=nds # leave blank for ephemeral
vm_boot_size=21gb # size of boot volume, only used when vm_voot=nds

# sshkeys that you have uploaded or want to upload to OPC ex : /OPCDBaaS/<userid>/sshkey
# multiple sshkeys can be given with "," separator. Also, if you have sshkey generated already,
# provide the public key to be uploaded with full path eg:/home/oracle/.ssh/sshkey.pub
#vm_sshkeys="/u00/app/oracle/tools/dbcs-cli/ssh/cloudtrialprivatekey.pub"

#-------------------------------------------------------------------------------
# Specify the DB related info
#-------------------------------------------------------------------------------
db_version=12102 # db version
db_edition=enterprise # valid values are standard/enterprise
db_bundle="basic" # valid only for enterprise, basic and high-perf
db_lvm=yes # Use LVM <yes/no>.
db_timezone=UTC # set the time zone.

## volumes for DB
# bits is to store the oracle home, data is for oradata and
# fra for flashback, arch logs, rman disk backup
# optionally a separate vol for redo logs
db_vols=(bits:30gb data:25gb fra:10gb redo:10gb)

db_redo_log_size=1024M # size of each redo log. 3 logs are created
db_sid=cloud04 # sid for db and cdb
db_dbname=cloud04 # Must be the same as db_sid
db_passwd=Cloud04#sys # password for sys/system/pdb
db_automem=yes # automatic memory management

db_cdb=yes # cdb mode
db_pdb_name=pdb1 # sid of the pdb
db_em=yes # whether to config em dbexpress / dbconsole

db_gfish=yes # configure glassfish

db_archlog=yes # enabled archivelogs. if bkup enabled, archivelogs is yes
db_flashback=yes # configure flashback
db_flashback_days="1" # flashback retention period

# incremental backup related
db_bkup_disk=no # backup to disk i.e fra. valid values yes/no
db_bkup_cron_entry=yes # enable or disable the crontab entry
db_bkup_daily_time=01:01 # HH:MM time to kick off the backup everyday(incremental)
db_bkup_disk_recovery_window=7 # recovery time period on disk, suggested value 7
db_bkup_oss=no # backup to OSS, give "yes" for backups to OSS
db_bkup_oss_url= # oss end point url including tenant id and service name
# ex : http://uclmp0024.us.oracle.com:7777/v1/dbaas01_StorageService88
db_bkup_oss_user= # oss user
db_bkup_oss_passwd= # oss user password
db_bkup_oss_recovery_window=30 # recovery time period on oss, the max is 30 days
db_bkup_cfg_files=yes # to enable backup of config files. yes/no
db_bkup_cfg_recovery_window= # recovery time period for cfg files, same as nds if blank

# PDBSS configuration
db_pdbss=yes # Configure PDBSS <yes|no>. If db_pdbss=yes also set db_gfish=yes.

# TDE encryption parameters
db_tde_ks_login=auto # TDE keystore login <manual|local|auto>

# User defined dborch provisioning parameters
db_net_security_enable=no # See section "Advanced network security"

# Advanced network security
#
# Set to yes to enable network encryption
db_net_security_encryption_enable=yes
# Configure encryption for: client or server
db_net_security_encryption_target=server
# Actions of host when negotiationg encryption:
# accepted, requested,rejected, or required
db_net_security_encryption_type=required
# Select one or more; separate them with comas and no spaces. The methods in the
# client will be matched with the server in given order:
# AES256,AES192, and/or AES128

Summary

The ORACLE-DBCS-CLI Utility is a great tool to manage the lifecycle of your Oracle cloud instances in th CLI. With a small set of templates and configuration files, you are able to manage your cloud instances without any browser.