Install the CLI Toolkit
CipherTrust Manager includes a CLI toolkit, named ksctl, that can be downloaded and run locally to control a remote CipherTrust Manager.
Note
ksctl is designed to be run from a remote system, not on the CipherTrust Manager itself.
ksctl exclusively uses the REST API to communicate with CipherTrust Manager, so anything you can do with the CLI tool, you can also do directly with the REST API. Conversely, ksctl exposes most of the functionality of the REST API. It can perform management functions, such as adding users and groups, and end-user functions, such as creating keys.
To get started with ksctl you must do the following:
Download and unzip the ksctl_images.zip file.
Setup the ksctl-os file for your system. This includes setting some basic configuration variables for ksctl authentication.
(Optional) Further set ksctl configuration variables, if desired.
Download and unzip the ksctl_images.zip file
Enter the IP address of your CipherTrust Manager system in your browser.
If you are logged into CipherTrust Manager, select the API link at the top right. If you are logged out, select API & CLI Documentation at the bottom right.
Select the ** CLI Guide page and click on Download CLI** button:
Unzip the ksctl_images.zip file.
Example set of available images in ksctl_images.zip file:
Setup the ksctl-os for your system
The ksctl utility can be set up on Windows, Linux, and macOS.
Windows
After unzipping, rename
ksctl-win-amd64.exe
toksctl.exe
.Note
ksctl.exe is a single executable with no dependencies, so it can be run from anywhere.
Move the ksctl.exe file to a folder easily accessed by the local command prompt.
Note
You can also add the location of the ksctl.exe file to your PATH variable or copy ksctl.exe to a location already in your PATH.
Create a ksctl configuration file using the local command prompt cmd.exe:
Create a .ksctl directory in your %HOMEPATH% directory:
In the %HOMEPATH%.ksctl directory, create a config.yaml file with the following items:
Tip
Enter
set homepath
to find or confirm your %HOMEPATH% directory.
Linux
After unzipping, rename the file of choice to ksctl and move it to a directory within your PATH.
Note
ksctl can be run from any directory.
Create a ksctl configuration file:
Create a .ksctl directory in your $HOME directory:
In the $HOME/.ksctl directory create a config.yaml file with the following items:
Bash completions can be generated by typing ksctl bashcomp at the bash prompt and following the instructions.
macOS
After unzipping, rename ksctl-darwin-amd64 to ksctl and move it to a directory within your PATH.
In Finder, right-click or control-click the ksctl executable and select Open. You cannot open the executable by double-clicking.
Note
For some versions of macOS, a prompt appears indicating that macOS cannot verify the developer. You need to dismiss the prompt and navigate into Security & Privacy settings to manually allow ksctl.
On the prompt, click Open to proceed.
Create a ksctl configuration file:
Create a .ksctl directory in your $HOME directory:
In the $HOME/.ksctl directory create a config.yaml file with the following items:
Tip
Enter
env | grep HOME
to find your $HOME directory.
ksctl Configuration Variables
Summary of ksctl configuration variables for the config.yaml configuration file:
ksctl is easiest to use with the configuration file (config.yaml). However, those parameters can be overridden by using these flags on the command line:
Note
If
KSCTL_VERBOSITY
andKSCTL_NOSSLVERIFY
are set to true in the config.yaml file, you must use--verbose=false
or--nosslverify=false
flags to override them. This is because these two settings are boolean values.We recommend setting
KSCTL_TRUSTED_CA_FILE
andKSCTL_SERVER_NAME
to verify the CipherTrust Manager web interface server certificate. In most cases, ksctl communicates with the web interface. When the disk is encrypted and in the preboot stage, ksctl communicates with the preboot interface. In this state, we recommend using the--trusted-ca-file
and--server-name
flags to provide values matching the preboot interface certificate. It is also possible but not recommended to use--nosslverify
to skip certificate verification.
Run ksctl
Note
This is an example only; not all supported CLI commands and flags are shown.
At the command line prompt, enter ksctl. You will get the following example output:
Try creating a key by entering the command ksctl keys create –autoname:
This will create output similar to the following: