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)
      --skip-img-verify            Install without enforcing image signature verification. The VSatellite starts in detection mode.
      --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.

Skip image signature verification

New installations enforce image signature verification by default, so that VSatellite workloads start only if their container image was published and signed by a trusted source.

Use the --skip-img-verify flag to install without enforcing verification:

sudo vsatctl install --skip-img-verify --pairing-code=<pairing-code>

The VSatellite starts in detection mode. Verification still runs and is logged, but no pods are blocked.

Important

Use this option only as a temporary workaround, and only when advised to. Detection mode leaves the VSatellite without the protection that image signature verification provides.

This setting persists across VSatellite updates, so a VSatellite installed with --skip-img-verify stays in detection mode until you turn enforcement back on. To turn enforcement back on after installation, run vsatctl img-verify true.

For more information, see About image signature verification.

HSM-protected DEK options

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

Option Required Description
--label Yes HSM slot/partition label
--serial-number No Required only if multiple slots/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