sshcheckreceiver

README

SSH Check Receiver

This receiver creates stats by connecting to an SSH server which may be an SFTP server.

Status
Stability	beta: metrics
Distributions	contrib
Issues
Code coverage
Code Owners	@ishaish103
Emeritus	@nslaughter

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

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:

receivers:
  sshcheck:
    endpoint: localhost:2222
    username: otelu
    password: $OTELP
    collection_interval: 60s

SSH check with key file authentication:

receivers:
  sshcheck:
    endpoint: sftp.example.com:22
    username: monitoring
    key_file: /path/to/private_key
    collection_interval: 60s

SSH check with SFTP monitoring enabled:

receivers:
  sshcheck:
    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:

receivers:
  sshcheck:
    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: [sshcheck]
      processors: [batch]
      exporters: [otlp_grpc]

The full list of settings exposed for this receiver are documented in config.go with detailed sample configurations in 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.

receivers:
  sshcheck:
    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):

receivers:
  sshcheck:
    check_sftp: true

1. By enabling SFTP metrics individually:

receivers:
  sshcheck:
    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.

receivers:
  sshcheck:
    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 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

receivers:
  sshcheck:
    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.

receivers:
  sshcheck:
    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.

Limitations and 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 and metadata.yaml.

Documentation

Index

• func NewFactory() receiver.Factory
• type Config
  • func (c Config) SFTPEnabled() bool
  • func (c Config) Validate() (err error)

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a new receiver factory

Types

type Config

type Config struct {
	scraperhelper.ControllerConfig `mapstructure:",squash"`
	configssh.SSHClientSettings    `mapstructure:",squash"`

	CheckSFTP            bool                          `mapstructure:"check_sftp"`
	MetricsBuilderConfig metadata.MetricsBuilderConfig `mapstructure:",squash"`
}

func (Config) SFTPEnabled

func (c Config) SFTPEnabled() bool

SFTPEnabled tells whether SFTP metrics are Enabled in MetricsSettings.

func (Config) Validate

func (c Config) Validate() (err error)