NAME

htroot - Encrypt Linux Root devices using HyTrust DataControl

SYNOPSIS

htroot OPTIONS

DESCRIPTION

The htroot command manages encrypted root disk, swap, and other system devices using HyTrust DataControl. The policy agent can encrypt the 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 the 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 installing packages.

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 separating the boot partition on an existing VM.

Root 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 an appropriate network configuration.

During the preparation phase, the administrator can set up a "debug console" to monitor encryption progress. Because root device encryption happens during system boot, a regular admin login does not work. Other than the "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 the SSH identity file. During the root device encryption, the administrator can connect to the debug console with this identity file, like

The debug console provides various options in addition to showing encryption progress, such as network restart and authentication with KeyControl.

-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. 

The update command is useful after a system kernel upgrade or HyTrust software upgrade. If you upgrade HyTrust software on a system, it automatically updates the grub configuration and initrd. However, if any encrypted Linux root device has in-progress encryption activity during the HTDC upgrade, you must run htroot update manually after the encryption activity finishes.

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

This command removes HyTrust changes to the boot loader (grub), fstab, and initrd. If the root device is still encrypted, cleanup fails with a message that the administrator must decrypt the root device first.

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

If a user signal or system reboot interrupts the cleanup command, the administrator must run cleanup again before running any other command.

encrypt device list --noreboot --yes

Prepare Linux root devices for encryption. This command makes the necessary modifications to the grub config and fstab to initiate encryption at 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. Valid device names are in the output of the command hcl status under the first column, Disk name. If you provide a device list, the htroot command checks whether the operation is valid for 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 the root device, swap devices, and other mount points to be encrypted under root device encryption. In interactive mode, the user can encrypt the root device, any or all swap devices, and additional system mount points like /var, /usr, or/opt if they are mounted on separate block devices.

In interactive mode, the admin must provide "Mount Points" for /var, /usr, /opt, etc., not the disk or partition name. In non-interactive mode, specify all devices using "Disk Names".

The admin can run htroot encrypt multiple times and choose any system device 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 the subsequent boot, the selected devices are encrypted. You can see the encryption progress on the VM console and debug console.

If you specify the --noreboot option, the system will not reboot after the operation. The admin must manually reboot the system to initiate encryption.

--yes option can be used to take affirmative action for all 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 to decrypt. Valid device names are in the output of the hcl status command under the first column, Disk name. If you provide a device list, the htroot command checks whether the operation is valid for 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 a device list. If -a is specified, then all the encrypted Linux root devices are decrypted.

If the --noreboot option is specified, the system will not reboot after the operation. The admin must manually reboot the system to initiate decryption.

--yes option can be used to take affirmative action for all 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. Valid device names are in the output of the command hcl status under the first column, Disk name. If you provide a device list, the htroot command checks whether the operation is valid for 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 a device list. If -a is specified, then all the encrypted Linux root devices are rekeyed.

If the --noreboot option is specified, the system will not reboot after the operation. The admin must 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

The default location of the HyTrust DataControl configuration files.

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

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)