Using the command-line interface

In this tutorial, we will show how to install ComodIT’s Command-Line Interface (CCLI) on Fedora, CentOS, Ubuntu and Debian systems. We will then configure CCLI and finally illustrate its usage by re-creating a simplified version of the ‘Web Server’ application present by default in your organization.

Note Command-line usage is an advanced topic.

1. Pre-requisites

It is assumed that the reader has already created an account on ComodIT and has already created an application using the web interface (see this tutorial). The reader shloud also be familiar with the JSON format.

2. Install

You need to be super-user to install CCLI on your computer.

Fedora/CentOS Users

Add ComodIT repository by executing the following command:
- On CentOS 7: rpm -ivh http://dl.comodit.com/pub/centos/7/x86_64/comodit-release-7-0.el7.noarch.rpm
- On Fedora 27: rpm -ivh http://dl.comodit.com/pub/fedora/27/x86_64/comodit-release-1-0.fc27.noarch.rpm
Install CCLI package with command yum install comodit-client.

Ubuntu/Debian Users

1. Add ComodIT repository by executing the following command:

cat <<EOF > /etc/apt/sources.list.d/comodit.list
deb http://dl.comodit.com/pub debian-stretch main
EOF

Replace debian-stretch by the name of your distribution.

Ex: for Ubuntu 16

deb http://dl.comodit.com/pub ubuntu-16 main

2. Install repository key:

wget http://dl.comodit.com/pub/comodit.asc -O /tmp/key; apt-key add /tmp/key; rm -f /tmp/key

3. Install CCLI package with command apt-get update; apt-get install comodit-client.

Enable auto-completion

CCLI supports auto-completion, however if you try to use it directly in the same terminal you used to install it, it wont work (this is a consequence of how bash auto-completion framework configures itself). In this case, just open a new terminal. You may also source the file /etc/bash_completion.d/comodit using the following command:

source /etc/bash_completion.d/comodit

3. Configure

By default, a system-wide configuration file located at /etc/comodit-client/comodit-client.conf is created when installing CCLI package. CCLI configuration file defines one or several profiles. A profile defines a ComodIT server endpoint as well as the credentials to use when authenticating.

In you user directory, create a user-wide configuration file .comoditrc and fill it with the following content (replace username and password values with your own credentials):

[client]
default_profile = mycomodit

[mycomodit]
api = https://my.comodit.com/api
username = user
password = pass
vnc_viewer_call = vinagre %h:%p

‘client’ section defines which profile to use by default (here, ‘mycomodit’ profile is used). Each following section defines a profile.

In above example, there is one profile called ‘mycomodit’. Server endpoint is https://my.comodit.com/api and ‘user’ and ‘pass’ are respectively the username and the password to use when connecting to the server. Finally, ‘vnc_viewer_call’ field defines the command to execute when connecting through VNC to a host’s instance (see man page for more details). %h and %p are respectively replaced with hostname and VNC port upon command execution. In given example, ‘vinagre’ is used as VNC client.

4. Use

General Usage

CCLI command name is ‘comodit’. Invoking directly CCLI will print its usage. Generally, a CCLI invocation will have the following form:

comodit [OPTIONS] TARGET_TYPE ACTION ID [PARAMS]

where

OPTIONS is a list of options, for example --profile mycomodit to select profile ‘mycomodit’;
TARGET_TYPE is the targeted ComodIT resource, for example an organization, a host, an application, etc.;
ACTION is the action applied to the resource, for example ‘show’, ‘list’, ‘update’, ‘delete’, etc.;
ID is the identifier of targeted resource;
PARAMS is a list of positional parameters required by the action.

A resource might be enclosed by another resource, for example, a parameter might be enclosed by an application, a distribution, etc. This type of resource is called a sub-resource. So TARGET_TYPE part in above example might actually be composed of several words: a resource followed by a list of sub-resources. For example, if you want to target a particular file of an application, TARGET_TYPE will be ‘applications files’.

An action is always a single word, generally one of:

list
create
show
update
delete

Some resources do not support these actions and/or define other actions.

Finally, the resource identifier (ID in above example) depends on resource type and may also be composed of several words. For instance, when targeting a host, an organization name, an environment name and a host name must be provided in order to uniquely identify it.

CCLI supports auto-completion for resources, sub-resources, actions and identifiers. For example, typing ‘comodit’ in your terminal and hitting the TAB key to auto-complete will show up all available top-level resources.

Create ‘Web Server’ application

We assume that you have an organization ‘MyOrg’ containing default ‘Web Server’ application and that you have properly configured your default profile (there is therefore no need to use ‘--profile’ option).

Download original ‘httpd.conf’ file from here and parametrize it by replacing Listen 80 line by Listen ${httpd_port}. We assume that the file has been downloaded in current directory and has its original name (httpd.txt).

Create the application:

 comodit applications add MyOrg

This should open an editor containing a JSON skeleton for your application.

2.1. First update name field, for instance call your new application ‘My Web Server’

     "name":"My Web Server"

2.2. Update the description:

     "description":"My web server application."

2.3. Set the packages needed by your application, in this case ‘httpd’:

     "packages": [
         {"name":"httpd"}
     ]

2.4. Set the services used by your application, in this case ‘httpd’:

     "services": [
       {
           "name":"httpd",
           "enabled":true
       }
     ]

2.5. Define the files of your application, in this case Apache’s configuration file:

     "files": [
         {
             "name":"httpd.conf",
             "path":"/etc/httpd/conf/httpd.conf",
             "owner":"root",
             "group":"root",
             "mode":"644",
             "template": {
                 "delimiter": {
                     "start": "${",
                     "end": "}"
                 }
             }
         }
     ]

2.6. Set the parameters of your application, in this case the port Apache is listening to:

     "parameters": [
         {
             "name": "Port",
             "description": "Apache's port",
             "key": "httpd_port",
             "value": "80"
         }
     ]

2.7. Set the handlers of your application, in this case update configuration file and restart service when ‘httpd_port’ value is updated:

     "handlers": [
         {
             "do": [
                 {
                     "action": "update", 
                     "resource": "file://httpd.conf"
                 }, 
                 {
                     "action": "restart", 
                     "resource": "service://httpd"
                 }
             ], 
             "on": [
                 "httpd_port"
             ]
         }
     ]

2.8. Save and close file, the application should now exist and CCLI displays a more user-friendly representation of it. To verify application’s existence, you may explicitly display its representation with the following command:

 comodit applications show MyOrg My\ Web\ Server

You may use --raw option to display JSON representation, you should obtain something like this.

Currently, the application exists and defines a configuration file ‘httpd.conf’ but this file has no content. For instance, if you execute the following command, you will get an error:
```
  comodit applications files show-content MyOrg My\ Web\ Server httpd.conf
```
To set the content of the file, execute the following command (we suppose that file ‘httpd.txt’ exists, see step 1):
```
  comodit applications files set-content MyOrg My\ Web\ Server httpd.conf httpd.txt
```
If you re-execute ‘show-content’ action, you should see the content of the file you just uploaded.
Install the application on an existing host (e.g. ‘MyHost’ in environment ‘Default’) with the following command:
```
 comodit hosts applications install MyOrg Default MyHost
```