docker

README

ContainerSSH Docker Backend Library

This library implements a backend that connects to a Docker socket and launches a new container for each connection, then runs executes a separate command per channel using docker exec. It replaces the legacy dockerrun backend.

⚠⚠⚠ Warning: This is a developer documentation. ⚠⚠⚠
The user documentation for ContainerSSH is located at containerssh.io.

Using this library

This library implements a NetworkConnectionHandler from the sshserver library. This can be embedded into a connection handler.

The network connection handler can be created with the New() method:

var client net.TCPAddr
connectionID := "0123456789ABCDEF"
config := docker.Config{
    //...
}
collector := metrics.New()
dr, err := docker.New(
    client,
    connectionID,
    config,
    logger,
    collector.MustCreateCounter("backend_requests", "", ""),
    collector.MustCreateCounter("backend_failures", "", ""),
)
if err != nil {
    // Handle error
}

The logger parameter is a logger from the ContainerSSH logger library.

The dr variable can then be used to create a container on finished handshake:

ssh, err := dr.OnHandshakeSuccess("provided-connection-username")

Conversely, on disconnect you must call dr.OnDisconnect(). The ssh variable can then be used to create session channels:

var channelID uint64 = 0
extraData := []byte{}
session, err := ssh.OnSessionChannel(channelID, extraData)

Finally, the session can be used to launch programs:

var requestID uint64 = 0
err = session.OnEnvRequest(requestID, "foo", "bar")
// ...
requestID = 1
var stdin io.Reader
var stdout, stderr io.Writer
err = session.OnShell(
    requestID,
    stdin,
    stdout,
    stderr,
    func(exitStatus ExitStatus) {
        // ...
    },
)

Operating modes

This library supports several operating modes:

• connection creates a container per connection and uses the docker exec mechanism to launch SSH programs inside the container. This mode ignores the CMD of the container image and uses the idleProgram setting to launch inside the container.
• session creates a container per session and potentially results in multiple containers for a single SSH connection. This mode uses the CMD of the container image or from the configuration.

Documentation

Index

• Constants
• func New(client net.TCPAddr, connectionID string, cfg config.DockerConfig, ...) (sshserver.NetworkConnectionHandler, error)

Constants

const UserMessageInitializeSSHSession = "Failed to initialize SSH session."

This message is the user-visible message if the Docker initialization fails.

Functions

func New

func New(
	client net.TCPAddr,
	connectionID string,
	cfg config.DockerConfig,
	logger log2.Logger,
	backendRequestsMetric metrics.SimpleCounter,
	backendFailuresMetric metrics.SimpleCounter,
) (
	sshserver.NetworkConnectionHandler,
	error,
)

New creates a new NetworkConnectionHandler for a specific client.