NuoDB Command

NuoDB Command (nuocmd) is a command-line tool that enables users to control and inspect the state of a NuoDB domain.

Most of the functionality exposed by nuocmd is made available by Admin Processes (APs) via the REST API.

Usage

nuocmd has several subcommands of the form:

nuocmd <verb> <noun>

The verb can be one of several actions, such as add, remove, get, and show, and the noun is some object that the subcommand is operating on.

The list of available verbs can be obtained by invoking nuocmd -h, and the list of available nouns for a particular verb can be obtained by invoking nuocmd <verb> -h. The list of arguments for a particular subcommand and their meaning can be obtained by invoking nuocmd <verb> <nuon> -h.

Enabling Autocompletion

To facilitate easy interactive use of nuocmd, autocompletion can be enabled.

Autocompletion is only available when using the Bash shell.

Autocompletion is enabled by sourcing the nuocmd-complete script included in the NuoDB distribution and also included in the NuoDB Client Package. If using the RPM package, autocompletion can be enabled for the current Bash session as follows:

. /opt/nuodb/etc/nuocmd-complete

Verifying Autocompletion

After enabling the autocompletion, available global arguments and subcommand verbs are proposed as options by typing nuocmd and hitting the <TAB> key twice.

nuocmd <TAB> <TAB>
--api-server        --show-json-fields  create              hotcopy             shutdown
--basic-creds       --verify-server     delete              import              sign
--client-key        -h                  diagnose            log                 start
--help              add                 enforce             prepare             update
--no-verify         capture             generate            remove              upgrade
--show-http         check               get                 set
--show-json         connect             handoff             show

Further arguments will be proposed based on the context, i.e. what arguments have already been specified.

nuocmd can also propose arguments based on runtime configuration. For example, if nuocmd shutdown database --db-name <TAB> <TAB> is entered, the set of running databases is proposed.

NuoDB Command Conventions

Most nuocmd subcommand verbs have conventions associated with them that map predictably to the REST API exposed by APs. Some of these conventions are listed below:

  • nuocmd create and nuocmd delete subcommands create or delete objects in the NuoDB domain state, such as database and archive objects.

  • nuocmd add and nuocmd remove subcommands add or remove attributes from an existing object in the NuoDB domain state.

  • nuocmd get subcommands display the attributes of an object or a set of objects without formatting and can be used with the --show-json or --show-json-fields global arguments.

  • nuocmd show subcommands display the attributes of an object or a set of objects with formatting that can be customized using format strings.

Customizing the Output of Show Commands

By default, the nuocmd show subcommands display long listings that include information that may not be needed when reviewing basic domain and database status. However, it is possible to customize the output of these commands so that it displays in a summary format. To do this, set nuocmd output formatting variables as follows:

export NUOCMD_SERVER_FORMAT='[{id}] {address} ({role}, Leader={leader}) {raft_state}:{connected_state}'
export NUOCMD_DB_FORMAT='{name} [{state}]'
export NUOCMD_PROCESS_FORMAT='[{engine_type}] {address::<UNKNOWN ADDRESS>} [StartId = {start_id}] [ServerId = {server_id}] {durable_state}:{engine_state}'
export NUOCMD_ARCHIVE_FORMAT='Archive: [{id}] {server_id} : {archive_path} [db = {db_name}] {state}'
export NUOCMD_API_SERVER=localhost:8888

To revert to the detailed output, run the following commands (as required):

unset NUOCMD_SERVER_FORMAT
unset NUOCMD_DB_FORMAT
unset NUOCMD_PROCESS_FORMAT
unset NUOCMD_ARCHIVE_FORMAT
unset NUOCMD_API_SERVER

Using NuoDB Command When TLS is Enabled

When TLS has been configured, users must pass the client credentials (typically a TLS key and certificate, though password authentication is also available) and certificate needed to verify the Admin server. For example, when using NuoDB Command to display the NuoDB domain and database state: 
nuocmd --client-key <pem> --verify-server <cert> show domain

So that it is not necessary to pass the client key and server certificate with every nuocmd invocation, set the following environment variables:

export NUOCMD_CLIENT_KEY=/etc/nuodb/keys/nuocmd.pem
export NUOCMD_VERIFY_SERVER=/etc/nuodb/keys/ca.cert