Command Line Tool


Overview

zstack-cli is a command line tool that you can use to call all ZStack APIs. All API examples in this documentation are demonstrated by using zstack-cli.

ZStack is built on a service-oriented architecture (SOA). Therefore, all API operations in ZStack are essentially API messages. For example, the CLI command StartVmInstance actually maps to the API message APIStartVmInstanceMsg.

ZStack includes a built-in HTTP service that encapsulates all API messages into HTTP POST requests. zstack-cli calls API requests based on the built-in HTTP service for business processing.


Usage

Connect to ZStack Management Node

zstack-cli is installed by default after you install a ZStack management node. You can start the management node by typing zstack-cli in a shell console.
[root@localhost ~]# zstack-cli

  ZStack command line tool
  Type "help" for more information
  Type Tab key for auto-completion
  Type "quit" or "exit" or Ctrl-d to exit
If no parameters are specified, zstack-cli will automatically connect to port 8080 on localhost. To connect a remote ZStack management node, you can specify the IP address and the port No. by using -H and -p respectively.
[root@localhost ~]# zstack-cli --help
Usage: -c [options]

Options:
  -h, --help            show this help message and exit
  -H HOST, --host=HOST  [Optional] IP address or DNS name of a ZStack
                        management node. Default value: localhost
  -p PORT, --port=PORT  [Optional] Port that the ZStack management node is
                        listening on. Default value: 8080
  -d DEPLOY_CONFIG_FILE, --deploy=DEPLOY_CONFIG_FILE
                        [Optional] deploy a cloud from a XML file.
  -t DEPLOY_CONFIG_TEMPLATE_FILE, --template=DEPLOY_CONFIG_TEMPLATE_FILE
                        [Optional] variable template file for XML file
                        specified in option '-d'
  -D ZSTACK_CONFIG_DUMP_FILE, --dump=ZSTACK_CONFIG_DUMP_FILE
                        [Optional] dump a cloud to a XML file
  -P ADMIN_PASSWORD, --password=ADMIN_PASSWORD
                        [Optional] admin account password for dumping and
                        recovering cloud environment. It can only be used when
                        set -D or -d option. Default is 'password'.
  -s, --no-secure       [Optional] if setting -s, will save password
                        information in command history.
[root@localhost ~]# zstack-cli -H 172.20.16.35

  ZStack command line tool
  Type "help" for more information
  Type Tab key for auto-completion
  Type "quit" or "exit" or Ctrl-d to exit


admin >>>

With zstack-cli, you can connect any management node in a multi-management node environment.

Modes

  • Command mode
    zstack-cli can work in command mode that receives parameters from shell. In the command mode, zstack-cli runs only once and prints an output result to shell. For example,
    [root@localhost ~]# zstack-cli -H 172.20.16.35 QueryZone name=Zone-1
    {
        "inventories": [
            {
                "createDate": "Nov 17, 2017 8:27:47 PM",
                "lastOpDate": "Nov 17, 2017 8:27:47 PM",
                "name": "Zone-1",
                "state": "Enabled",
                "type": "zstack",
                "uuid": "c3a228078e8c4f81ba7da0b16fb8d77f"
            }
        ],
        "success": true
    }
  • Interactive mode
    ztack-cli also works in interactive mode. In the interactive mode, ztack-cli keeps a session to continuously execute commands. For example,
    ...
    
    admin >>>query
    BatchQuery                                        PrometheusQueryLabelValues
    PrometheusQueryMetadata                           PrometheusQueryPassThrough
    PrometheusQueryVmMonitoringData                   QueryAccessKey
    QueryAccount                                      QueryAccountResourceRef
    QueryAffinityGroup                                QueryAlarm
    QueryAlert                                        QueryAliyunDiskFromLocal
    ...
    QueryVmCdRom                                      QueryVmInstance
    QueryVmNic                                        QueryVmNicInSecurityGroup
    QueryVniRange                                     QueryVolume
    QueryVolumeBackup                                 QueryVolumeSnapshot
    QueryVolumeSnapshotTree                           QueryVpcIkeConfigFromLocal
    QueryVpcIpSecConfigFromLocal                      QueryVpcRouter
    QueryVpcUserVpnGatewayFromLocal                   QueryVpcVpnConnectionFromLocal
    QueryVpcVpnGatewayFromLocal                       QueryVtep
    QueryWebhook                                      QueryZone
    ZQLQuery
    
    admin >>>QueryZone

The interactive mode is more suitable for manual execution, while the command mode is more suitable for script integration.

Login

ZStack Identity and Access Management (IAM) supports three login methods: account login, user login, and AD/LDAP login.

Account includes admin account and ordinary account. The admin account uses a default login password: password.

Before you execute any commands, you need to run the login command LogInByAccount to obtain a session token. This token is automatically saved to ~/.zstack/cli/session and needs to be maintained independently.
admin >>>LogInByAccount accountName=admin password=password

Logout

Once you finish your work, you can run the LogOut command to end your current session.
admin >>>LogOut

The LogOut command can receive the sessionUuid parameter, which is optional. You do not need to provide it because zstack-cli can automatically read sessions that were saved.

Execute API Commands

Each API has multiple parameters. You can execute API commands in command mode or interactive mode.
  • Command mode:
    [root@localhost ~]# zstack-cli StartVmInstance uuid=f1bd87fe2a40498db78ee596766f57b0
  • Interactive mode:
    admin >>>StartVmInstance uuid=f1bd87fe2a40498db78ee596766f57b0

View Command History

You can use the more command to view your command history. For example,
  • Command mode:
    [root@localhost ~]# zstack-cli more
  • Interactive mode:
    admin >>>more
The output format is similar to the Linux command more. You can glance or search any entry with the up and down arrow keys.

[NUM]   COMMAND
------------------------------------------------
[1]      LogInByAccount accountName=admin password=******
[2]      ['LogOut']
[3]      ['QueryVmInstance', 'state=Running']
[4]      ['QueryZone']
[5]      ['QueryVmInstance']
[6]      LogInByAccount accountName=admin password=******
[7]      [u'QueryVmInstance', u'count=True', u'state=Stopped']
[8]      [u'QueryVmInstance', u'count=True', u'state=Running']
[9]      [u'QueryVmInstance', u'count=True']
...
You can add a command No. behind more to query the command details.
  • Command mode:
    [root@localhost ~]# zstack-cli more 6
  • Interactive mode:
    admin >>>more 6
    The result is as follows:
    Command:
            LogInByAccount accountName=admin password=******
    Result:
    {
        "inventory": {
            "accountUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
            "createDate": "Dec 28, 2017 5:13:59 PM",
            "expiredDate": "Dec 28, 2017 7:13:59 PM",
            "userUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
            "uuid": "c0488a149e1244799317a84ab3378763"
        },
        "success": true
    }
    (END)

Export Command Result

You can run the save command to export command results. You can save only one history or multiple histories at a time.
  • Saving only one history at a time
    • Command mode:
      [root@localhost ~]# zstack-cli save 1
      Saved command: 1 result to file: /root/LogInByAccount-1.json
    • Interactive mode:
      admin >>>save 1
      Saved command: 1 result to file: /root/LogInByAccount-1.json
  • Saving multiple histories at a time
    • Command mode:
      [root@localhost ~]# zstack-cli save 1,2,3
      [u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
      Saved command: 1 result to file: /usr/local/CreateDataVolume-1.json
      [u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
      Saved command: 2 result to file: /usr/local/CreateDataVolume-2.json
      [u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
      Saved command: 3 result to file: /usr/local/CreateDataVolume-3.json
    • Interactive mode:
      admin >>>save 1,2,3
      [u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
      Saved command: 1 result to file: /usr/local/CreateDataVolume-1.json
      [u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
      Saved command: 2 result to file: /usr/local/CreateDataVolume-2.json
      [u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
      Saved command: 3 result to file: /usr/local/CreateDataVolume-3.json
By default, the results are saved to the current directory. You can also specify a file path as the destination folder.
save 1 /tmp
Download

Already filled the basic info? Click here.

Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

The download link will be sent to your email. Make sure the address you provided is valid and correct.

Download

Not filled the basic info yet? Click here.

Invalid email address or mobile number.

Email Us

contact@zstack.io

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder. After receiving the email, click the URL to download the documentation.

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder.
Or click on the URL below. (For Internet Explorer, right-click the URL and save it.)

Thank you for using ZStack products and services.

Back to Top