Get a Quote     (408) 943-4100   TrueNAS Discord VendOp_Icon_15x15px Commercial Support
TrueNAS.com Software Systems Company Community Security iX Portal Download
TrueNAS CORE TrueNAS Enterprise TrueNAS SCALE Compare Editions TrueCommand Software Status FreeNAS
Compare Systems F-Series M-Series X-Series R-Series Mini Series
About iXsystems Our Clients Reviews Careers Awards iX Blog & News iX Website Contact Us
Community Forum Discord TrueNAS GitHub TrueNAS Merch Store
Application Analytics Backup and Archival Cloud Data Mobility File Sharing iX Storj Media Creation Video Surveillance Virtualization
Industry Automotive Education Gaming Government Healthcare MSP Manufacturing Research & AI Media & Entertainment
Download TrueNAS CORE Download TrueNAS SCALE Get TrueNAS Enterprise Compare TrueNAS Editions Where to Buy
  1. Documentation Hub
  2. /
  3. TrueNAS SCALE
  4. /
  5. CLI Reference Guide
  6. /
  7. System
  8. /
  9. KMIP
Edit page
TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

KMIP

  7 minute read.

Last Modified 2024-03-15 13:07 EDT

Kmip Namespace

The kmip namespace has six commands and is based on system KMIP server creation and management functions found in the SCALE API and web UI. It provides access to KMIP server methods through the kmip commands.

Kmip Commands

The following kmip commands allow you to create new and manage existing KMIP server connections.

You can enter commands from the main CLI prompt or from the kmip namespace prompt.

Interactive Argument Editor (TUI)

Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).

Click for more information

The interactive argument editor is a text user interface (TUI) that can help enter complex commands with multiple configurable properties. It shows expected properties, defaults, input types (string, boolean, integer, or array), and can include command instructions or warnings.

Optional properties, indicated by the # symbol, are disabled by default. Required properties are enabled. Do not disable properties that are enabled by default.

To configure required properties, enter a space after the colon then add the value.

To enable optional properties, delete # from the corresponding line.

Some required properties are disabled if they are part of a pair of properties where one or the other is required. Select one property to enable and enter a value.

Press F2 or click Save to save the modified file.

Press F10, Esc, or click Quit to exit the TUI. The command automatically executes upon exit.

Clear_Sync_Pending_Keys command

Use the clear_sync_pending_keys command to clear any pending sync.

Using the Clear_Sync_Pending_Keys Command

Description

The clear_sync_pending_keys command does not require entering a property argument. Enter the command then press Enter. The command returns an empty line. Use the system kmip kmip_sync_pending command to verify if the sync is cleared.

Usage

From the CLI prompt, enter:

system kmip clear_sync_pending_keys

Command Example 
system kmip clear_sync_pending_keys

Config command

Use the config command to retrieve the KMIP server settings if one is configured.

Using the Config Command

Description

The config command does not require entering a property argument. Enter the command then press Enter. The command returns a dictionary with the system-assigned ID, server, ssl version, port number, manage SED and ZFS settings, and if the KMIP sever is enabled. It indicates a certificate and CA is configured but not the entire certificate string.

Usage

From the CLI prompt, enter:

system kmip config

Command Example 
system kmip config
+-----------------------+------------------+
|                    id | 1                |
|                server | <null>           |
|           ssl_version | PROTOCOL_TLSv1_2 |
|                  port | 5696             |
|      manage_sed_disks | false            |
|       manage_zfs_keys | false            |
|               enabled | false            |
|           certificate | <null>           |
| certificate_authority | <null>           |
+-----------------------+------------------+

Kmip_Sync_Pending command

Use the kmip_sync_pending command to verify if there is a pending sync.

Using the Kmip_Sync_Pending Command

Description

The kmip_sync_pending command does not require entering a property argument. Enter the command then press Enter. The command returns true if there is a pending sync or false if not.

Usage

From the CLI prompt, enter:

system kmip kmip_sync_pending

Command Example 
system kmip kmip_sync_pending
false

Ssl_Version_Choices command

Use the ssl_version_choices command to retrieve valid SSL version choices you can use when configuring KMIP service.

Using the Ssl_Version_Choices Command

Description

The ssl_version_choices command does not require entering a property argument. Enter the command then press Enter. The command returns an empty line.

Usage

From the CLI prompt, enter:

system kmip ssl_version_choices

