1. Maintenance Guide
  2. Using the ExaCLI Utility

10 Using the ExaCLI Utility

The ExaCLI utility enables you to manage database and cell nodes remotely.

10.1 ExaCLI Command Reference

ExaCLI is a command-line administration tool that runs on database and cell nodes and enables you to manage nodes remotely.

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, the JAVA_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]
 [--cookie-jar [filename]] [-e {command | 'command[; command]' | @batchfile}]

Options

Option Description

-c [username@]remotehost or

--connect [username@]remotehost[:port]

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.

-l username or

--login-name username

Specifies the user name to log into the remote node.

--xml

Displays the output in XML format.

--cookie-jar [filename]

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 HOME/.exacli/cookiejar, where HOME is the home directory of the OS user running the ExaCLI command.

The presence of a valid cookie allows the ExaCLI user to run commands without requiring to login in subsequent ExaCLI sessions.

-e command or

-e 'command[; command]' or

-e @batchFile

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.

--cert-proxy proxy[:port]

Specifies the proxy server to use when downloading certificates. If port is omitted, port 80 is used by default.

-n or

--no-prompt

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. If filename is not specified, the cookie is stored in a default cookie jar located at HOME/.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.

    • Cookies are invalidated after 24 hours.

    • 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 cookie issued by the remote node is invalidated after 24 hours. 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.

  • Use DBMCLI or CellCLI on the remote node to create the users and roles, and grant privileges.

    Note:

    When creating a user on the cell or database node, the user password must be 8 to 40 alphanumeric characters or special characters (!@#$%^&*()-_) with at least one digit, one lowercase letter and one uppercase letter. The new password cannot be the same as the current password 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 called dbadministratorand grants the administrator 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 called celladministrator and grants the administrator 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 the ALTER CELL command)

  • Starting cell services (the startup option in the ALTER CELL command)

  • Shutting down cell services (the shutdown option in the ALTER 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 the LIST 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

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.

  1. Modify security attributes for the storage server or database server.

    To upload a CA-certified security certificate, modify the securityPubKey and the securityPrivKey attributes on the storage server or database server:

    • securityPubKey specifies a URL for the certificate public key file.

    • securityPrivKey specifies a URL for the certificate private key file.

    The keys must be supplied as PEM-encoded files. Each URL can use the http, https, or file access scheme.

    If the private key is encrypted, you can provide the password using the securityPrivKeyPW attribute.

    The following examples show commands for uploading a CA-certified security certificate:

    • Example for a storage server using http URLs to access the key files. In this example, the password prompt requests the password for the celladministrator user on cellhost. 

      $ exacli -l celladministrator -c cellhost  -
         -e 'alter cell securityPubKey="http://www.example.com/security/newkey1.pem.crt", -
             securityPrivKey="http://www.example.com/security/newkey1-private.pem", -
             securityPrivKeyPW="welcome1"'

Password: *********
...

    • Example for a database server using local file URLs to access the key files. In this example, the password prompt requests the password for the dbadministrator user on dbhost. 

      $ exacli -l dbadministrator -c dbhost  -
         -e 'alter dbserver securityPubKey="file:///root/security/newkey2.pem.crt", -
             securityPrivKey="file:///root/security/newkey2-private.pem", -
             securityPrivKeyPW="welcome2"'

Password: *********
...
  2. Restart the Management Server (MS) on the storage server or database server.

    After you upload the CA-certified security certificate individually to every server in the cluster, you must restart MS before the new security certificate is visible.

    For example:

    • Restart MS on a storage server. 

      CELLCLI> alter cell restart services ms

Restarting MS services... 
The RESTART of MS services was successful.

    • Restart MS on a database server. 

      DBMCLI> alter dbserver restart services ms

Restarting MS services... 
The RESTART of MS services was successful.

Parent topic: Certificates for ExaCLI

10.6 Running Commands Remotely Using URLs

In addition to running commands on a remote node through exacli, you can also run them through URLs.

Before using URLs to run commands on the remote node, you have to create users, roles, and privileges, as described in Creating Users for Use with ExaCLI.

The format of the URL 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.

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 login again to the same account.

The results of the command are returned in plain text.

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:

  1. 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.

  2. Provide a user name and password.

    curl -u username:password -c cookiejar --cacert mycertfile.pem 'https://remote_node:port /MS/RESTService/login'

  3. 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