hicli is available in an API bundle from the Cryptographic Security Platform Vault webGUI:

  1. Log into the Cryptographic Security Platform Vault for VM Encryption using an account with Cloud Admin privileges.
  2. In the top menu bar, click Workloads.
  3. Select Actions > Download Policy Agent.
  4. From the Available Downloads dialog box, download the hcs-api-10.5.3-buildnum.tgz file, where buildnum is the build number for the release you are installing.
  5. Copy the tgz file to the VM on which you want to install the API.

  6. Navigate to a directory where you want to install the package and untar it as follows:

    $ cd ~
$ tar xvfz hcs-api-10.5.3-buildnum.tgz
				
x hcs-api/
x hcs-api/hclcomm.py
x hcs-api/kpsapi.py
x hcs-api/docopt.py
x hcs-api/hicli

  7. hicli needs the Python requests module, and to manage Windows VMs, it also needs the winrm module. Install these modules:

    $ pip install requests
$ pip install pywinrm

  8. Set up PYTHONPATH to point to the new directory and modify your PATH so that the shell can reference the hicli program. For example, if the install location is /Users/spate, the environment variables need to be set up as follows:

    $ export PYTHONPATH=$PYTHONPATH:/Users/spate/hcs-api
$ export PATH=$PATH:/Users/spate/hcs-api

    Note: If your python installation only includes a python command and not a python3 command, then do one of the following:

    • Edit the first line of hicli from #!/usr/bin/env python3 to #!/usr/bin/env python.

    • Define an alias similar to hicli='python /Users/<user_name>/hcs-api/hicli' using your install location.

  9. Set up a configuration file named ~/.hicli/hicli.cfg that contains information about the virtual machines to be managed. The following example shows a configuration file with two Linux VMs and one Windows VM.

    Notes:

    • The number and location of curly brackets is important. Make sure your configuration file looks like the example below.
    • If the platform is not specified it defaults to "linux".
    • A password is required for Windows platforms to connect over winrm.
    • By default, the hicli.cfg file is used to resolve VM names. If no entries are found, DNS is used to resolve the VM names.
    • On Linux, you can run hicli commands as root or as a sudo user. If you specify a sudo user, you also specify a password if the sudo user requires one. On Windows, you can run hicli with any Windows account that has Administrator privileges.

    The following example shows a hicli.cfg file with three Linux VMs and one Windows VM. The Linux ubuntu10.04 VM uses the standard root account, the ubuntu12.10 VM uses the sudo user spate with the password DogDays123!, and the rhel73 VM uses the passwordless sudo user jsmith. The Windows VM uses the Administrator account with the password XYZ@123.

    {
      "cvmlist": {
        "ubuntu10.04": {
          "host":"192.168.140.129",
          "port":"22", 
          "user":"root"
        },
        "ubuntu12.10": {
          "host":"192.168.140.130",
          "port":"22",
          "user":"spate",
          "sudo_password" : "DogDays123!"
        },
        "rhel73": {
          "host":"192.168.140.131",
          "port":"22",
          "user":"jsmith"
        },
        "Windows2012r2": {
          "host":"192.168.140.132",
          "user":"Administrator",
          "password":"XYZ@123",
          "platform": "windows"
        }
      }
    }

    If you want to manage another VM with hicli, just add that entry to the cfg file.

    {
      "cvmlist": {
        "ubuntu10.04": {
          "host":"192.168.140.129",
          "port":"22",
          "user":"root"
        },
        "ubuntu12.10": {
          "host":"192.168.140.130",
          "port":"22",
          "user":"spate",
          "sudo-password" : "DogDays123!"
        },
        "rhel73": {
          "host":"192.168.140.131",
          "port":"22",
          "user":"jsmith"
        },
        "Windows2012r2": {
          "host":"192.168.140.132",
          "user":"Administrator",
          "password":"XYZ@123",
          "platform": "windows"
        },
        "ubuntu13.04": {
          "host":"192.168.140.133",
          "port":"22",
          "user":"root"
        }
      }
    }
  10. To verify the installation, run the hicli command and you should see a comprehensive listing of the command and its options.

  11. To set up SSH communication on each Linux host, generate a key pair on the API server and copy the public key to each VM on which you want to run API commands. The public key should be appended to the authorized_keys file for either root or the sudo user you specified in the hicli.cfg file. (For the Windows VM you would use WinRM.)

    The following example uses ssh-keygen on the API server to generate the key pair and then uses ssh-copy-id to send the public key to the Linux VMs we added to the hicli.cfg file above.

    api# cd ~/.ssh
api# ssh-keygen -t dsa
api# ssh-copy-id id_dsa.pub root@192.168.140.129
api# ssh-copy-id id_dsa.pub spate@192.168.140.130
api# ssh-copy-id id_dsa.pub jsmith@192.168.140.131
api# ssh-copy-id id_dsa.pub root@192.168.140.133

    After you copy the public key to the VM, make sure that, on each VM:

    • You enable root or sudo user login over SSH to the VM. If you are using a passwordless sudo user, you need to set up passwordless SSH access for that user using the pub.
    • You turn off SSH warnings.

    To test that SSH access is working between your API server and your VM, issue a test command over SSH. For example, you can use SSH to query the hostname on the VM:

    $ ssh root@192.168.140.129 hostname
ubuntu10.04