NAME

htroot - Encrypt Linux Root devices using HyTrust DataControl

SYNOPSIS

htroot [OPTIONS]

DESCRIPTION

The htroot command is used to manage encrypted root disk, swap and other system devices using HyTrust's DataControl. The policy agent can be used to encrypt root disk mounted on "/", multiple swap devices and devices mounted on Linux system mount points such as "/usr", "/opt", "/home" etc. This document refers to all these devices as "Linux root devices".

OPTIONS

The options are as follows:

status

Display information about encryption status of Linux root devices.

setup [-c params.conf]

Prepare system for root device encryption. This command makes necessary modifications to grub and HyTrust configuration. It also installs required packages from external repositories, if required. The user is prompted before packages are installed.

The setup command also rebuilds initrd with additional binaries and configuration files required to encrypt the root devices.

Root disk encryption on Linux requires a separate /boot partition. If the VM does not have a separate /boot, setup fails. Please refer to the Admin Guide for more information on how to seperate the boot partition on an exsting VM.

htroot setup is an interactive process. In the preparation phase, the user is prompted to make various choices. For example the user is asked to choose appropriate network configuration.

During the preparation phase, the administrator can setup a "debug console" which can be used to monitor encryption progress. As the root device encryption happens during system boot, regular admin login does not work. Other than "debug console", the progress can also be monitored on the Virtual Machine Console.

The setup command prompts the user to enable the debug console and download ssh identity file. During the root device encryption, the administrator can connect to debug console with this identity file, like

# ssh -i <identity file> root@vm

The debug console provides various options in addition to showing the encryption progress, for example network restart, authentication with KeyControl etc.

-c option can be used to provide encryption related parameters using a config file. A sample configuration file is provided at /opt/hcs/bin/params.conf This option is useful in automating the invocation of htroot setup.

update [-c params.conf]

This command allows the user to update the grub configuration files and initrd for a previously root encrypted system. Note that even if the root device is decrypted later, the HyTrust changes to boot loader remain with the system, unless they are explicitly removed with cleanup command or the HyTrust agent software is uninstalled.

The update command is useful after a system kernel upgrade or HyTrust software upgrade. If the HyTrust software is upgraded on a system, it automatically updates the grub configuration and initrd. However if any of the encrypted Linux root device has in-progress encryption activity, at the time of HTDC upgrade then htroot update has to be done manually, after the encryption activity is over.

The update command also allows the administrator to update the network configuration used for root device encryption.

-c option can be used to provide encryption related parameters using a config file. A sample configuration file is provided at /opt/hcs/bin/params.conf This option is useful in automating the invocation of htroot update.

cleanup [-f]

The HyTrust changes to boot loader (grub), fstab, initrd can be removed with this command. If the root device is still encrypted then cleanup fails with a message that the administrator needs to decrypt the root device first.

If HyTrust agent has not made any changes to boot loader then cleanup returns immediately reporting that cleanup is not needed. However the administrator can force a cleanup with -f option.

If the cleanup command is interrupted by a user signal or system reboot then the administrator needs to run cleanup again, before running any other command.

encrypt [device list] [--noreboot] [--yes]

Prepare Linux root devices for encryption. This command makes necessary modifications in grub config and fstab, to initiate encryption in the next system boot.

device list is an optional parameter. The user can provide a comma (,) separated list of device names, which should be encrypted. The valid device names can be found in the output of command hcl status under the first column Disk name. If device list is provided htroot command checks for the validity of the operation on every device in the list. If the operation is not valid for any device in the list, for example encrypt is called on a device which is already encrypted, then the command fails.

If the device list is not provided then htroot encrypt becomes an interactive process. The user is prompted to choose root device, swap devices and other mount points to be encrypted under root device encryption. In the interactive mode the user can choose to encrypt root device, any or all of the swap devices and additional system mount points like /var, /usr, /opt if they are mounted on separate block devices.

Please note that in interactive mode the admin needs to provide "Mount Points" for /var, /usr, /opt etc. and not the disk or partition name. Whereas in non-interactive mode all devices are specified using "Disk Names".

Note that for root device encryption, the block device should have an entry in /etc/fstab.

The admin can run htroot encrypt multiple times and choose any of the system devices in any order. All the prepared devices will be encrypted during the next boot.

At the end of the preparation phase, htroot prompts the user to reboot the system. During subsequent boot the selected devices are encrypted. The progress of encryption can be seen on the VM console and debug console.

If --noreboot option is specified then the system will not be rebooted after the operation. The admin will have to manually reboot the system to initiate the encryption.

--yes option can be used to take affirmative action for all the confirmations.

decrypt <device list | -a> [--noreboot] [--yes]

Prepare the Virtual Machine for decryption of Linux root devices. At the end of this command the user is prompted to reboot the system.

device list is an optional parameter. The user can provide a comma (,) separated list of device names, which should be decrypted. The valid device names can be found in the output of command hcl status under the first column Disk name. If device list is provided htroot command checks for the validity of the operation on every device in the list. If the operation is not valid for any device in the list, for example decrypt is called on a device which is not encrypted, then the command fails.

The admin can specify -a instead of device list. If -a is specified then all the encrypted Linux root devices are decrypted.

If --noreboot option is specified then the system will not be rebooted after the operation. The admin will have to manually reboot the system to initiate the decryption.

--yes option can be used to take affirmative action for all the confirmations.

rekey <device list | -a> [--noreboot] [--yes]

Prepare the Virtual Machine for Linux root device rekey. At the end of this command the user is prompted to reboot the system.

device list is an optional parameter. The user can provide a comma (,) separated list of device names, which should be rekeyed. The valid device names can be found in the output of command hcl status under the first column Disk name. If device list is provided htroot command checks for the validity of the operation on every device in the list. If the operation is not valid for any device in the list, for example rekey is called on a device which is not encrypted, then the command fails.

The admin can specify -a instead of device list. If -a is specified then all the encrypted Linux root devices are rekeyed.

If --noreboot option is specified then the system will not be rebooted after the operation. The admin will have to manually reboot the system to initiate the rekey.

--yes option can be used to take affirmative action for all the confirmations.

version

Display the version of the DataControl agent software.

-h | -?

This command displays all the options available through the htroot command.

FILES

/opt/hcs

The default location of the HyTrust DataControl configuration files.

/var/log/htroot.log

The HyTrust DataControl htroot log file. If errors are detected, you will be requested to provide this file to HyTrust support staff.

/opt/hcs/bin/params.conf

Sample configuration file for supplying parameters to htroot

BUGS

See the HyTrust Release Notes for information about bugs and caveats in the software.

AUTHOR

HyTrust Inc.

SEE ALSO

hcl(1)