# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/virtual-hsm/cli/security-and-encryption/vhsm-ssh.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.