ZStack Cloud 4.4.0>Product Manuals>zstack-cli Command Manual>Command Line Tool

Command Line Tool

Overview

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

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

ZStack Cloud 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 Cloud Management Node

zstack-cli is installed by default after you install a ZStack Cloud 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 Cloud 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 Cloud 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

Next Chapter:Query