> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/virtual-hsm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/virtual-hsm/cli/security-and-encryption/vhsm-ssh.md).

# 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

```sh
vhsm ssh [options] user@<target_host>
```

### Examples

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

```sh
vhsm ssh -mode=otp -role=my-role user@1.2.3.4
```

#### Example2: SSH using CA mode

```sh
vhsm ssh -mode=ca -role=my-role user@1.2.3.4
```

#### Example 3: SSH using CA mode with host key verification

```sh
vhsm ssh \
    -mode=ca \
    -role=my-role \
    -host-key-mount-point=host-signer \
    -host-key-hostnames=example.com \
    user@example.com
```

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.