10 Using the ExaCLI Utility
The ExaCLI utility enables you to manage database and cell nodes remotely.
- ExaCLI Command Reference
ExaCLI is a command-line administration tool that runs on database and cell nodes and enables you to manage nodes remotely. - ExaCLI Security
The authentication process is performed for every ExaCLI session. - Creating Users for Use with ExaCLI
To use ExaCLI, users must be created on the remote node, and the users must be assigned roles that have privileges appropriate for the user. - Differences in Commands Between ExaCLI and DBMCLI/CellCLI
- Certificates for ExaCLI
Security certificates allow the remote nodes to confirm their identity to ExaCLI. - Running Commands Remotely Using REST
In addition to running commands on a remote node throughexacli
, you can also run them using a URL to access a REST endpoint.
10.1 ExaCLI Command Reference
Overview
You can use ExaCLI to manage cell and database node configuration and objects in the remote node's environment. ExaCLI is installed when a cell or database node is imaged. ExaCLI supports the same command syntax as DBMCLI and CellCLI. The main difference is that ExaCLI manages cell and database nodes from a remote host whereas DBMCLI runs directly on a database node, and CellCLI runs directly on a cell node.
There are two main reasons to use ExaCLI:
-
Many companies, especially government organizations, require root access or the SSH service on the cell and database nodes to be disabled as part of the compliance requirements.
-
Service providers that host Exadata machines provide access to a virtual machine running on the cell and database node. Customers are not allowed to SSH into the cell or database node to manage the node using CellCLI or DBMCLI.
For such cases, the only way to manage the cell or database node is by using ExaCLI running on a remote node.
Prerequisites
-
Users created on the cell or database node that have been granted the necessary privileges. See Creating Users for Use with ExaCLI for more information.
-
Java version 1.8 or later
You can determine the version of Java by running the
java -version
command. In addition, theJAVA_HOME
environment variable must be set to point to the installation directory of the proper version of Java.
File Path
/usr/local/sbin/exacli
Syntax
You run ExaCLI from the operating system command line.
exacli -c [username@]remotehost[:port] [-l username] [ --xml | --json ]
[--cookie-jar [filename]] [-e {command | 'command[; command]' | @batchfile}]
Options
Option | Description |
---|---|
|
Specifies the remote node to which you want to connect. ExaCLI prompts for the user name if not specified. ExaCLI can connect to both cells and compute nodes. The default port for compute node MS is 7879. You can specify the remote host using an IPv6 address. The IPv6 addresses must be enclosed in square brackets and single quotes as shown in Example 10-2. |
|
Specifies the user name to log into the remote node. |
|
Displays output in XML format. |
|
Displays output in JSON format. |
|
Specifies the filename of the cookie jar to use. If filename is not specified, the cookie is stored in a default cookie jar located at The presence of a valid cookie allows the ExaCLI user to run commands without requiring to login in subsequent ExaCLI sessions. |
|
Specifies either the ExaCLI commands to run or a batch file. ExaCLI exits after running the commands. If specifying multiple commands to run, enclose the commands in single quotes to prevent the shell from interpreting the semi-colon. Omit this option to start an interactive ExaCLI session. |
|
Specifies the proxy server to use when downloading certificates. If |
|
Suppresses prompting for user input. |
Usage Notes
-
Notes for the
--cookie-jar
option:-
The user name and password are sent to the remote node for authentication. On successful authentication, the remote node issues a cookie (the login credentials) that is stored in the specified
filename
on the database node. Iffilename
is not specified, the cookie is stored in a default cookie jar located atHOME/.exacli/cookiejar
, where HOME is the home directory of the operating system user running the ExaCLI command. -
Permissions for the cookie jar file are set to
rw- --- ---
(600). -
The operating system user running the ExaCLI command is the owner of the cookie-jar file.
-
A cookie jar can contain multiple cookies from multiple users on multiple nodes in parallel sessions.
-
If the cookie is not found or is no longer valid, ExaCLI prompts for the password. The new cookie is stored in the cookie jar identified by filename, or the default cookie jar if filename is not specified.
-
Even without the
--cookie-jar
option, ExaCLI still checks for cookies from the default cookie jar. However, if the cookie does not exist or is no longer valid, the new cookie will not be stored in the default cookie jar if the--cookie-jar
option is not specified.
-
-
Notes for the
-e
option:-
ExaCLI exits after running the commands.
-
If specifying multiple commands to run, be sure to enclose the commands in single quotes to prevent the shell from interpreting the semi-colon.
-
The batch file is a text file that contains one or more ExaCLI commands to run.
-
-
Notes for the
-n (--no-prompt)
option:-
If ExaCLI needs additional information from the user, for example, if ExaCLI needs to prompt the user for a password (possibly because there were no valid cookies in the cookie-jar) or to prompt the user to confirm the remote node’s identity, then ExaCLI prints an error message and exits.
-
Examples
The following examples show how use ExaCLI after the users have been created and granted the necessary privileges. See Creating Users for Use with ExaCLI for examples of creating users and assigning privileges to them.
Example 10-1 Connecting to a User on a Cell using ExaCLI
Connect to cell node cellnode01
as the celladministrator
user. ExaCLI prompts for a password if the default cookie jar does not contain a valid cookie for the celladministrator
user. Because the --cookie-jar
option is not specified, the cookie is not stored in the cookie jar.
$ exacli -l celladministrator -c cellnode01
The following command is equivalent.
$ exacli -c celladministrator@cellnode01
Example 10-2 Connecting to a Remote Host Using an IPv6 Address
You can specify the remote host using an IPv6 address. The IPv6 addresses must be enclosed in square brackets and single quotes.
$ exacli -c 'scott@[2001:db8:a0b:12f0::1]'
$ exacli -c '[2001:db8:a0b:12f0::1]' -l scott
Example 10-3 Creating a Cookie for ExaCLI Connections
The user celladministrator
and password are sent to
cellnode01
for authentication. On successful authentication, the cell node
sends back a cookie which is stored in the default cookie jar. The specified commands are then
run on the cell node. Note that
Tip:
Multiple commands must be enclosed in single quotes.$ exacli -l celladministrator -c cellnode01 --cookie-jar -e 'list cell; list celldisk'
Password=************
Example 10-4 Creating a Cookie for ExaCLI Connections
The user celladministrator
and password are sent to
cellnode01
for authentication. On successful authentication, the cell node
sends back a cookie which is stored in the default cookie jar. The specified commands are then
run on the cell node.
Tip:
Multiple commands must be enclosed in single quotes.$ exacli -l celladministrator -c cellnode01 --cookie-jar -e 'list cell; list celldisk'
Password=************
Example 10-5 Using a Cookie when Ruunning ExaCLI Commands
After creating a cookie, as shown in the previous example, ExaCLI does not prompt for password for subsequent ExaCLI sessions for the celladministrator
user because it uses the cookie from the default cookie jar.
$ exacli -l celladministrator -c cellnode01 -e list griddisk detail
If you connect as a user other than celladministrator
, and a cookie
does not exist for that user, you are prompted for a password.
$ exacli -c user1@cellnode01 -e list griddisk detail
Password=************
Example 10-6 Viewing DBSERVER Details using ExaCLI
In this example, ExaCLI connects to the dbnode01
node as the dbnodeadministrator
user and lists the DBSERVER object attributes in detail.
$ exacli -l dbnodeadministrator -c dbnode01 --cookie-jar -e list dbserver detail
The login and password are sent to the database node for authentication. On successful authentication, the database node returns a cookie with the login credentials which gets stored in the cookie jar on the machine running ExaCLI
Example 10-7 Viewing the ALERTHISTORY for a DBSERVER using ExaCLI
In this example, ExaCLI connects to the dbnode01
node as the dbnodeadministrator
user and lists the ALERTHISTORY object. ExaCLI does not prompt for password if there is a valid cookie in the default cookie jar.
$ exacli -c dbnodeadministrator@dbnode01 -e list alerthistory
Example 10-8 Using a Command Batch File with ExaCLI
In this example, the file commandFile
is stored in the local directory (from where the ExaCLI command is called) and contains the following information:
list dbserver detail
list alerthistory
ExaCLI connects as the dbnodeadministrator
user to the dbnode01
database node, and, on successful authentication, runs the commands in commandFile
.
$ exacli -l dbnodeadministrator -c dbnode01 -e @commandFile
Parent topic: Using the ExaCLI Utility
10.2 ExaCLI Security
The authentication process is performed for every ExaCLI session.
Because ExaCLI runs DBMCLI and CellCLI commands on a remote node, user access must be authenticated before the commands can run. ExaCLI connects to an Oracle Exadata System Software user on the remote node that has been granted the necessary privileges to run the specified commands.
The presence of a valid cookie allows the ExaCLI user to run commands without requiring to log in for each session. A cookie is a token that contains the login credentials issued by the remote node and stored on the host machine running ExaCLI. A repository of cookies is called a cookie jar.
The same cookie jar can be used by multiple simultaneous ExaCLI sessions connecting to multiple remote nodes, even when they are using different login names. For example, exadcli
connects to multiple remote nodes using multiple ExaCLI sessions, but they all use the same cookie jar.
The cookie jar is configured with read and write permissions for the operating system user. The file is not readable, writable, or executable for anyone else.
Parent topic: Using the ExaCLI Utility
10.3 Creating Users for Use with ExaCLI
To use ExaCLI, users must be created on the remote node, and the users must be assigned roles that have privileges appropriate for the user.
Example 10-9 Create and Configure a User With All Privileges for Use with ExaCLI
Create the users and roles on the remote node using DBMCLI (for database nodes) or CellCLI (for cell nodes). These are the users that are allowed to connect to the remote node using ExaCLI. You use roles to assign privileges to users.
-
Database node example:
The following example creates an
administrator
role and grants all privileges to that role. It then creates a user calleddbadministrator
and grants theadministrator
role to that user.DBMCLI> CREATE ROLE administrator DBMCLI> GRANT PRIVILEGE ALL ACTIONS ON ALL OBJECTS ALL ATTRIBUTES - WITH ALL OPTIONS TO ROLE administrator DBMCLI> CREATE USER dbnodeadministrator password=* DBMCLI> GRANT ROLE administrator TO USER dbnodeadministrator
-
Cell node example:
This following example creates an
administrator
role and grants all privileges to that role. It then creates a user calledcelladministrator
and grants theadministrator
role to that user:CellCLI> CREATE ROLE administrator CellCLI> GRANT PRIVILEGE ALL ACTIONS ON ALL OBJECTS ALL ATTRIBUTES - WITH ALL OPTIONS TO ROLE administrator CellCLI> CREATE USER celladministrator password=* CellCLI> GRANT ROLE administrator TO USER celladministrator
Example 10-10 Creating a Cell Node User for Cell Monitoring with ExaCLI
This example creates a user called cellmon
who has privileges to only view object details.
CellCLI> CREATE ROLE monitor
CellCLI> GRANT PRIVILEGE list ON ALL OBJECTS ALL ATTRIBUTES -
WITH ALL OPTIONS TO ROLE monitor
CellCLI> CREATE USER cellmon password=*
CellCLI> GRANT ROLE monitor TO USER cellmon
Example 10-11 Creating a Database Node User for Node Monitoring with ExaCLI
This example creates a user called dbnodemon
that has privileges to view object details.
DBMCLI> CREATE ROLE monitor
DBMCLI> GRANT PRIVILEGE list ON ALL OBJECTS ALL ATTRIBUTES -
WITH ALL OPTIONS TO ROLE monitor
DBMCLI> CREATE USER dbnodemon password=*
DBMCLI> GRANT ROLE monitor TO USER dbnodemon
Related Topics
Parent topic: Using the ExaCLI Utility
10.4 Differences in Commands Between ExaCLI and DBMCLI/CellCLI
ExaCli supports the exact same command syntax as DBMCLI and CellCLI.
Not all CellCLI commands can be run through ExaCLI. The following commands are not supported on ExaCLI:
-
Restarting cell services (the
restart
option in theALTER CELL
command) -
Starting cell services (the
startup
option in theALTER CELL
command) -
Shutting down cell services (the
shutdown
option in theALTER CELL
command) -
User management commands (
CREATE USER
,ALTER USER
,DROP USER
) -
Role management commands (
CREATE ROLE
,DROP ROLE
,GRANT ROLE
,REVOKE ROLE
) -
Privilege management commands (
GRANT PRIVILEGE
,REVOKE PRIVILEGE
) -
CALIBRATE
-
DESCRIBE
-
HELP
-
Getting the following cell attributes:
rsStatus
,cellsrvStatus
,msStatus
using theLIST CELL
command -
SET
-
SPOOL
-
START
Parent topic: Using the ExaCLI Utility
10.5 Certificates for ExaCLI
Security certificates allow the remote nodes to confirm their identity to ExaCLI.
All communication between ExaCLI and Management Server (MS) running on the remote node is over HTTPS. Management Server is deployed with a default self-signed security certificate for HTTPS access. Optionally, you can upload a different security certificate issued by a Certificate Authority (CA).
Trusted CA Certificates can be listed by running the following command on the machine where ExaCLI is run:
$JAVA_HOME/bin/keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass password
- Using the Default Self-Signed Certificate
A security certificate must be signed by a trusted certificate authority (CA) for ExaCLI to accept it without a warning. - Using a CA-Certified Security Certificate
The Oracle Exadata Database Machine administrator can supply CA-certified security certificates, if they are needed for your environment.
Parent topic: Using the ExaCLI Utility
10.5.1 Using the Default Self-Signed Certificate
A security certificate must be signed by a trusted certificate authority (CA) for ExaCLI to accept it without a warning.
When ExaCLI connects to a remote node that does not have a security certificate signed by a trusted CA, a warning message is generated requesting the user to verify the certificate. When verified, ExaCLI remembers the security certificate and the users are not prompted to verify the certificate again for subsequent commands. Every cell and compute node is automatically configured with a self-signed certificate during install or Management Server (MS) deployment.
Note:
If you are using Oracle Exadata System Software release 19.3 or later, then enter y or n followed by pressing Enter when prompted.Example of accepting the self-signed security certificate (non-CA certificate):
$ exacli -l celladministrator --cookie-jar -c cellnode01
This connection is unsecure. You have asked ExaCLI to connect to cell cellnode01 securely.
The identity of cellnode01 cannot be verified.
Got certificate from server:
CN=cellnode01,OU=Oracle Exadata,O=Oracle Corporation,L=Redwood City,ST=California,C=US
Do you want to accept and store this certificate? (Press y/n)
y
Example of accepting the self-signed security certificate (non-CA certificate) for a database node:
$ exacli -l dbadministrator --cookie-jar -c dbnode01
This connection is unsecure. You have asked ExaCLI to connect to dbserver dbnode01 securely.
The identity of dbnode01 cannot be verified.
Got certificate from server:
CN=dbnode01,OU=Oracle Exadata,O=Oracle Corporation,L=Redwood City,ST=California,C=US
Do you want to accept and store this certificate? (Press y/n)
y
Parent topic: Certificates for ExaCLI
10.5.2 Using a CA-Certified Security Certificate
The Oracle Exadata Database Machine administrator can supply CA-certified security certificates, if they are needed for your environment.
ExaCLI accepts valid CA-Certified security certificates without any prompts and without requiring you to accept the certificates. Each certificate consists of a key pair, which includes a public key and matching private key.
Parent topic: Certificates for ExaCLI
10.6 Running Commands Remotely Using REST
In addition to running commands on a remote node through
exacli
, you can also run them using a URL to access a REST
endpoint.
Before using a URL to run commands on the remote node, you must create users, roles, and privileges, as described in Creating Users for Use with ExaCLI.
The format of the URL to run a command is:
https://remotenode:port/MS/RESTService/?cmd=command_to_run
If the remote node is a cell node, the port is 443. If the remote node is a database node, the port is 7879.
By default, the command results are formatted using plain text. To format
the results using XML, append &xml=true
to the URL. To format
the results using JSON, use &json=true
. For example:
https://remotenode:port/MS/RESTService/?cmd=command_to_run&json=true
When you submit the URL in a browser, the browser displays a warning about the certificate. If the warning is about a new certificate, the warning is usually acceptable. If the warning is about a changed certificate, you should make sure that the certificate is acceptable.
The browser then prompts for the user name and password. If you do not enter the correct password 5 times in succession, then the account is locked. You have to wait 30 minutes until you can try to log in again to the same account.
If you submit further requests in the same session, the browser will not display warnings about the certificate and will not prompt for user name and password, unless the session cookie has expired.
The following example runs the list dbserver detail
command:
https://dbnode:7879/MS/RESTService/?cmd=list+dbserver+detail
The following example runs the list cell detail
command:
https://cellnode:443/MS/RESTService/?cmd=list+cell+detail
You can also specify the URL in a RESTful format. For example:
https://cellnode:443/MS/RESTService/celldisk/list?where=size>1g
You can also run the URL using curl
. The steps are:
-
Download and store the server certificate.
( openssl s_client -showcerts -connect remote_node:port < /dev/null | openssl x509 -outform PEM > mycertfile.pem ) >& /dev/null
You need to do this only once.
curl
will not proceed unless you provide a valid certificate. -
Provide a user name and password.
curl -u username:password -c cookiejar --cacert mycertfile.pem 'https://remote_node:port /MS/RESTService/login'
-
Run the command.
Database node example:
curl -b cookiejar --cacert mycertfile.pem 'https://remote_node:port/MS/RESTService/?cmd=list+dbserver+detail'
Cell node example:
curl -b cookiejar --cacert mycertfile.pem 'https://remote_node:port/MS/RESTService/?cmd=list+cell+detail'
Parent topic: Using the ExaCLI Utility