IM Command-line Interface (CLI)
The im_client is a CLI client that uses XML-RPC or REST APIs of IM Server.
Installation
Prerequisites
The im_client needs at least Python 2.4 to run.
It is also required to install the RADL parser (https://github.com/grycap/radl), available in pip as the ‘RADL’ package. It is also required the Python Requests library (http://docs.python-requests.org/) available as ‘python-requests’ in O.S. packages or ‘requests’ in pip.
Optional packages
In case of using the SSL secured version of the XMLRPC API the SpringPython framework (http://springpython.webfactional.com/) must be installed.
Installing
Docker image
A Docker image named grycap/im-client has been created. Information about this image can be found here: https://hub.docker.com/r/grycap/im-client/. It is also available in Github Container registry ghcr.io/grycap/im-client: https://github.com/grycap/im-client/pkgs/container/im-client.
How to launch the IM client using docker:
docker run --rm -ti -v "$PWD:/im-client" grycap/im-client list
From pip
You only have to call the install command of the pip tool with the IM-client package:
$ pip install IM-client
From source
Download de source code from the Github repo: https://github.com/grycap/im-client/releases. Then you only need to install the tar-gziped file to any directoy:
$ tar xvzf IM-client-X.XX.tar.gz
Configuration
To avoid typing the parameters in all the client calls. The user can define a config file “im_client.cfg” in the current directory or a file “.im_client.cfg” in their home directory. In the config file the user can specify the following parameters:
[im_client]
# only set one of the urls
#xmlrpc_url=http://localhost:8899
restapi_url=http://localhost:8800
auth_file=auth.dat
xmlrpc_ssl_ca_certs=/tmp/pki/ca-chain.pem
Invocation
The im_client is called like this:
$ im_client.py [-u|--xmlrpc-url <url>] [-r|--restapi-url <url>] [-v|--verify-ssl] [-a|--auth_file <filename>] operation op_parameters
- -u|--xmlrpc-url url
URL to the XML-RPC service. This option or the ` -r` one must be specified.
- -r|--rest-url url
URL to the REST API on the IM service. This option or the ` -u` one must be specified.
- -v|--verify-ssl
Verify the certificates of the SSL connection. The default value is False.
- -a|--auth_file filename
Path to the authorization file, see Authorization File. This option is compulsory.
- -f|--force
Force the deletion of the infrastructure. Only for destroy operation. The default value is False.
- -q|--quiet
Work in quiet mode. Avoid all unnecessary prints. The default value is False.
- -n|--name
Show/use Infrastructure name in the selected operation. In case of list operation it will show the name of each infrastructure (if available). In other operations if this flag is set the user should specify the name of the infrastructure instead of the ID. The default value is False.
- operation
list filterList the infrastructure IDs created by the user. The
filterparameter is optional and is a regex that will be used to filter the list of infrastructures. This regex will be used with the RADL or TOSCA of the infrastructure.create inputfile async_flagCreate an infrastructure using RADL/TOSCA specified in the file with path
inputfile. Theasync_flagparameter is optional and is a flag to specify if the creation call will wait the resources to be created or return immediately the id of the infrastructure.destroy infIdDestroy the infrastructure with ID
infId.getinfo infId [radl_attribute]Show the information about all the virtual machines associated to the infrastructure with ID
infId. Optional parameterradl_attributeto show only the value of the specified attribute in the RADL.getcontmsg infIdShow the contextualization message of the infrastructure with ID
id.getstate infIdShow the state of the infrastructure with ID
id.getoutputs <infId>Show the outputs of infrastructure with ID
infId(Only in case of TOSCA docs with REST API).getvminfo infId vmId [radl_attribute]Show the information associated to the virtual machine with ID
vmIdassociated to the infrastructure with IDinfId. Optional parameterradl_attributeto show only the value of the specified attribute in the RADL.getvmcontmsg infId vmIdShow the contextualization message of the virtual machine with ID
vmIdassociated to the infrastructure with IDinfId.addresource infId radlfile ctxt_flagAdd to infrastructure with ID
infIdthe resources specifies in the RADL file with pathradlfile. Thectxt_flagparameter is optional and is a flag to specify if the contextualization step will be launched just after the VM addition. If not specified the contextualization step will be launched.removeresource infId vmId ctxt_flagDestroy the virtual machine with ID
vmIdin the infrastructure with IDinfId. Thectxt_flagparameter is optional and is a flag to specify if the contextualization step will be launched just after the VM addition. If not specified the contextualization step will be launched.start infIdResume all the virtual machines associated to the infrastructure with ID
infId, stopped previously by the operationstop.stop infIdStop (but not remove) the virtual machines associated to the infrastructure with ID
infId.alter infId vmId radlfileModify the specification of the virtual machine with ID
vmIdassociated to the infrastructure with IDvmId, using the RADL specification in file with pathradlfile.reconfigure infId radl_file vm_listReconfigure the infrastructure with ID
infIdand also update the configuration data specified in the optionalradl_file. The lastvm_listparameter is optional and is a list integers specifying the IDs of the VMs to reconfigure. If not specified all the VMs will be reconfigured.startvm infId vmIdResume the specified virtual machine
vmIdassociated to the infrastructure with IDinfId, stopped previously by the operationstop.stopvm infId vmIdStop (but not remove) the specified virtual machine
vmIdassociated to the infrastructure with ID infrastructure with IDinfId.rebootvm infId vmIdReboot the specified virtual machine
vmIdassociated to the infrastructure with ID infrastructure with IDinfId.sshvm infId vmId [show_only]Connect with SSH with the specified virtual machine
vmIdassociated to the infrastructure with ID infrastructure with IDinfId. Theshow_onlyparameter is optional and is a flag to specify if ssh command will only be shown in stdout instead of executed.export infId deleteExport the data of the infrastructure with ID
infId. Thedeleteparameter is optional and is a flag to specify if the infrastructure will be deleted from the IM service (the VMs are not deleted).import json_fileImport the data of an infrastructure previously exported with the previous function. The
json_fileis a file with the data generated with theexportfunction.wait infId [max_time]Wait infrastructure with ID
infIdto get a final state. It will return code0if it becomesconfiguredor1otherwhise. Optional parametermax_timeto set the max time to wait in seconds.create_wait_outputs inputfileThis operation is a combination of the create, wait and getoutputs functions. First it creates the infrastructure using the specified
inputfile, then waits for it to be configured, and finally gets the TOSCA outputs. In case of failure in then infrastructure creation step only the error message will be returned. The results will be returned to stdout in json format:{"infid": "ID", "error": "Error message"}
cloudusage cloud_idShow the usage/quotas of the cloud with ID
cloud_id. The results will be returned to stdout in json format:[ { "uri": "ost://server.com/image_id1", "name": "Image 1 Name" }, { "uri": "ost://server.com/image_id2", "name": "Image 2 Name" } ]
cloudimages cloud_idShow the images available in the cloud with ID
cloud_id. The results will be returned to stdout in json format (-1 means no limit):{ "cores": { "used": 36, "limit": -1 }, "ram": { "used": 50, "limit": -1 }, "instances": { "used": 10, "limit": 50 }, "security_groups": { "used": 0, "limit": -1 }, "floating_ips": { "used": 0, "limit": -1 } }