Initial documentation update for v0.5 release

docs/reference/upcoming/auth-oauth2.md

@@ -4,6 +4,9 @@ title: oAuth2 authentication
 
 {{ reference_upcoming() }}
 
+!!! warning "Feature Preview"
+    oAuth2 support is considered as a feature preview as it doesn't have adequate test coverate
+
 This page details setting up the oAuth2 authentication for ContainerSSH. oAuth2 uses the keyboard-interactive authentication mechanism, which is supported by most, but not all SSH clients. ContainerSSH supports GitHub, GitHub Enterprise, and OIDC-compliant oAuth2 servers for authentication (such as KeyCloak, Microsoft Active Directory Federation Services, etc).
 
 ## Supported clients
@@ -15,31 +18,28 @@ We have tested the following clients and know them to work:
 - WinSCP
 - Filezilla
 
-## Configuration
-
-
-
 ## Configuration
 
 The configuration structure for OAuth2 authentication looks as follows:
 
 ```yaml
 auth:
-  method: oauth2
-  oauth2:
-    clientId: "client ID string"
-    clientSecret: "client secret string"
-    provider: oidc|github
-    github:
-      <GitHub configuration>
-    oidc:
-      <OIDC configuration>
-    qrCodeClients:
-      - <Client version string regexps that should be sent an ASCII QR code>
-    deviceFlowClients:
-      - <Client version string regexps to use the device flow with>
-    redirect:
-      <configuration for the redirect server>
+  keyboardInteractive:
+    method: oauth2
+    oauth2:
+      clientId: "client ID string"
+      clientSecret: "client secret string"
+      provider: oidc|github
+      github:
+        <GitHub configuration>
+      oidc:
+        <OIDC configuration>
+      qrCodeClients:
+        - <Client version string regexps that should be sent an ASCII QR code>
+      deviceFlowClients:
+        - <Client version string regexps to use the device flow with>
+      redirect:
+        <configuration for the redirect server>
 ```
 
 ## Client credentials
@@ -52,6 +52,14 @@ Currently, we support OIDC and GitHub as providers of OAuth2-based authenticatio
 
 ### OIDC configuration
 
