> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Sshcheck

> OpenTelemetry receiver for Sshcheck

# Sshcheck Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@ishaish103](https://github.com/ishaish103)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/sshcheckreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-beta-green)

## Overview

## Prerequisites

If `ignore_host_key` is not set then host key validation requires the agent either have a known\_hosts file at a path specified by setting `known_hosts` or at default paths indicated by ssh man pages: \$HOME/.ssh/known\_hosts or /etc/ssh/known\_hosts.

## Configuration

> **Note:** This receiver was renamed from `sshcheck` to `ssh_check` to match the snake\_case naming convention.
> The deprecated component type `sshcheck` is still accepted as an alias and will log a deprecation warning.

The following settings are required:

* `endpoint`
* `username`
* `password` or `key_file`

Either `password` or `key_file` must be set. But if both are set then password is treated as the `passphrase` and the key is assumed to be encrypted.

The following settings are optional:

* `collection_interval` (default = `60s`): This receiver collects metrics on an interval. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
* `known_hosts` (default = ssh defaults): The path to the known\_hosts file. If this isn't set then default locations are checked at `$HOME/.ssh/known_hosts` and `/etc/ssh/known_hosts`.
* `ignore_host_key` (default = false): Can override conventional ssh security for use cases like tests where authentication via the known\_hosts file isn't required.

### Example Configuration

**Basic SSH check with password authentication:**

```yaml theme={null}
receivers:
  ssh_check:
    endpoint: localhost:2222
    username: otelu
    password: $OTELP
    collection_interval: 60s
```

**SSH check with key file authentication:**

```yaml theme={null}
receivers:
  ssh_check:
    endpoint: sftp.example.com:22
    username: monitoring
    key_file: /path/to/private_key
    collection_interval: 60s
```

**SSH check with SFTP monitoring enabled:**

```yaml theme={null}
receivers:
  ssh_check:
    endpoint: sftp.example.com:22
    username: monitoring
    key_file: /path/to/private_key
    check_sftp: true
    collection_interval: 60s
```

**Production-ready configuration with processors and exporters:**

```yaml theme={null}
receivers:
  ssh_check:
    endpoint: production-server.example.com:22
    username: monitoring
    key_file: /etc/otel/ssh_monitoring_key
    collection_interval: 30s
    timeout: 5s
    known_hosts: /etc/otel/known_hosts

processors:
  batch:
    timeout: 10s
    send_batch_size: 100

exporters:
  otlp_grpc:
    endpoint: otel-collector:4317

service:
  pipelines:
    metrics:
      receivers: [ssh_check]
      processors: [batch]
      exporters: [otlp_grpc]
```

The full list of settings exposed for this receiver are documented in [config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/sshcheckreceiver/config.go) with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/sshcheckreceiver/testdata/config.yaml).

## Advanced Configuration

### Timeout Configuration

The `timeout` option controls how long the receiver waits for an SSH connection to establish. The default is `10s`. This timeout applies to both SSH and SFTP connection attempts.

```yaml theme={null}
receivers:
  ssh_check:
    endpoint: slow-server.example.com:22
    username: user
    password: pass
    timeout: 30s  # Increase timeout for slow connections
```

### SFTP Check Configuration

SFTP checks can be enabled in two ways:

1. **Using the `check_sftp` option** (enables SFTP status and duration metrics):

```yaml theme={null}
receivers:
  ssh_check:
    check_sftp: true
```

2. **By enabling SFTP metrics individually**:

```yaml theme={null}
receivers:
  ssh_check:
    metrics:
      sshcheck.sftp_duration:
        enabled: true
      sshcheck.sftp_status:
        enabled: true
```

When `check_sftp` is enabled or SFTP metrics are individually enabled, the receiver will attempt to establish an SFTP connection after a successful SSH connection. Note that SFTP checks require a successful SSH connection first (see Limitations section).

### Metric Enable/Disable Configuration

Individual metrics can be enabled or disabled using the `metrics` configuration section. By default, all SSH metrics are enabled and all SFTP metrics are disabled.

```yaml theme={null}
receivers:
  ssh_check:
    endpoint: localhost:2222
    username: user
    password: pass
    metrics:
      sshcheck.duration:
        enabled: true  # Default: true
      sshcheck.status:
        enabled: true  # Default: true
      sshcheck.error:
        enabled: true  # Default: true
      sshcheck.sftp_duration:
        enabled: false  # Default: false
      sshcheck.sftp_status:
        enabled: false  # Default: false
      sshcheck.sftp_error:
        enabled: false  # Default: false
```

See [metadata.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/sshcheckreceiver/metadata.yaml) for the complete list of available metrics and their default states.

