+ CLI Guide Overview

From OSNEXUS Online Documentation Site
Revision as of 12:18, 16 September 2022 by Qadmin (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The QuantaStor command line interface (CLI) can be used to remotely manage your QuantaStor based systems via a Windows or Linux system, and it is also a powerful tool for scripting the configuration and provisioning of storage volumes, network shares, and other resources. The command line utility for managing your QuantaStor system is called simply 'qs'. You can run 'qs' after logging into your QuantaStor system via an SSH connection, or you can download the QuantaStor Remote CLI client installer for Windows which is available for download from the OSNEXUS web site.

How to use the CLI

QuantaStor CLI is a full featured interface into all of the QuantaStor management features and can communicates with the local core management service as well as remote storage systems.



It is important to note that running the qs CLI locally as root affords no additional access privileges. Each command run via the CLI must include the --server specification which includes which server and what credentials should be used to access the system with. The QuantaStor CLI uses the same REST API calls that the QuantaStor Web User Interface (WUI) does. For this reason if you change the QuantaStor user "admin"'s default password, you will need to use one of the following authentication methods.

Authentication via --server Argument

All CLI commands accept the server specification argument which is of this form:


If you do not specify a username or password it will try to use the defaults which are 'admin' and 'password'.

Authentication via QS_SERVER Environment Variable

Rather than having to specify the --server argument over and over again you can set an environment variable once then it will use this as the default system IP address and credentials. The form of the variable is like so:

export QS_SERVER=ipaddress[,username,password]]


export QS_SERVER=localhost,admin,password
export QS_SERVER=,admin,mypass123
export QS_SERVER=myhostname.domain.net,mike,mypass123

Authentication via .qs.cnf Configuration File Using Password

Finally, rather than using an environment variable you can also create a file in your home directory called .qs.cnf with your credentials in it. Here's an example of how to create the file:

echo ",admin,password" > ~/.qs.cnf
chmod 600 ~/.qs.cnf

Authentication via .qs.cnf Configuration File Using Passwordless Token

IF a QuantaStor user is configured with "Enable '[QSCLITKN]' token based authentication for QS CLI via 'root' console account" then the users password will not have to be added to the .qs.cnf file as described above. This user option can be set in the WUI or via the command line. If the admin users default password has not been changed, then the following command will enable token based authentication at the command line:

qs user-modify --user=admin --cli-auth=true

If the admin users password has been changed, then the QuantaStor Web UI / Security tab / admin user / right mouse Modify User / Advanced Settings tab / Enable '[QSCLITKN]' token based authentication for QS CLI via 'root' console account can be checked to allow token based authentication.

Once the admin user has this option checked, the following must be done to allow the root user to execute "qs" CLI commands without a password.

echo "localhost,admin,[QSCLITKN]" > /root/.qs.cnf
chmod 600 ~/.qs.cnf

After that file is created a command such as "qs system-list" should work without error.


The general usage format for all CLI commands is as follows:

qs command <-mandatory-arg=val> [-optional-arg=val] [-flags=force,async,...] [-server=ipaddress[,username,password]] [-xml] [-min] 

As you read through the CLI documentation note that all arguments that are specified in angle backets <> are mandatory required arguments. Arguments in square brackets [] are optional and you'll generally see the default argument specified in the documentation. Note that the qs CLI is installed on your QuantaStor system so you can run it from there, or from a Windows system using our Remote Management CLI Installer found on the downloads page. All commands can be run against a remote QuantaStor storage system using the --server= argument as outlined above.

Note also that anytime you must specify an object argument like host= volume= share= or others you can refer to the object by name or by its unique ID (UUID). For scripting it is always best to be more exact and use the UUID but it can be a big time-saver to be able to refer to objects by name as well, hence this capability.

Output Modes

XML Output Mode

Use --xml with any command to get the results in XML. Example:

qs disk-list --server=localhost,admin,password --xml
qs volume-list --server=localhost,admin,password

Minimal Output Mode

Use --min with any list or enumeration command where you want the results in a more compact format.

Interactive Mode

You can use the qs command line utility in an interactive mode where you will not have to run it from the shell each time. To enter the interactive mode just run the CLI like so:

qs i

To exit the interactive command line mode simply press CTRL-C to exit.

Built-in CLI Help

All of the commands covered in the documentation are also documented within the command line utility itself. Simply run the CLI with the 'help' argument to get the full list of all the different CLI commands. This list is pretty long so it's often best to pipe it to more
qs help | more

You can also use the help system to get information on a specific command:

    qs help command=CMD-NAME

As an example you can get help on how to use the pool-create command like so:

    qs help command=pool-create

Another way to get information on a group of commands is to specify a category. Help will then be printed for all commands that have a partial name match to the category specified. For example, to see all the commands that have 'pool' in their name:

    qs help category=pool

Or to see all list or get commands:

    qs help category=list
    qs help category=get

In this way you can reduce down help results to just what you need.

Remote System Specification

You can use the CLI to manage remote QuantaStor systems, but in such cases you'll need to specify the IP address and username/password of the remote storage system using the 'server' argument.

qs command [--server=ipaddress[,username,password]] [command-args]
example: qs disk-list --server=,admin,password --xml

Note that the The service specification must be comma delimited with no spaces. If no username and password are supplied the default Administrator username 'admin' and the default password 'password' will be tried.

Command Error Code Definitions

For all commands a 0 is returned for SUCCESS and a non-zero error code is returned if there is a command failure. Use the --xml mode to get verbose detail on the error. Full list of error codes are available here.

Usage Examples

It's always nice to see some common examples of how the CLI can be used so here's a number of commands so you can see the general syntax of how the CLI is used. You'll notice that sometimes we specify arguments with a single hyphen (-), other times with the double hyphen (--) and sometimes it is omitted. All three are supported. The only hard rule is that the command name must be the first argument after the 'qs' command-line utility name. After that the arguments can be specified in any order with or without hyphens.

    qs help -min
    qs pool-list
    qs volume-list -xml
    qs volume-create name=vol1 size=100G pool=pool0
    qs volume-create vol1 100G pool0 -xml --server=,admin,password 

Help Commands

Display help for all commands. 'qs help' provides a verbose listing of all commands with their input parameters. Use 'qs help --min' for a compacted list of commands, or use 'qs help --category=<some category>' for help on aspecific category or command (for example, 'qs help --category=volume').
 qs help|h [--command=value ] [--category=value ] [--wiki=value ] [--api=value ] 
  command A specific CLI command to get detailed help with.
  category Category of commands to get help with (acl, alert, host, host-group, license, role, session, schedule, pool, quota, system, volume, volume-group, task, user, user-group).
  wiki Generates help output in a format that's importable into MediaWiki.
  api Generates help output in a parsable format for automating API.

List of commands for tab completion
 qs tc-commands [--command=value ] 
  command Command to show method args for.

CLI Overview

The Command Reference covers the complete list of all operations accessible via the qs CLI utility (available on Linux, Windows, and is installed within the system). All commands (with few exceptions) are available via the QuantaStor REST API, QuantaStor CLI, and QuantaStor Web Management interface. The CLI includes an XML output mode which can be utilized to integrate with scripts and other automated systems but for more advanced integrations we recommend using the QuantaStor REST API. CLI commands have a short name and long time. When developing scripts it is recommended to use the long command names as it makes scripts easier to read and maintain.

CLI Command Reference Versions

Each new release of QuantaStor CLI generates an updated specification which can be found below. All effort is made to maintain backward compatibility between versions but we recommend that the XML mode be used for scripting. Click the link below to access the latest version of the QS CLI Reference documentation.

QuantaStor CLI Command Reference