Skip to content

vsatctl install

vsatctl install [flags]

Install a single node Venafi VSatellite cluster.

Note

This command must be run with root privileges because it installs system wide executables and configuration files in '/etc' and '/usr/local/bin'. It requires root privileges to start the VSatellite systemd service. It connects to the VSatellite cluster using credentials from a file which is only accessible to root users.

Important

When using --install-dir, carefully review related hard disk requirements

Examples

sudo vsatctl install --pairing-code=cf216fbc-f429-41f1-a64b-f06bb9b4e1be

Restore a DEK from a backup file during installation of the first VSatellite :

sudo vsatctl install --pairing-code=<pairing-code> --dek=<path-to-dek-backup-file>

Options

      --accept-license-agreement   Accept the Venafi End User License Agreement. (https://venafi.com/end-user-license-agreement)
      --api-url string             Specify the Venafi Cloud API URL. (Default: https://api.venafi.cloud)
      --dek string                 Provide a DEK backup file to restore the Data Encryption Key during installation of the first VSatellite.
  -h, --help                       Show help for the install command.
      --install-dir string         Specify the directory for all VSatellite installation artifacts.
      --loglevel string            Set the file logging level. Options: "INFO," "ERROR," "WARN," "DEBUG." (Default: "DEBUG")
      --pairing-code string        Provide the pairing code to register with Venafi as a Service.
      --silent                     Perform a silent Kubernetes installation without showing events or progress. (Deprecated)
      --timeout-seconds int        Set the maximum timeout in seconds for each VSatellite service installation. (Default: 180)

Restore DEK from backup file

Use the --dek flag to restore a previously generated Data Encryption Key (DEK) during installation.

When the --dek flag is provided, the VSatellite restores the DEK from the specified backup file instead of generating a new DEK.

When to use this option

Use this option only when installing the first VSatellite in CyberArk Certificate Manager - SaaS .

This scenario applies when:

  • All VSatellites have been deleted in the Certificate Manager - SaaS UI.
  • You need to restore access to previously encrypted data.
  • You have a valid DEK backup file from a previous VSatellite deployment.

Restoring the DEK ensures that the newly installed VSatellite can access existing encrypted data instead of creating a new encryption key.

Important

The --dek flag works only when no VSatellites exist in Certificate Manager - SaaS. If at least one VSatellite already exists in Certificate Manager - SaaS, the installation fails and an error message is displayed in the terminal. This restriction prevents the creation of multiple DEKs within the same environment.

Note

If a VSatellite entry exists in Certificate Manager - SaaS but its status is Lost connection, do not use --dek. Instead, follow the standard VSatellite recovery procedure.

HSM-protected DEK options

When installing a VSatellite with HSM-protected DEK, the following options are required unless otherwise noted:

Option Required Description
--partition-label Yes HSM partition label
--partition-serial-number No Required only if multiple partitions share the same label
--hsm-client-path Yes Path to the HSM client installation
--hsm-lib-path Yes Path to the PKCS#11 library
--hsm-config Yes Path to the HSM client configuration file

Note

During installation, you are prompted to enter the PIN for the HSM partition. Ensure that the PIN is available before starting the installation.

For an explanation of each HSM-related parameter and example values, see Using HSM-protected DEK with VSatellites.

Note

HSM connectivity and credentials are not fully validated during installation. In some cases, installation may succeed but the VSatellite enters an Unhealthy state. For details about HSM validation behavior and Unhealthy states, see

Using HSM-protected DEK with VSatellites.

See also