enterprise manager: write powerful scripts with emcli
TRANSCRIPT
ENTERPRISE MANAGER: WRITE POWERFUL SCRIPTS WITH EMCLI
GOKHAN ATIL
INTRODUCTION
GOKHAN ATIL
▸ DBA Team Lead with 15+ years of experience
▸ Oracle ACE (since 2011)
▸ 10g/11g and R12 OCP
▸ Founding Member and Vice President of TROUG
▸ Co-author of Expert Oracle Enterprise Manager 12c
▸ Blogger (since 2008) gokhanatil.com
▸ Twitter: @gokhanatil
2
INTRODUCTION
AGENDA
▸ Introduction to EM CLI
▸ EM CLI Verbs
▸ Sample Verbs
▸ Fundamentals of Python
▸ EM CLI and Python
▸ Sample Scripts
▸ Summary
3
INTRODUCTION TO EM CLI
4
INTRODUCTION TO EM CLI
WHAT IS EM CLI?
EMCLI is an alternative for the web interface. It enables you to access OEM functionality from a text-based console.
Repository
EM CLI
Agent
OMS
Web Console
5
INTRODUCTION TO EM CLI
ALREADY INSTALLED
EM CLI is already installed and configured on OMS server:
cd $MIDDLEWARE_HOME/bin
./emcli (or emcli.bat on Windows servers)
6
INTRODUCTION TO EM CLI
YOU CAN INSTALL EM CLI TO YOUR PC
▸ Requires Java version 1.7.0_80 or greater
▸ Supported Operating Systems: Windows, Linux, Solaris, HPUX, Tru64, AIX
▸ Go to “command line interface” page under “setup” page to download the installation JAR file.
▸ Login is not required to download, so it’s possible to download the JAR file with “wget”.
To run EM CLI on Java 1.8 or higher, you need apply patch 17555224 to the weblogic server. Use"-no-check-certificate" parameter with wget.
7
INTRODUCTION TO EM CLI
EM CLI DOWNLOAD PAGE
8
INTRODUCTION TO EM CLI
EM CLI STANDARD KIT VS ADVANCED KIT
There are two different installation kits for EM CLI:
▸ EM CLI Standard Kit: This kit supports only the Standard (command line) mode.
▸ EM CLI with Scripting mode (option): This “advanced” kit supports Interactive and Script modes in addition to standard mode.
9
INTRODUCTION TO EM CLI
3 MODES OF EM CLI:
▸ Standard mode: This mode provides a simple command-line interface to Enterprise Manager, and supports the execution of one verb at a time from the command line.
emcli get_targets
▸ Interactive mode: This mode enables you to create a single interactive session with OMS. It is a Jython shell.
emcli
▸ Scripting mode: In Scripting mode, EM CLI runs Jython scripts containing EM CLI verbs.
emcli @scriptname.py
10
INTRODUCTION TO EM CLI
SOMEONE SAID JYTHON?
Jython is an implementation of the Python programming language designed to run on the Java platform.
11
INTRODUCTION TO EM CLI
SO WHAT’S PYTHON?
▸ Widely used general-purpose, high-level programming language
▸ Supports multiple programming paradigms, including OOP, imperative and functional programming
▸ Dynamic type system and automatic memory management
▸ Batteries Included (!)
12
INTRODUCTION TO EM CLI
INSTALL AND CONFIGURE:
▸ After you download, set JAVA_HOME and install the JAR file:
java -jar emcliadvancedkit.jar -install_dir=<home>
▸ Configure EM CLI:
emcli help setup
emcli setup -url="https://host:port/em" -username=<emuser> -dir=<instancedir> -trustall
13
EM CLI VERBS
14
EM CLI VERBS
400+ VERBS IN 75+ CATEGORIES
▸ Add Host Verbs
▸ Agent Administration Verbs
▸ Agent Upgrade Verbs
▸ BI Publisher Reports Verbs
▸ Blackout Verbs
▸ Credential Verbs
▸ Incident Rules Verbs
▸ Job Verbs
▸ Metric Extension Verbs
▸ Monitoring Templates Verbs
▸ Oracle Cloud Verbs
▸ Provisioning Verbs
▸ Self Update Verbs
▸ User Administration Verbs
15
EM CLI VERBS
GET QUICK HELP
You can get the list of available verbs using “help”:
emcli help
emcli help get_targets
16
EM CLI VERBS
EM CLI VERBS IN STANDARD MODE
In standard mode, EM CLI expect you enter a verb as the first parameter. Verbs may take zero or more arguments as input.
emcli verb -1st_argument="value" [ -2nd_ argument="value" ] [ -3rd_ argument="value" ] [ -4th_ argument ]…
17
EM CLI VERBS
EM CLI VERBS IN SCRIPTING MODE
▸ Verbs are defined as Python functions
▸ Arguments are entered as function parameters
verb( argument_name="value", 2nd_ argument="value")
▸ Results of verbs are formatted as JSON
18
SAMPLE VERBS
LOGIN
Login verb is used to log into Enterprise Manager with the given credentials.
login( username="SYSMAN", password="123456", force=true)
login( username="SYSMAN", password="123456" )
login( username=“SYSMAN" )
The EM CLI client should be logged in to OMS before other EM CLI verbs are executed.
19
SAMPLE VERBS
GET_TARGETS
get_targets verb lists the targets (their names and their types) which are discovered or monitored by Enterprise Manager.
get_targets()
get_targets( targets="targetname:targettype" )
get_targets( targets="targetname:%" )
get_targets( targets="targettype" )
get_targets( "unmanaged", targets="targettype" )
Target names, target types and even “verbs” are case sensitive, so be sure that you use the exact name of a target and target type!
20
SAMPLE VERBS
ADD_TARGET
add_target verb adds a target to Enterprise Manager.
add_target( name="TESTDB", type="oracle_database", host="testdb.gokhanatil.com", credentials="...", properties="..." )
You must specify any required properties of a target type when adding a new target of this type
21
SAMPLE VERBS
CLEAR_STATELESS_ALERTS
clear_stateless_alerts verb clears the stateless alerts associated with the specified target. Stateless alerts are not cleared automatically by the Enterprise Manager.
clear_stateless_alerts( target_name="TESTDB", target_type="oracle_database", metric_internal_name="...", older_than="0" )
To find the metric internal name associated with a stateless alert, use the get_metrics_for_stateless_alerts verb.
22
SAMPLE VERBS
UPDATE_DB_PASSWORD
update_db_password verb updates the target database password stored in the Enterprise Manager Credential sub-system and can change the password on the target database as well.
update_db_password (target_name="TESTDB", user_name="DBSNMP", target_type="oracle_database", change_at_target="yes", old_password="oldone", new_password="newone", retype_new_password="newone" )
23
SAMPLE VERBS
LIST
▸ Although there are more than 85+ verbs to help you fetch a specific information from OMS such as list of targets, list of jobs etc, you may still need a more powerful verb which can fetch information from the repository database.
▸ This command will show all resources that you can query:
emcli list -help
24
SAMPLE VERBS
LIST
▸ The following command will list the users defined in EM:
emcli list -resource="Administrators"
▸ This command shows the columns of the specified resource:
emcli list -resource="Administrators" -help
25
SAMPLE VERBS
LIST
▸ This command will list the EM users and their last logins:
emcli list -resource="Administrators" -columns="USER_NAME,LAST_AUTHENTICATED_TS"
▸ The following command will list the EM users which are logged in at least one time:
emcli list -resource="Administrators" -columns="USER_NAME,LAST_AUTHENTICATED_TS" -search=“LAST_AUTHENTICATED_TS IS NOT NULL"
26
SAMPLE VERBS
LIST
Latest version of the “list” verb can query 30+ resources. If you can not find the data you need among these resources, you can even run SQL on repository database using list verb:
emcli list -sql="<query>"
You need ACCESS_EMCLI_SQL_LIST_VERB privilege to be able to run query using “the list verb”.
27
FUNDAMENTALS OF PYTHON
28
FUNDAMENTALS OF PYTHON
VARIABLES
Python supports dynamic type variables. You don’t need to declare a variable but you need to initialise it before you use:
▸ myvar = "TESTDB"
▸ myvar = myvar + ":oracle_database"
▸ myvar = 10
▸ myvar = myvar + 10
▸ myvar = 10 + "10"
TYPE ERROR: UNSUPPORTED OPERAND TYPE(S) FOR +: 'INT' AND 'STR'
29
FUNDAMENTALS OF PYTHON
CONVERSIONS
You can convert numbers to string using “str” function, and string variables to numbers using “int” function:
‣ myvar = int("2")
‣ myvar = int("5") + 10
‣ myvar = str(2)
‣ myvar = str(2) + "nd century"
30
FUNDAMENTALS OF PYTHON
CONDITIONAL STATEMENTS AND CODE BLOCKS
The indented block of code is executed if the condition is true. You should use indents to create code blocks.
myvar = int("2")myvar = myvar + 10myvar = "2"
if ( myvar >= 10 ): print "myvar is " + str(myvar)else: print "lower than 10" CODE BLOCKS ARE IDENTIFIED
BY “INDENTATION”
THE COLON (:) SIGN
31
FUNDAMENTALS OF PYTHON
DICTIONARY AND LIST OBJECTS
Dictionary objects, list objects and iterations:
mydict = { 'Name':'Gokhan', 'Age':40 }mydict['Name'] = "Gokhan"
mylist = ["Joe","William","Jack","Averell"] mylist[0] = "Joe"
for i in mylist: print i
SIMILAR TOJSON. KEY=VALUE
IT WILL PRINT ALL ELEMENTS IN “MYLIST”
ARRAY. USE INDEX TO REACH VALUE
32
EM CLI AND PYTHON
33
EM CLI AND PYTHON
EM CLI RESPONSE OBJECT
emcli.response represents the response object which returned from invocation of a emcli verb from python script.
emcli.response.Response
error() error textexit_code() error code (0=success)isJson() is JSON? true/falseout() JSON or text
34
EM CLI AND PYTHON
EM CLI RESPONSE OBJECT
In scripting mode, default output format type is JSON. In interactive mode, to change the output format to JSON, you need to run the following command:
set_client_property('EMCLI_OUTPUT_TYPE', 'JSON')
It’s recommended to use JSON format because it directly matches with Python “dictionary” object. There’s no need for extra effort to parse the output.
35
EM CLI AND PYTHON
EM CLI RESPONSE OBJECT
Let’s get the response from a verb:
mytargets = get_targets( target="oracle_database" )
type(mytargets.out()) <type 'dict'>
mytargets.out()
{'data': [{'Status': 'Up', 'Warning': '6', 'Status ID': '0', 'Target Type': 'oracle_database', 'Critical': '64', 'Target Name': 'TESTDB'}, {…}, {…}, {…}] }
36
EM CLI AND PYTHON
EM CLI RESPONSE OBJECT
A response always contain a “data” item which is a list object:
type(mytargets.out()['data']) <type ‘list'>
mytargets.out()['data']
[ {'Status': 'Up', 'Warning': '6', 'Status ID': '0', 'Target Type': 'oracle_database', 'Critical': '64', 'Target Name': 'TESTDB'},{…}, {…}, {…} ]
type(mytargets.out()['data'][0]) <type 'dict'>
37
EM CLI AND PYTHON
EM CLI RESPONSE OBJECT
We can iterate over the items of the list:
for DB in mytargets.out()['data']: print DB['Target Name'], DB['Status']
DICT / JSON
LIST (DATA)
DICT
DICT
DICT
DICT
DICT
38
SAMPLE SCRIPTS
39
SAMPLE SCRIPTS
CLEAR STATELESS ALERTS
Save the following code in a file (clearalerts.py) and run it as “emcli @clearalerts.py”:
if login( username="GOKHAN" ).exit_code()==0:
mytargets=get_targets( targets="oracle_database" )
for DB in mytargets.out()['data']: clear_stateless_alerts( target_name=DB['Target Name'], target_type=DB['Target Type'], older_than="0" )
40
SAMPLE SCRIPTS
CHANGE DBSNMP PASSWORDS
if len(sys.argv) <> 2: print "Usage: emcli @change_dbsnmp_passwords.py oldpwd newpwd" exit()if login( username="GOKHAN" ).exit_code()==0: mytargets=get_targets( targets="%_database" ) for DB in mytargets.out()['data']: try: update_db_password (target_name=DB['Target Name'], target_type=DB['Target Type'] , change_at_target="yes",user_name="dbsnmp", old_password=sys.argv[0], new_password=sys.argv[1], retype_new_password=sys.argv[1]) except emcli.exception.VerbExecutionError, e: print e.error()
41
SAMPLE SCRIPTS
PROMOTE UNMANAGED DATABASES
lg = login( username="SYSMAN" )
if lg.exit_code() <> 0: print lg.error() exit()
utargets=get_targets( "unmanaged", properties=True, targets="oracle_database" )
for target in utargets.out()['data']: add_target( name=target['Target Name'], type=target['Target Type'], host=target['Host Info'].split(';')[0].split(':')[1], credentials="UserName:dbsnmp;password:xyz;Role:Normal", properties=target['Properties'] )
POSITIONAL PARAMETERS
42
SUMMARY
43
SUMMARY
WHY NOT BASH SCRIPTING WITH EM CLI STANDARD KIT?
▸ BASH scripting supports environment variables, if conditions, loops
▸ Linux tools (grep, awk etc…) to parse output of EM CLI
▸ Python is cross-platform
▸ Python scripts are easy to be read and maintain
▸ Python scripts perform better
44
SUMMARY
FURTHER READING
▸ OEM 12c Command-Line Interface
▸ My blog:http://www.gokhanatil.com
▸ Kellyn Pot'Vin-Gormanhttp://dbakevlar.com
▸ Ray Smith https://oramanageability.wordpress.com
▸ Seth Miller http://sethmiller.org
▸ The Definitive Guide to Jythonhttp://www.jython.org/jythonbook/en/1.0/
45
THANK YOU FOR ATTENDING! ANY QUESTIONS?
46