+ CLI Guide Overview

From OSNEXUS Online Documentation Site
Jump to navigation Jump to 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 appliances.

Authentication

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

Authentication via --server Argument

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

[--server=ipaddress[,username,password]]

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 appliance IP address and credentials. The form of the variable is like so: 

export QS_SERVER=ipaddress[,username,password]]

Examples: 

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

Authentication via .qs.cnf Configuration File

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 "192.168.0.10,admin,password" > ~/.qs.cnf
chmod 600 ~/.qs.cnf

Usage

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=192.168.0.88,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=192.168.0.88,admin,password

Help Commands

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


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

CLI Command Reference

The following list of commands is the complete list of everything you can do from the CLI. In fact, the list of CLI commands is a pretty close 1-to-1 match with our SOAP based management interface API set. As such, anything you can do via the web management interface, you can do through the CLI, and with the XML output mode you can easily integrate your QuantaStor system with any automated provisioning system in any language. Note that we list the command names along with a short version in square brackets (ex: help [h]). If you find yourself using the CLI frequently learning the short command names can make the CLI easier to work with as it reduces the amount of typing required. For scripting, it's often better to use the long command names as it makes your script easier to read and maintain.

Alert Management [ALERT]

Alerts are generated by the system and routed to the administrators via the various call-home mechanisms which include email, SNMP, PagerDuty and custom alert handlers. Alerts include a severity, a descriptive message, and in most cases an identifier referring to the element of the system or grid that is the subject of the alert.


alert-clear

Deletes the alert with the specified ID. 

 qs alert-clear|a-clear --id=value
  id Unique identifier (GUID) for the object.

alert-clear-all

Clears all the alerts. 

 qs alert-clear-all|a-clear-all

alert-config-get

Alert configuration settings indicate where alert notifications should be sent. 

 qs alert-config-get|ac-get

alert-config-set

Sets the alert configuration settings such as the administrator email address, SMTP server address, etc. Be sure to use the alert-raise command to generate a test alert after you modify the alert configuration settings to ensure that emails are being properly sent. 

 qs alert-config-set|ac-set [--sender-email=value ] [--smtp-server=value ] [--smtp-port=value ] [--smtp-user=value ] [--smtp-password=value ] [--smtp-auth=value ] [--support-email=value ] [--freespace-warning=value ] [--freespace-alert=value ] [--freespace-critical=value ] [--pagerduty-key=value ]
  sender-email Sender email address to be used for alert emails sent from the storage system.
  smtp-server IP Address of the SMTP service where emails should be routed through.
  smtp-port Port number of the SMTP service (eg 25, 465, 587) where emails should be routed through (0 indicates auto-select).
  smtp-user SMTP user name to use for secure SMTP access to your SMTP server for sending alert emails.
  smtp-password SMTP password to use for secure SMTP access to your SMTP server.
  smtp-auth SMTP security mode.
  support-email Email address for local customer support.
  freespace-warning The percentage of free-space left in a pool at which a warning is sent to indicate pool growth plans should be made.
  freespace-alert The percentage (default=10) of free-space left in a pool at which alerts are generated.
  freespace-critical The percentage (default=5) of free-space left in a pool at which all provisioning operations are blocked.
  pagerduty-key Specifies the service key to which alerts will be posted to PagerDuty. Please see www.pagerduty.com for more detail on service keys.


alert-get

Gets information about a specific alert. 

 qs alert-get|a-get --id=value
  id Unique identifier (GUID) for the object.


alert-list

Returns a list of all the alerts from all systems in the grid. Adjust the settings for the 'admin' or custom user account(s) to indicate alerts to be sent out via email call-home mechanism. 

 qs alert-list|a-list [--filtered=value ]
  filtered Returns just the 'value' most recently created.


alert-raise

Allows one to raise a user generated alert for testing the SMTP server configuration settings. 

 qs alert-raise|a-raise --title=value --message=value [--alert-severity=value ]
  title Title string to be echoed back from the server.
  message Message string to be echoed back from the server.
  alert-severity Severity of the user generated alert to be raise. [always, critical, error, *info, warning]


event-list

Returns a list of all the internal events in the event queue (used for service monitoring). 

 qs event-list|ev-list [--index=value ] [--max=value ] [--time-stamp=value ]
  index Starting event index of where to begin listing events from.
  max Maximum number of events to enumerate.
  time-stamp Time-stamp of the service.

Backup Policy Management [BACKUP-POLICY]

Backup policies provide a mechanism for scheduling and executing automatic backups of 3rd party filers and other NFS/SMB shares in an environment directly to a Network Share.


Scale-out Object / Ceph Management [CEPH]

Commands for management, monitoring, and configuration of Ceph object clusters and associated storage.


Cloud Backup Schedule Management [CLOUD-BACKUP]

Cloud Backup schedules provide a mechanism for automatic backups of storage volumes into remote S3/SWIFT object storage.


Cloud Container Management [CLOUD-CONTAINER]

Cloud containers provide a NAS gateway mechanism to bridging S3/SWIFT cloud storage to a local Network Share within an appliance.


Storage System Grid Management [GRID]

Commands for management and formation of grids of QuantaStor appliances which simplifies management and enables advanced features including HA, DR, and scale-out configurations.


Storage Pool HA Failover Management [HA-FAILOVER]

Storage Pools based on ZFS can be made Highly-Available when formed using SAS/FC/iSCSI disks connected to two or more appliances. HA storage pools can be moved dynamically between a pair of appliances and activated HA groups will do automatic failover to ensure availability to the underlying pool and it's associated volume and shares.


