VM Management

The table below shows the VM operations that can be performed on any VM in a Cloud VM Set. All operations can be performed by Cloud Administrators.

hicli Command	Description
cvm add_disk	Add a disk to be encrypted
cvm decrypt_task	Perform decryption on specified disk
cvm detail	Get the status of the VM (KeyControl perspective)
cvm detail_disk	Display details about a specified disk
cvm encrypt_task	Perform encryption on specified disk
cvm list	List the VMs in the current Cloud VM Set
cvm list_tasks	Display list of tasks for the specified VM
cvm new	Add a new VM
cvm reauth	Re-authorize a VM
cvm rekey_task	Perform rekey on specified disk
cvm renew clone	Clone a VM certificate
cvm revoke	Revoke access to the VM and its devices
cvm revoke_disk	Revoke access to the specified disk
cvm rm	Remove a VM
cvm rm_disk	Remove a disk from HyTrust management
cvm s3 add_file	Add a file to an S3 bucket
cvm s3 get_file	Retrieve a file from an S3 bucket
cvm s3 rm_file	Remove a file from an S3 bucket
cvm set	Set properties of the VM
cvm set rekey	Set the value for the automatic rekey of disks interval in days/months/years (defaults to 0 which means not set)
cvm set_disk expiration	Set the expiration date for a disk
cvm set_mapping	Set KC mapping
cvm status	Get the status of the VM (as in hcl status)
cvm unrevoke_disk	Give permissions back to access the device

All of these operations are performed in the context of a Cloud VM Set. So, before invoking any of these commands, you need to set the Cloud VM Set first. Let's first look at the current Cloud VM Set:

$ hicli cvmset
Current Cloud VM Set: Amazon EC2

You can change the current Cloud VM Set as follows:

$ hicli cvmset select "Amazon AWS"
$ hicli cvmset 
Current Cloud VM Set: Amazon AWS

To list the VMs associated with a Cloud VM Set:

$ hicli cvm list
VM Name               Status
---------------------------------------------------
ubuntu-10.04          Online
ubuntu-12.10          Online

To request more information about a specific VM, there are two options. The first is equivalent to running hcl status on the VM. For example:

$ hicli cvm status ubuntu-12.10
Host Status on ubuntu12.10
---------------------------------------------------
Summary
---------------------------------------------------
KeyControl: kc-1:443
KeyControl list: kc-1:443
Status: Connected

Registered Devices
---------------------------------------------------
Disk Name         Clear                             Cipher      Status
---------------------------------------------------
sdb2              /dev/mapper/clear_sdb2            AES-256     Attached
 '--> auto_attach=ENABLED, attach_handler=DEFAULT, detach_handler=DEFAULT
sdb1              /dev/mapper/clear_sdb1            AES-256     Attached
 '--> auto_attach=ENABLED, attach_handler=DEFAULT, detach_handler=DEFAULT

Available Devices
---------------------------------------------------
Disk Name           Device Node                     Size (in MB)
---------------------------------------------------
sde                 /dev/sde                        2048
sdd                 /dev/sdd                        2048
sdc                 /dev/sdc                        2048

Other Devices
---------------------------------------------------
Disk Name           Device Node                     Status
---------------------------------------------------
sda5                /dev/sda5                       Mounted (swap)
sda1                /dev/sda1                       Mounted (/)

And the second displays abbreviated information:

$ hicli cvm detail ubuntu-12.10
KeyControl Status for ubuntu12.10
---------------------------------------------------
Name                            ubuntu12.10
IP Address                      192.168.11.93
Status                          Online
Description
Cloud VM Set                    HCS
OS                              Linux ubuntu 2.7.32-38-generic #83-Ubuntu
				   SMP Wed Jan 4 11:12:07 UTC 2014 x86_64 GNU/Linux
Agent version                   10.4.3
Valid till                      02/01/2020
Heartbeat (sec)                 10
Grace period (sec)              3600
Reauth on H/W signature change  Yes
Reauth on IP address change     Yes
Reauth on reboot                No

Disks:
sdb1                            ACTIVE
sdb2                            ACTIVE

Adding a new VM and adding devices to be encrypted is very straightforward, as the following script shows:

$ hicli user login spate --password=******** 
$ hicli cvmset set 'Amazon EC2' 
$ hicli cvm new ubuntu10.04 
$ hicli cvm ubuntu10.04 add_disk sdb1 
$ hicli cvm ubuntu10.04 add_disk sdb2

We log on to the KeyControl as user spate. Next we select the Cloud VM Set into which we wish to place the VM. The new subcommand is used to register and authenticate the new VM. We then add two disks. Note that we are using the abbreviated names sdb1 and sdb2 in place of /dev/sdb1 and /dev/sdb2.

The hicli cvm new command involves calling the KeyControl to create and download a new certificate which is then copied to the VM. It then calls hcl register from the VM and completes authentication. The call to add_disk is the equivalent of hcl add, which adds and attaches the device including getting access to the key. Following the call to add_disk, the encrypted device is now ready to use.

Note: The Policy Agent software must be installed prior to adding the VM.

At this point, you can view the effects of your script through the KeyControl webGUI.

To undo the effects of the script above, to remove the devices, and to remove the VM, use the following script:

$ hicli cvmset select "Amazon EC2"
$ hicli cvm ubuntu-10.04 rm_disk sdb1
$ hicli cvm ubuntu-10.04 rm_disk sdb2
$ hicli cvm revoke ubuntu-10.04
$ hicli cvm rm ubuntu-10.04

At this point it will look like the original script was never run.

The revoke and unrevoke options allow you to forcibly remove access to clear-text data and then grant permissions back to a device. The following operation is equivalent to selecting the Cloud icon, choosing a virtual machine and disk, and then selecting Actions > Revoke Disk Access:

$ hicli cvm ubuntu-10.04 revoke_disk sdb2

The following operation is equivalent to selecting a device and selecting Actions > Grant Disk Access in the KeyControl webGUI.

$ hicli cvm ubuntu-10.04 unrevoke_disk sdb2

The revoke sub-command is equivalent to selecting a device and then selecting Actions > Revoke VM Authentication in the KeyControl webGUI.

$ hicli cvm revoke ubuntu-10.04

The opposite operation is the reauth of the VM. This will perform the equivalent of running hcl auth on the command line of the VM and then typing the passphrase in the webGUI.

$ hicli cvm reauth ubuntu-10.04

Renew the certificate of a Cloud VM:

$ hicli cvm renew ubuntu-12.10

Clone a Cloud VM:

$ hicli cvm clone ubuntu-12.10 ubuntu-clone

Get details of a disk:

$ hicli cvm ubuntu-12.10 detail_disk sdb1
Name			sdb1
Mapped Device		clear_sdb1
Status			Active
Algorithm		AES-256
Expiration		Never
OnExpiry		Shred
Size (bytes)		104857600

Change disk attributes:

$ hicli cvm ubuntu-12.10 set_disk sdb1 --expiration="12/31/2022" --onexpiry="No Use"

Rekey a disk:

$ hicli cvm ubuntu-12.10 rekey_disk sdb1

Encrypt a file:

$ hicli cvm ubuntu-12.10 encryptfile -k aws_key /tmp/files.zip

Decrypt a file:

$ hicli cvm ubuntu-12.10 decryptfile /tmp/files.zip.enc