7 Using the ExaCLI Utility

This chapter describes the ExaCLI utility, which enables you to manage database and cell nodes remotely.

This chapter contains the following topics:

7.1 ExaCLI Overview

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

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.

The ExaCLI utility requires 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.

The following steps describe typical ExaCLI usage:

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

    Cell node example:

    The 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
    

    The following example creates a role with privileges to list the name and size attributes of grid disks, and grants that role to a user called user1.

    cellcli> create user user1
    password:************
    
    cellcli> create role role1
    Role role1 successfully created.
    
    cellcli> GRANT PRIVILEGE list ON griddisk ATTRIBUTES name,size WITH OPTIONS
     detail TO ROLE role1
    Privilege [object=griddisk, verb=list, attributes=name,size, options=detail]
    has been granted to role role1.
    
    cellcli> grant role role1 to user user1
    
    

    Database node example:

    The following example creates an administrator role and grants all privileges to that role. It then creates a user called dbnodeadministrator and 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
    

    The following example creates a role with privileges to list the name attribute of the database server, and grants that role to a user called user1.

    dbmcli> create user user1
    password:************
    
    dbmcli> create role role1
    Role role1 successfully created.
    
    dbmcli> GRANT PRIVILEGE list ON dbserver ATTRIBUTES name WITH OPTIONS
     detail TO ROLE role1
    Privilege [object=dbserver, verb=list, attributes=name, options=detail]
    has been granted to role role1.
    
    dbmcli> grant role role1 to user user1
    
    
  2. Run ExaCLI to connect to the remote node as the user created in the previous step, and execute commands on the remote node.

    Cell node example:

    In the following example, ExaCLI connects to the cellnode01 node as the celladministrator user and runs the list cell detail command.

    $ exacli -l celladministrator -c cellnode01 --cookie-jar -e list cell detail
    Password=*******
    

    The login and password are sent to the cell node for authentication. On successful authentication, the cell node returns a cookie with the login credentials which gets stored in the cookie jar on the machine running ExaCLI.

    If you run a subsequent command, ExaCLI does not prompt for a password because it uses the cookie stored in the cookie jar from the previous command.

    $ exacli -l celladministrator -c cellnode01 -e list griddisk detail
    

    Database node example:

    In the following example, ExaCLI connects to the dbnode01 node as the dbnodeadministrator user and runs the list dbserver detail command:

    $ exacli -l dbnodeadministrator -c dbnode01 --cookie-jar -e list dbserver detail
    Password=*******
    

    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.

    If you run a subsequent command, ExaCLI does not prompt for a password because it uses the cookie stored in the cookie jar from the previous command.

    $ exacli -l dbnodeadministrator -c dbnode01 -e list alerthistory detail
    

7.2 ExaCLI Syntax

You run ExaCLI from the operating system command line. The command line syntax is as follows:

exacli -c [username@]remotehost [-l username] [--xml] [--cookie-jar [filename]] [-e command]

Table 7-1 ExaCLI Options

Option Description
-c [username@]remotehost

--connect [username@]remotehost

Specifies the remote node to connect to. ExaCLI will prompt for the user name if omitted.

-l username

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

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 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 OS user running the exacli command.

The permissions for the cookie jar file are set to rw------- (that is, 600).

The OS 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.

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

If the cookie is not found or 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 no longer valid, the new cookie will not be stored in the default cookie jar if the --cookie-jar option is not specified.

-e command[; command] 

-e @batchFile 

Specifies either the ExaCLI command(s) to run or a batch file. ExaCLI exits after running the command(s). Omit this option to start an interactive ExaCLI session.

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.

--cert-proxy proxy[:port]

Specifies the proxy server to use when downloading certificates. If port is omitted, it defaults to port 80.

-n

--no-prompt

Suppresses prompting for user input. 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.

7.3 ExaCLI Examples

Cell Node Example 1: 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. The following commands are equivalent.

$ exacli -l celladministrator -c cellnode01

$ exacli -c celladministrator@cellnode01

Cell Node Example 2: 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 executed on the cell node. Note that multiple commands are enclosed in single quotes.

$ exacli -l celladministrator -c cellnode01 --cookie-jar -e 'list cell; list celldisk'
Password=************

