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=f1bd87fe2a40498db78ee596766f57b0Interactive 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 moreInteractive 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 6Interactive mode:
admin >>>more 6The 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.jsonInteractive 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.jsonInteractive 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