Host Management [HOST]

Storage Volumes must be assigned to Host(s) before the block storage (LUNs) can be accessed. Each Host entry is identified by one or more iSCSI IQNs and/or FibreChannel WWPNs.


Host Group Management [HOST-GROUP]

Hosts can be grouped together into Host Group(s) to simplify assignment and management of Storage Volumes assigned to a cluster of hosts (eg. VMware).


Hardware RAID Management [HWRAID]

Integrated hardware management modules monitor, discover, correlate and manage all the key aspects of internal SAS HBAs and RAID Controllers.


SAS Switch Management [HWSWITCH]

DEPRECATED


License Management [LICENSE]

Commands for management of QuantaStor license keys including adding, removing and listing keys within a grid of one or more appliances.


Cloud I/O Stats Management [METRICS]

Commands for the configuration and management of Librato Metrics cloud stats collection system.


Storage Pool Management [POOL]

Storage Pools combined Physical Disks together to form fault-tolerant pools of storage that can be provisioned from. Both Storage Volumes and Network Shares are provisioned from Storage Pools where ZFS based pools are the default ans XFS based pools are used for scale-out configurations using Ceph or Gluster technology.


QoS Policy Management [QOSPOLICY]

Storage Volume access can be throttled to limit throughput independently for read and write IO in terms of MB/sec via Quality of Serivce (QoS) policies.


Resource Group Quota Management [QUOTA]

Resource Groups can have quotas associated with them to limit which pools and how much storage can be provisioned from those pools by a given group of users which are members of a Resource Group


Remote Replication Management [REPLICATION]

Remote-replication and associated replication schedules enable automatic replication to a pool of storage in a remote appliance for disaster-recovery (DR) purposes.


Resource Domain Management [RESOURCE-DOMAIN]

Resource Domains group appliances by site, building, and rack so that scale-out data distribution technologies (Ceph CRUSH, GlusterFS) can be automatically configured.


Multitenant Resource Group Management [RESOURCE-GROUP]

Resource Groups combine volumes, shares, and pools of storage together and so that they can be assigned to one more users (tenants). This facilitates multi-tenancy and delegation of common tasks like storage provisioning to end-users.


RBAC Role Management [ROLE]

Advanced Role Based Access Controls (RBAC) allow for the creation of custom roles that limit users to specific tasks and operations within a grid or Resource Group (collection of volumes, shares, and pools).


Snapshot Schedule Management [SCHEDULE]

Snapshot schedules make automatic instant point-in-time snapshots of Storage Volumes and/or Network Shares on a schedule. It is highly recommended that snapshot schedule(s) be created for all mission critical volumes and shares so that data and files can be easily recovered from a previous point in time.


iSCSI/FC Session Management [SESSION]

Commands for iSCSI/FC storage session management.


Network Share Management [SHARE]

Commands for managing Network Shares which are accessible via NFS and/or the SMB protocol.


Site Cluster Resource Management [SITE]

Configurations with floating IPs such as High-Availability pools and Gluster VIFs first require that a Site Cluster is formed. Site Clusters maintain a heart-beat and control quorum for a subset of nodes so that Virtual Interfaces can be automatically moved between nodes as necessary.


Software Controller / iSCSI SAN Adapter [SWC]

QuantaStor appliances can use iSCSI storage to form Storage Pools. To configure an appliance to automatically connect to and login to one or more storage appliances to access iSCSI block storage first add and then configure a iSCSI Software Adapter.


Storage System Management [SYSTEM]

Commands for managing all the appliance centric settings including NTP, DNS servers, hostname, ARP policies, system restart, shutdown and more.


Storage System Replication Link Management [SYSTEM-LINK]

Storage System Links are a required prerequisite before remote-replication and replication schedules can be formed to move data between any given pair of appliances in a grid.


Tag/Object Property Management [TAG]

Feature which allows any object within the QuantaStor system to be tagged with user custom properties (key/value pairs). Tagging is often used to facilitate multi-tenancy deployments by applying tags containing unique IDs which identify users, customers, account, tenants and more.


Network Interface Management [TARGET-PORT]

Commands for configuration, management and monitoring of network ports, teaming/bonding, VLAN configuration and more.


Task Management [TASK]

Every configuration operation done within an appliance or across a group of appliances is represented in the system as a Task. Some long running tasks can be canceled while running and all tasks from all systems in a grid are visible and monitorable from all appliances.


Trace Level Management [TRACE-LEVEL]

Debugging facility used to increase the amount of information sent to the /var/log/qs_service.log


User Management [USER]

User management within an appliance is used both to facilitate access to appliance management operations as well as to create local user accounts to provide SMB access to Network Shares. Use the System Monitor role to limit users so that they cannot change the configuration of any aspect of the system except their own password.


User Group Management [USER-GROUP]

Users can be grouped together to simplify management of Resource Groups.


Storage Volume Management [VOLUME]

Commands for the management of Storage Volumes which are block devices which can be presented to Hosts via the iSCSI and/or FC protocols.


Storage Volume Access Control (LUN Masking) [VOLUME-ACLS]

Volume ACLs control which Hosts have access to which Storage Volumes via block protocols like FibreChannel and iSCSI. All Storage Volumes must be assigned before they can be accessed; volumes are never made publically accessible.


Storage Volume Group Management [VOLUME-GROUP]

Storage Volume Groups are a convience feature to grouping together Storage Volumes so that they can be snapshot as a set.


Retrieved from "https://wiki.osnexus.com/index.php?title=%2B_CLI_Guide_Overview&oldid=7663"