vhsm ssh

The vhsm ssh command establishes an SSH connection to a target machine using an SSH secrets engine for authentication. It automatically authenticates and initiates an SSH connection to the host.

This command requires:

• The SSH secrets engine to be mounted and configured.

• A local installation of ssh.

Syntax

vhsm ssh [options] user@<target_host>

Examples

Example 1: SSH using OTP mode (requires sshpass for full automation)

vhsm ssh -mode=otp -role=my-role [email protected]

Example2: SSH using CA mode

vhsm ssh -mode=ca -role=my-role [email protected]

Example 3: SSH using CA mode with host key verification

vhsm ssh \
    -mode=ca \
    -role=my-role \
    -host-key-mount-point=host-signer \
    -host-key-hostnames=example.com \
    [email protected]

For detailed guides on each authentication method, refer to the corresponding SSH secrets engine documentation.

---

Options

Output Options

Flag	Description	Default
-field (string)	Prints only the specified field in the format set by -format. No trailing newline is added.	""
-format (string)	Specifies the output format: table, json, or yaml. Can also be set via the VAULT_FORMAT environment variable.	"table"

SSH Options

Flag	Description	Default
-mode (string)	Authentication mode to use: ca, dynamic, or otp.	""
-mount-point (string)	Mount point of the SSH secrets engine.	"ssh/"
-no-exec (bool)	Prints generated credentials without establishing an SSH connection.	false
-role (string)	Role name used for key generation.	""
-strict-host-key-checking (string)	Defines SSH StrictHostKeyChecking behavior. Default is "ask". Can also be set via VAULT_SSH_STRICT_HOST_KEY_CHECKING environment variable.	"ask"
-user-known-hosts-file (string)	Path to the UserKnownHostsFile for SSH. Can also be set via VAULT_SSH_USER_KNOWN_HOSTS_FILE environment variable.	"~/.ssh/known_hosts"

CA Mode Options

Flag	Description	Default
-host-key-hostnames (string)	Comma-separated list of hostnames allowed for the CA. "*" allows all domains and IPs. Can also be set via VAULT_SSH_HOST_KEY_HOSTNAMES environment variable.	"*"
-host-key-mount-point (string)	SSH secrets engine mount point for host key signing. If set, vHSM generates a custom known_hosts file for strict key verification. Can also be set via VAULT_SSH_HOST_KEY_MOUNT_POINT environment variable.	""
-private-key-path (string)	Path to the private SSH key for authentication.	"~/.ssh/id_rsa"
-public-key-path (string)	Path to the public SSH key sent to vHSM for signing.	"~/.ssh/id_rsa.pub"

---

Notes

• By default, vhsm ssh provides an SSH-like experience by executing the local ssh command with the necessary credentials.

• The -no-exec flag can be used to retrieve credentials without initiating the connection.

• The -mode flag determines the authentication method:

  • otp: Uses a one-time password (OTP) for authentication.

  • ca: Uses a certificate authority (CA) to sign SSH keys.

  • dynamic: Retrieves dynamically generated SSH credentials.