+OpenID Connect (OIDC) is a popular authentication protocol used for Single-Sign-On. It is supported in popular authentication products such as Keycloak and Microsoft Active Directory Federation Services. The ContainerSSH OIDC provider allows users to authenticate using the same single sign on infrastructure as any web-based service. When a user connects, ContainerSSH will provide the user with the configured OIDC servers authentication url to click on and authenticate. There are two different supported OIDC authentication flows that can be used, the usual authorization flow and the device flow.
+
+### OIDC Device Flow
+
+
+
+### OIDC Authorization Flow
+
 ```yaml
 auth:
   oauth2:
@@ -66,6 +74,8 @@ The following configuration options are supported:
 |--------|------|-------------|
 | `deviceFlow` | `bool` | Use device flow when authenticating. Defaults to true. |
 | `authorizationCodeFlow` | `bool` | Use authorization code flow when authenticating. Defaults to true. |
+| `usernameField` | `string` | The field from the result of the userinfo OIDC endpoint to use as the username. Defaults to `sub` |
+| `redirectURI` | 
 
 The device flow takes precedence over the authorization code flow if enabled.
 

docs/reference/upcoming/auth-webhook.md

@@ -26,12 +26,14 @@ must be provided.
 
 The authentication webhook is a simple JSON `POST` request to which the server must respond with a JSON response.
 
-!!! note We have an [OpenAPI document](../api/authconfig) available for the authentication and configuration server. You
-can check the exact values available there, or use the OpenAPI document to generate parts of your server code.
+!!! note
+    We have an [OpenAPI document](../api/authconfig) available for the authentication and configuration server. You can check the exact values available there, or use the OpenAPI document to generate parts of your server code.
 
-!!! tip We provide a [Go library](https://github.com/ContainerSSH/libcontainerssh) to create an authentication server.
+!!! tip
+    We provide a [Go library](https://github.com/ContainerSSH/libcontainerssh) to create an authentication server.
 
-!!! warning A warning about rate limiting: if the authentication server desires to do rate limiting for connecting users
+!!! warning
+    A warning about rate limiting: if the authentication server desires to do rate limiting for connecting users
 it should take into account that a user is allowed to try multiple authentication attempts (currently hard-coded to 6
 per connection) before they are disconnected. Some of the authentication attempts (e.g. public keys) happen
 automatically on the client side without the user having any influence on them. Furthermore, ContainerSSH retries failed
@@ -101,7 +103,11 @@ When the separate authorization webhook is configured, you will receive a separa
 
 ### Response
 
-Both endpoints need to respond with an `application/json` response of the following content:
+When responding the authentication server has the opportunity to define extra metadata, environment variables or files for the user connection. All three are forwarded to all following requests (e.g. webhook -> authz -> config) made and can be used to influence authentication or configuration decisions, the environment variables are added to the users environment when the connection is established and the files are placed in the container before the users command executes.
+
+If any metadata, environment variables or files are marked as sensitive they will not be re-transmitted with further webhook calls but they will be taken account of and added to the users environment or, in case of files, placed in the container. This can be used to limit exposure in case the file contains sensitive information e.g. users credentials.
+
+All endpoints need to respond with an `application/json` response of the following content:
 
 ```json
 {
@@ -128,5 +134,6 @@ Both endpoints need to respond with an `application/json` response of the follow
 }
 ```
 
-!!! tip We provide a [Go library to implement an authentication server](https://github.com/containerssh/libcontainerssh).
+!!! tip
+    We provide a [Go library to implement an authentication server](https://github.com/containerssh/libcontainerssh).
 

docs/reference/upcoming/auth.md

@@ -40,10 +40,9 @@ At first glance keyboard-interactive authentication is very similar to password
 method the SSH server can provide customized questions to the client, to which the user has to provide answers. There
 can also be multiple consecutive questions and answers.
 
-### GSSAPI
+### GSSAPI / Kerberos
 
-GSSAPI is a cryptographic authentication method that is embedded into the SSH encryption itself. It is mainly used as
-part of Kerberos authentication. This is often used in corporate systems to auto-login users.
+GSSAPI is a generic authentication interface for peer-to-peer authentication. It is mainly used as part of Kerberos authentication, which is the only implementation supported by ContainerSSH. It is often used in corporate environment to authenticate using existing Active-Directory or FreeIPA systems and support passwordless authentication.
 
 ## Authentication backends supported by ContainerSSH
 
@@ -60,8 +59,8 @@ method is always tied to one backend.
 
 ## Authorization
 
-ContainerSSH offers a separate webhook to process authorization after the authentication is complete. This is a
-webhook-only feature that lets you compare the username entered in SSH and the username that has been authenticated.
+ContainerSSH offers a separate webhook to process authorization after the authentication is complete. This lets you
+compare the username entered in SSH and the username that has been authenticated.
 
 This is especially useful for non-webhook authentication methods, such as Kerberos and oAuth2. The details of the
 authorization protocol are described on the [webhook page](auth-webhook.md).

docs/reference/upcoming/configserver.md

@@ -11,7 +11,7 @@ ContainerSSH has the ability to configure the backend, and the launched containe
 The configserver webhook can be configured in the main configuration using the following structure:
 
 ```yaml
