Metrics

ContainerSSH contains a Prometheus-compatible metrics server which can be enabled using the following configuration:

metrics:
  <options here>

The metrics server has the following options:

Option	Type	Description
`enable`	`bool`	Enable metrics server. Defaults to false.
`path`	`string`	HTTP path to serve metrics on. Defaults to `/metrics`.
`listen`	`string`	IP and port to listen on. Defaults to `0.0.0.0:9100`.
`clientcacert`	`string`	CA certificate in PEM format or filename that contains the CA certificate used for authenticating connecting clients.
`cert`	`string`	Client certificate in PEM format or filename that contains the server certificate.
`key`	`string`	Private key in PEM format or filename that contains the server certificate.
`tlsVersion`	`[]string`	Minimum TLS version to support. See the TLS version section below.
`curve`	`[]string`	Elliptic curve algorithms to support. See the Elliptic curve algorithms section below.
`cipher`	`[]string,string`	Which cipher suites to support. See the Cipher suites section below.

Available metrics¶

You can configure Prometheus to grab the following metrics:

containerssh_auth_server_failures: Number of failed requests to the authentication server since start.
containerssh_auth_success: Number of successful authentications since start. Contains labels for authtype (password or pubkey) and country (see below).
containerssh_auth_failures: Number of failed authentications since start. Contains labels for authtype (password or pubkey) and country (see below).
containerssh_config_server_failures: Number of failed requests to the configuration server since start.
containerssh_ssh_connections: Number of SSH connections since start. Contains a label for country (see below).
containerssh_ssh_handshake_successful: Number of successful SSH handshakes since start. Contains a label for country (see below).
containerssh_ssh_handshake_failed: Number of failed SSH handshakes since start. Contains a label for country (see below).
containerssh_ssh_current_connections: Number of currently open SSH connections. Contains a label for country (see below).

Country identification¶

Country identification works using GeoIP2 or GeoLite2 from MaxMind. This database needs to be provided to ContainerSSH externally due to licensing concerns.

The default path for the GeoIP database is /var/lib/GeoIP/GeoIP2-Country.mmdb, but you can change that using the following configuration snippet:

geoip:
  provider: "maxmind"
  maxmind-geoip2-file: '/var/lib/GeoIP/GeoIP2-Country.mmdb'

Configuring TLS¶

TLS ensures that the connection between ContainerSSH and the configuration server cannot be intercepted using a Man-in-the-Mittle attack. We recommend checking the Mozilla Wiki for information about which configuration can be considered secure.

TLS version¶

The minimum supported TLS version can be configured using the tlsVersion option. It defaults to 1.3 and also supports 1.2. Versions lower than 1.2 are not supported.

Elliptic curve algorithms¶

The elliptic curve algorithms can be specified in the curve option. We support and default to the following options:

x25519
secp256r1
secp384r1
secp521r1

Cipher suites¶

The following cipher suites are supported in ContainerSSH:

Suite	Default
TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305

Client authentication¶

In order to safeguard the metrics ContainerSSH supports authenticating connecting clients using x509 mutual TLS authentication. For this you will need to generate a CA certificate and configure the metrics service with it, as well as client certificates that your connecting clients must use.

We recommend using cfssl for creating the CA infrastructure. First we need to create the CA certificates:

cat > ca-config.json <<EOF
{
  "signing": {
    "default": {
      "expiry": "8760h"
    },
    "profiles": {
      "containerssh": {
        "usages": ["signing", "key encipherment", "server auth", "client auth"],
        "expiry": "8760h"
      }
    }
  }
}
EOF

cat > ca-csr.json <<EOF
{
  "CN": "ContainerSSH CA",
  "key": {
    "algo": "rsa",
    "size": 4096
  },
  "names": [
    {
      "C": "Your Country Code",
      "L": "Your Locality",
      "O": "Your Company",
      "OU": "",
      "ST": "Your State"
    }
  ]
}
EOF

cfssl gencert -initca ca-csr.json | cfssljson -bare ca

The resulting ca.pem should be added to the metrics configuration:

metrics:
  clientcacert: /path/to/ca.pem

Then we can create the client certificate:

cat > containerssh-csr.json <<EOF
{
  "CN": "ContainerSSH",
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "names": [
    {
      "C": "Your Country Code",
      "L": "Your Locality",
      "O": "Your Company",
      "OU": "",
      "ST": "Your State"
    }
  ]
}
EOF

cfssl gencert \
  -ca=ca.pem \
  -ca-key=ca-key.pem \
  -config=ca-config.json \
  -profile=containerssh \
  containerssh-csr.json | cfssljson -bare containerssh

The resulting containerssh.pem and containerssh-key.pem can be used in your connecting client. For an example see the Prometheus documentation.