### Known Hosts Configuration

The `known_hosts` option specifies the path to the SSH known\_hosts file for host key validation. If not specified, the receiver checks default locations:

* `$HOME/.ssh/known_hosts`
* `/etc/ssh/known_hosts`

```yaml theme={null}
receivers:
  ssh_check:
    endpoint: server.example.com:22
    username: user
    key_file: /path/to/key
    known_hosts: /custom/path/to/known_hosts
```

### Security Considerations

The `ignore_host_key` option disables host key validation. **This should only be used in test environments** as it makes the connection vulnerable to man-in-the-middle attacks.

```yaml theme={null}
receivers:
  ssh_check:
    ignore_host_key: true  # ⚠️ Only for testing!
```

For production use, always configure proper host key validation using `known_hosts` or ensure the host key is in the default known\_hosts locations.

## Warnings

### Security

* **Authentication**: Passwords in configuration files should be stored securely. Consider using environment variables or secret management systems. Key file authentication is recommended for production use.

### Performance

* **Connection Overhead**: Each check creates a new SSH connection. The `collection_interval` should be configured based on your monitoring needs and the impact on the SSH server. More frequent checks (e.g., every 10 seconds) will create more connections.

* **Timeout Behavior**: If a connection times out, it will be retried on the next collection interval. Ensure your `timeout` value is appropriate for your network conditions.

## Feature Gates

This receiver does not currently use any feature gates. All functionality is available through configuration options.

## Metrics

This receiver produces the following metrics:

| Metric Name              | Type  | Description                                         | Unit     | Enabled by Default |
| ------------------------ | ----- | --------------------------------------------------- | -------- | ------------------ |
| `sshcheck.duration`      | Gauge | Measures the duration of SSH connection             | ms       | Yes                |
| `sshcheck.status`        | Sum   | 1 if SSH client successfully connected, otherwise 0 | 1        | Yes                |
| `sshcheck.error`         | Sum   | Records errors occurring during SSH check           | \{error} | Yes                |
| `sshcheck.sftp_duration` | Gauge | Measures SFTP request duration                      | ms       | No                 |
| `sshcheck.sftp_status`   | Sum   | 1 if SFTP server replied to request, otherwise 0    | 1        | No                 |
| `sshcheck.sftp_error`    | Sum   | Records errors occurring during SFTP check          | \{error} | No                 |

### Resource Attributes

The receiver adds the following resource attribute:

* `ssh.endpoint`: The full SSH endpoint being monitored (disabled by default, can be enabled in metadata.yaml)

### Detailed Metric Documentation

Complete details about the metrics produced by this receiver, including attributes, types, and units, can be found in [documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/sshcheckreceiver/documentation.md) and [metadata.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/sshcheckreceiver/metadata.yaml).

## Metrics

| Metric Name                | Description                                              | Unit     | Type          | Attributes    |
| -------------------------- | -------------------------------------------------------- | -------- | ------------- | ------------- |
| ✅ `sshcheck.duration`      | Measures the duration of SSH connection.                 | ms       | Gauge         |               |
| ✅ `sshcheck.error`         | Records errors occurring during SSH check.               | \{error} | UpDownCounter | error.message |
| ❌ `sshcheck.sftp_duration` | Measures SFTP request duration.                          | ms       | Gauge         |               |
| ❌ `sshcheck.sftp_error`    | Records errors occurring during SFTP check.              | \{error} | UpDownCounter | error.message |
| ❌ `sshcheck.sftp_status`   | 1 if the SFTP server replied to request, otherwise 0.    | 1        | UpDownCounter |               |
| ✅ `sshcheck.status`        | 1 if the SSH client successfully connected, otherwise 0. | 1        | UpDownCounter |               |

## Attributes

| Attribute Name  | Description                         | Type   | Values |
| --------------- | ----------------------------------- | ------ | ------ |
| `error.message` | Error message recorded during check | string |        |

## Resource Attributes

| Attribute Name | Description       | Type   | Enabled |
| -------------- | ----------------- | ------ | ------- |
| `ssh.endpoint` | Full SSH endpoint | string | ❌       |

## Configuration

### Example Configuration

```yaml theme={null}
receivers:
  ssh_check:
    endpoint: notdefault:1313
    username: notdefault_username
    password: notdefault_password
    key_file: notdefault/path/keyfile
    collection_interval: 10s
    known_hosts: path/to/collector_known_hosts
    ignore_host_key: false

processors:
  nop:

exporters:
  nop:

service:
  pipelines:
    metrics:
     receivers: [ssh_check]
     processors: [nop]
     exporters: [nop]
```

***

*Last generated: 2026-07-06*