-configuration:
+configserver:
   <options>
 ```
 

docs/reference/upcoming/health.md

@@ -2,7 +2,7 @@
 
 {{ reference_upcoming() }}
 
-The health check endpoint is an HTTP server that returns `ok` and a 200 status code only if all ContainerSSH services are running. This can be used to integrate ContainerSSH with a load balancer.
+The health check endpoint is an HTTP server that returns `ok` and a 200 status code only if all ContainerSSH services are running. This can be used to integrate ContainerSSH with a load balancer. In any other case it'll return "not ok" and a 503 status code.
 
 The health check endpoint has the following options:
 

docs/reference/upcoming/index.md

@@ -94,8 +94,72 @@ Any X11 applications launched within the container will be visible on the local
 
 ## SSH keepalives
 
+Explicit support has been added for SSH KeepAlives. Previously, keepalives received from the client would wield an unknown global command warning and flood the logs, keepalives are now handled transparently and do not generate a warning.
+
+Additionally, support has been added to send keepalives to all clients from the server at a pre-defined interval. This can be configured with the following parameters:
+
+```yaml
+ssh:
+    // The interval that keepalive messages are sent to each client, defaults to 0 which disables the feature (no keepalives are sent).
+    clientAliveInterval: 10s
+    // The number of unanswered keepalives before ContainerSSH considers a client unresponsive and kills the connection, defaults to 3.
+    clientAliveCountMax: 3
+```
+
+This can be useful if ContainerSSH is sitting behind a load balancer which automatically kills idle connections after a pre-defined interval. A keepalive will keep the connection active as long as the client is responsive.
+
 ## Health check endpoint
 
+A new health check service has been created that can be used with Kubernetes or loadbalancers to automatically remove unhealthy ContainerSSH instances from the pool.
+
+[Read more »](health.md){: .md-button}
+
 ## Bugfixes to the Prometheus integration
 
-## Removal of the deprecated DockerRun and KubeRun backends
+The name of some prometheus metrics and units has been altered to adhere to the convension of the metric name ending with the unit.
+
+In detail the following metrics have been modified:
+
+* `containerssh_auth_server_requests`:
+    - Name changed to `containerssh_auth_server_requests_total`
+    - Unit name change from `requests` to `requests_total`
+* `containerssh_auth_server_failures`: 
+    - Name changed to `containerssh_auth_server_failures_total`
+    - Unit name change from `requests` to `failures_total`
+* `containerssh_auth_success`: 
+    - Name changed to `containerssh_auth_success_total`
+    - Unit name change from `requests` to `success_total`
+* `containerssh_auth_failures`:
+    - Name changed to `containerssh_auth_failures_total`
+    - Unit name change from `requests` to `failures_total`
+
+
+* `containerssh_backend_requests`:
+    - Name changed to `containerssh_backend_requests_total`
+    - Unit name change from `requests` to `requests_total`
+* `containerssh_backend_errors`:
+    - Name changed to `containerssh_backend_errors_total`
+    - Unit name change from `requests` to `errors_total`
+
+
+* `containerssh_config_server_requests`:
+    - Name changed to `containerssh_config_server_requests_total`
+    - Unit name change from `requests` to `requests_total`
+* `containerssh_config_server_failures`:
+    - Name changed to `containerssh_config_server_failures_total`
+    - Unit name change from `requests` to `failures_total`
+
+* `containerssh_ssh_connections`:
+    - Name changed to `containerssh_ssh_connections_total`
+    - Unit name change from `connections` to `connections_total`
+* `containerssh_ssh_handshake_successful`:
+    - Name changed to `containerssh_ssh_successful_handshakes_total`
+    - Unit name change from `handshakes` to `handshakes_total`
+* `containerssh_ssh_handshake_failed`:
+    - Name changed to `containerssh_ssh_failed_handshakes_total`
+    - Unit name change from `handshakes` to `handshakes_total`
+
+
+## Removal of the deprecated DockerRun and KubeRun backends
+
+Following the deprecation notice in the previous versions, the dockerrun and kuberun backends have been removed. The updated [docker](./docker.md) and [kubernetes](./kubernetes.md) backends should be used instead.

docs/reference/upcoming/installation.md

@@ -14,7 +14,10 @@
       hostkeys:
         - /path/to/your/host.key
     auth:
-      url: http://your-auth-server/
+      password:
+        method: webhook
+        webhook:
+          url: http://your-auth-server/
     ```
 
     !!! tip
@@ -34,7 +37,10 @@
       hostkeys:
         - /var/run/secrets/host.key
     auth:
