CLI tutorial

StorPool provides an easy yet powerful Command Line Interface (CLI) for administrating the data storage cluster or multiple clusters in the same location (multi-cluster). It has an integrated help system that provides useful information on every step. There are various ways to execute commands in the CLI, depending on the style and needs of the administrator. The StorPool CLI gets its configuration from the /etc/storpool.conf file and command line options.

The current document provides an introduction to the CLI and a few useful examples. For more information, see the CLI reference document.

Using the standard shell

Type regular shell command with parameters:

# storpool service list

Pipe command output to StorPool CLI:

# echo "service list" | storpool

Redirect the standard input from a predefined file with commands:

# storpool < input_file

Display the available command line options:

# storpool --help

Using the interactive shell

To start the interactive StorPool shell:

# storpool
StorPool> service list

Interactive shell help can be invoked by pressing the question mark key (?):

# storpool
StorPool> attach <?>
  client - specify a client to attach the volume to {M}
  here - attach here {M}
  list - list the current attachments
  mode - specify the read/write mode {M}
  noWait - do not wait for the client {M}
  snapshot - specify a snapshot to attach {M}
  timeout - seconds to wait for the client to appear {M}
  volume - specify a volume to attach {M}

Shell autocomplete (invoked by double-pressing the Tab key) will show available options for current step:

StorPool> attach <tab> <tab>
client    here      list      mode      noWait    snapshot  timeout   volume

The StorPool shell can detect incomplete lines and suggest options:

# storpool
StorPool> attach <enter>
.................^
Error: incomplete command! Expected:
    volume - specify a volume to attach
    client - specify a client to attach the volume to
    list - list the current attachments
    here - attach here
    mode - specify the read/write mode
    snapshot - specify a snapshot to attach
    timeout - seconds to wait for the client to appear
    noWait - do not wait for the client

To exit the interactive shell use the quit or exit command, or directly use the Ctrl+C or Ctrl+D keyboard shortcuts of your terminal.

To set the string that would appear as a prompt for the interactive shell, use the SP_CLI_PROMPT option in the /etc/storpool.conf file. For details, see CLI prompt string.

Error messages

If the shell command is incomplete or wrong the system would display an error message, which would include the possible options:

# storpool attach
Error: incomplete command! Expected:
    list - list the current attachments
    timeout - seconds to wait for the client to appear
    volume - specify a volume to attach
    here - attach here
    noWait - do not wait for the client
    snapshot - specify a snapshot to attach
    mode - specify the read/write mode
    client - specify a client to attach the volume to

# storpool attach volume
Error: incomplete command! Expected:
  volume - the volume to attach

Multi-cluster mode

To enter multi-cluster mode (see Multi-site and multi-cluster) while in interactive mode:

StorPool> multiCluster on
[MC] StorPool>

For non-interactive mode, use:

# storpool -M <command>

Note

All commands not relevant to multi-cluster will silently fall-back to non-multi-cluster mode. For example, storpool -M service list will list only local services. Same for storpool -M disk list and storpool -M net list.