Command Example 
system kmip ssl_version_choices
+------------------+------------------+
|   PROTOCOL_TLSv1 | PROTOCOL_TLSv1   |
| PROTOCOL_TLSv1_1 | PROTOCOL_TLSv1_1 |
| PROTOCOL_TLSv1_2 | PROTOCOL_TLSv1_2 |
+------------------+------------------+

Sync_Keys command

Use the sync_keys command to sync ZFS/SED keys between the KMIP server and TrueNAS SCALE database.

Using the Sync_keys Command

Description

The sync_keys command does not require entering a property argument. Enter the command then press Enter. The command returns an empty line. Use the system kmip kmip_sync_pending command to verify there is no longer a sync operation pending.

Usage

From the CLI prompt, enter:

system kmip sync_keys

Command Example 
system kmip sync_keys

Update Command

Use the update command to update the KMIP server settings.

Using the Update Command

Description

The update command has 11 property options. See Update Properties for details. Enter the property argument using the = delimiter to separate property and value. Double-quote values that include special characters. Enter the command string then press Enter. The command returns an empty line. Enter the system kmip config command to verify settings.

Update Properties
PropertyDescriptionSyntax Example
enabledSet to true to activate the KMIP configuration and begin syncing keys with the KMIP server. enabled, if true, cannot be set to disabled if there are existing keys pending to be synced. However, users can still perform this action by enabling force_clear.enabled="true/false"
manage_sed_disksSet to true to enabled and manage syncs keys from local database to remote KMIP server. Enabling this option allows the key server to manage creating or updating the global SED password, creating or updating individual SED passwords, and retrieving SED passwords when SEDs are unlocked. When set to false, if there are any keys left to be retrieved from the KMIP server, it syncs them back to local database. Disabling this option leaves SED password management with the local system.manage_sed_disks="true/false"
manage_zfs_keysSet to true enabled and syncs keys from local database to remote KMIP server. Use the KMIP server to manage ZFS encrypted dataset keys. The key server stores, applies, and destroys encryption keys whenever an encrypted dataset is created, when an existing key is modified, an encrypted dataset is unlocked, or an encrypted dataset is removed. When set to false, if there are any keys left to be retrieved from the KMIP server, it syncs them back to local database. Unsetting this option leaves all encryption key management with the local system.manage_zfs_keys="true/false"
certificateUse the UI to import the certificate for the KMIP server. Next use the system certificate query command to locate then enter the system-assigned certificate ID as the value. The system authenticates connection with remote KMIP Server with a TLS handshake. A valid certificate and certificate_authority are required to verify the key server connection. WARNING: for security reasons, protect the Certificate used for key server authentication.certificate="true/false"
certificate_authorityUse the UI to import the certificate authority (CA) for the KMIP server. Next use the system certificate query command to locate then enter the system-assigned CA ID as the value. certificate_authority determines the certs to use to initiate the TLS handshake with server. A valid certificate and certificate_authority are required to authenticate the connection. WARNING: for security reasons, protect the certificate authority used for key server authentication.certificate_authority="true/false"
portEnter a connection port number on the central key server. Default is 5695.port="5695"
serverEnter the host name or IP address of the central key server.server="hostname.com"
ssl_versionEnter the option that matches the ssl configuration used by KMIP server. Options are: PROTOCOL_TLSv1, PROTOCOL_TLSv1_1, or PROTOCOL_TLSv1_2.ssl_version="PROTOCOL_TLSv1"
force_clearEnter true to cancel any pending key synchronization. Set change_server to true to allow users to migrate data between two KMIP servers. The system first migrates keys from old KMIP server to the local database, then migrates the keys from local database to the new KMIP server. If not able to retrieve all the keys from old server, this command fails.force_clear="true/false"
change_serverSet change_server to true to allow users to migrate data between two KMIP servers. The system first migrates keys from the old KMIP server to the local database, then migrate the keys from local database to a new KMIP server. If not able to retrieve all the keys from the old server, this command fails. You can bypass this by setting force_clear to true.change_server="true/false"
validateSet to true by default. When enabled, the system tests the connection to the server and verifies the certificate chain. To use this command, configure the server and port values, then enter a certificate and certificate_authority.validate="true/false"

Usage

From the CLI prompt, enter:

system kmip update enabled=true

Where:

  • true enables the KMIP server.

Command Example 
system kmip update enabled=true

Related Content

SCALE Tutorials
SCALE UI Reference

Have more questions?

For further discussion or assistance, see these resources:

Found content that needs an update?  You can suggest content changes directly! To request changes to this content, click the Feedback button located on the middle-right side of the page (might require disabling ad blocking plugins).