-      url: http://your-auth-server/
+      password:
+        method: webhook
+        webhook:
+          url: http://your-auth-server/
     ```
 
     !!! tip
@@ -69,7 +75,10 @@
       hostkeys:
         - /etc/containerssh/host.key
     auth:
-      url: http://your-auth-server/
+      password:
+        method: webhook
+        webhook:
+          url: http://your-auth-server/
     EOF
     ) | kubectl create configmap containerssh-config --from-file=config.yaml=/dev/stdin
     ```
@@ -131,4 +140,4 @@
     ```
 
     !!! warning "Note"
-        This still does not configure ContainerSSH to use Kubernetes as a container backend. This is described in detail in the [Kubernetes backend section](kubernetes.md).
+        This still does not configure ContainerSSH to use Kubernetes as a container backend. This is described in detail in the [Kubernetes backend section](kubernetes.md).

docs/reference/upcoming/metrics.md

@@ -26,30 +26,42 @@ Additionally, all options in the HTTP server section on the [HTTP and TLS](http.
 
 You can configure Prometheus to grab the following metrics:
 
-`containerssh_auth_server_failures`
-: Number of failed requests to the authentication server since start.
+`containerssh_config_server_requests_total`
+: Number of requests to the configuration server since start.
 
-`containerssh_auth_success`
-: Number of successful authentications since start. Contains labels for `authtype` (`password` or `pubkey`) and `country` (see below).
+`containerssh_config_server_failures_total`
+: Number of failed requests to the configuration server since start.
 
-`containerssh_auth_failures`
-: Number of failed authentications since start. Contains labels for `authtype` (`password` or `pubkey`) and `country` (see below).
+`containerssh_backend_requests_total`
+: Number of requests to the backend (docker, kubernetes etc) since start.
 
-`containerssh_config_server_failures`
-: Number of failed requests to the configuration server since start.
+`containerssh_backend_errors_total`
+: Number of failed requests to the backend (docker, kubernetes etc) since start.
+
+`containerssh_auth_server_requests_total`
+: Number of requests to the authentication server since start.
+
+`containerssh_auth_server_failures_total`
+: Number of failed requests to the authentication server since start.
 
-`containerssh_ssh_connections`
+`containerssh_auth_success_total`
+: Number of successful authentications since start. Contains labels for `authtype` (`password`, `pubkey` etc) and `country` (see below).
+
+`containerssh_auth_failures_total`
+: Number of failed authentications since start. Contains labels for `authtype` (`password`, `pubkey` etc) and `country` (see below).
+
+`containerssh_ssh_connections_total`
 : Number of SSH connections since start. Contains a label for `country` (see below).
 
-`containerssh_ssh_handshake_successful`
+`containerssh_ssh_current_connections`
+: Number of currently active SSH connections. Contains a label for `country` (see below).
+
+`containerssh_ssh_successful_handshakes_total`
 : Number of successful SSH handshakes since start. Contains a label for `country` (see below).
 
-`containerssh_ssh_handshake_failed`
+`containerssh_ssh_failed_handshakes_total`
 : 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](https://www.maxmind.com/en/geoip2-services-and-databases). This database needs to be provided to ContainerSSH externally due to licensing concerns.

docs/reference/upcoming/ssh.md

@@ -19,8 +19,10 @@ The options are as follows:
 | `ciphers` | `[]string` | List of ciphers the server should support. See the [Ciphers](#ciphers) section below. |
 | `kex` | `[]string` | List of key exchange algorithms the server should support. See the [Key exchange](#key-exchange) section below. |
 | `macs` | `[]string` | List of MAC algorithms the server should support. See the [MAC](#mac) section below. | 
-| `banner` | `[]string` | The banner text to presented to any connecting client. |
+| `banner` | `string` | The banner text to presented to any connecting client. |
 | `hostkeys` | `[]string` | List of host keys in PEM format, or file names to read the key from. Generate with `openssl genrsa` |
+| `clientAliveInterval` | `time.Duration` (`string`) | Time interval between keepAlive messages containerssh sends to the client. Defaults to `0`, disabled. Example value:`30s`
+| `clientAliveCountMax` | `int` | Number of missed keepAlive messages before a client is considered disconnected and the connection is closed |
 
 ## Configuring the server version