Cell Node Example 3: 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

Cell Node Example 4: ExaCLI connects as the "celladministrator" user to the "cellnode01" node, and, on successful authentication, runs the commands in commandFile.

$ exacli -l celladministrator -c cellnode01 -e @commandFile

Database Node Example 1: Connect to database node "dbnode01" as the "dbnodeadministrator" user. ExaCLI prompts for a password if the default cookie jar does not contain a valid cookie for the "dbnodeadministrator" user. Because the --cookie-jar option is not specified, the cookie is not stored in the cookie jar. The following commands are equivalent.

$ exacli -l dbnodeadministrator -c dbnode01

$ exacli -c dbnodeadministrator@dbnode01

Database Node Example 2: The user "dbnodeadministrator" and password are sent to "dbnode01" for authentication. On successful authentication, the database node sends back a cookie which is stored in the default cookie jar. The specified commands are then executed on the database node. Note that multiple commands are enclosed in single quotes.

$ exacli -l dbnodeadministrator -c dbnode01 --cookie-jar -e 'list dbserver; list alerthistory'
Password=************

Database Node Example 3: ExaCLI does not prompt for password for subsequent ExaCLI sessions for the "dbnodeadministrator" user because it uses the cookie from the default cookie jar.

$ exacli -l dbnodeadministrator -c dbnode01 -e list alerthistory

Database Node Example 4: 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

7.4 Authentication

Because ExaCLI runs DBMCLI and CellCLI commands on a remote node, users must be authenticated before the commands can be executed. The authentication process is performed for every ExaCLI session.

The presence of a valid cookie allows the ExaCLI user to execute 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 OS user. The file is not readable, writable, or executable for anyone else.

7.5 User Management

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.

Creation of users and roles can only be performed directly on the remote node using DBMCLI or CellCLI.

Cell Node Example: The following example creates a user called celladministrator with all privileges.

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

Cell Node Example: The following example creates a user called cellmon who has privileges to 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

Database Node Example: The following example creates a user called dbnodeadministrator with all privileges.

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

Database Node Example: The following example creates a user called dbnodemon who 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

See Also:

For details on user and role management, see Oracle Exadata System Software User's Guide.

7.6 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 executed 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

7.7 Certificates

All communication between ExaCLI and Management Server (MS) running on the remote node is over https. Security certificates allow the remote nodes to confirm their identity to ExaCLI. 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 executing the following command on the machine where ExaCLI is run. The first $ below is the shell prompt.

$ $JAVA_HOME/bin/keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit

7.7.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 is automatically configured with a self-signed certificate during install or Management Server (MS) deployment.

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)

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)

7.7.2 Using a CA-Certified Security Certificate

The Oracle Exadata Database Machine administrator must 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.

  1. Modify security attributes for the cell or compute node.

    To upload the CA-certified security certificates, you modify the securityPubKey and the securityPrivKey attributes for a cell or compute node. securityPubKey and securityPrivKey form a key pair for secure communication.

    • The securityPubKey attribute specifies a URL that contains the public key.

    • The securityPrivKey attribute specifies a URL that contains the private key.

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

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

    Example for cell node:

    CellCLI> alter cell securityPubKey="http://www.acme.com/security/newkey.crt",  -
                       securityPrivKey="http://www.acme.com/security/newkey.key", -
                       securityPrivKeyPW=*
    
    password=****************
    

    Example for database node:

    DBMCLI> alter dbserver securityPubKey="http://www.acme.com/security/newkey.crt", -
                       securityPrivKey="http://www.acme.com/security/newkey.key", -
                       securityPrivKeyPW=*
    
    password=****************
    
  2. Restart the Management Server for the cell or compute nodes.

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

    Restart the Management Server on a cell.

    CELLCLI> alter cell restart services ms
    

    Restart the Management Server on a compute node.

    DBMCLI> alter dbserver restart services ms
    

7.8 Executing Commands Remotely Using URLs

In addition to executing commands on a remote node through exacli, you can also execute them through URLs. You still need to set up users, roles, and privileges, as described in “ExaCLI Overview”.

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 will then prompt for the user name and password.

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'