dockerrun

README

ContainerSSH DockerRun 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.

Note: This is a developer documentation.
The user documentation for ContainerSSH is located at containerssh.github.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 := dockerrun.Config{
    //...
}
dr, err := dockerrun.New(client, connectionID, config, logger)
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) {
        // ...
    },
)

Documentation

Index

• func New(client net.TCPAddr, connectionID string, config Config, logger log.Logger) (sshserver.NetworkConnectionHandler, error)
• type Config
• type ContainerConfig
  • func (c ContainerConfig) Validate() error
• type ImagePullPolicy
  • func (p ImagePullPolicy) Validate() error

Functions

func New

func New(client net.TCPAddr, connectionID string, config Config, logger log.Logger) (sshserver.NetworkConnectionHandler, error)

New creates a new NetworkConnectionHandler for a specific client.

Types

type Config

type Config struct {
	Host   string          `json:"host" yaml:"host" comment:"Docker connect URL" default:"unix:///var/run/docker.sock"`
	CaCert string          `json:"cacert" yaml:"cacert" comment:"CA certificate for Docker connection embedded in the configuration in PEM format."`
	Cert   string          `json:"cert" yaml:"cert" comment:"Client certificate in PEM format embedded in the configuration."`
	Key    string          `json:"key" yaml:"key" comment:"Client key in PEM format embedded in the configuration."`
	Config ContainerConfig `json:"config" yaml:"config" comment:"Config configuration"`
}

Config is the base configuration structure of the DockerRun backend.

type ContainerConfig

type ContainerConfig struct {
	// ContainerConfig contains container-specific configuration options.
	ContainerConfig container.Config `` /* 129-byte string literal not displayed */
	// HostConfig contains the host-specific configuration options.
	HostConfig container.HostConfig `json:"host" yaml:"host" comment:"Host configuration"`
	// NetworkConfig contains the network settings.
	NetworkConfig network.NetworkingConfig `json:"network" yaml:"network" comment:"Network configuration"`
	// Platform contains the platform specification.
	Platform *specs.Platform `json:"platform" yaml:"platform" comment:"Platform specification"`
	// ContainerName is the name of the container to launch. It is recommended to leave this empty, otherwise
	// ContainerSSH may not be able to start the container if a container with the same name already exists.
	ContainerName string `json:"containername" yaml:"containername" comment:"Name for the container to be launched"`
	// Subsystems contains a map of subsystem names and their corresponding binaries in the container.
	Subsystems map[string]string `` /* 133-byte string literal not displayed */
	// DisableCommand disables passed command execution.
	DisableCommand bool `json:"disableCommand" yaml:"disableCommand" comment:"Disable command execution passed from SSH"`
	// DisableShell disables shell requests.
	DisableShell bool `json:"disableShell" yaml:"disableShell" comment:"Disables shell requests."`
	// DisableSubsystem disables subsystem requests.
	DisableSubsystem bool `json:"disableSubsystem" yaml:"disableSubsystem" comment:"Disables subsystem requests."`
	// ShellCommand is the command that runs when a shell is requested. This is intentionally left empty because populating it would mean a potential security issue.
	ShellCommand []string `json:"shellCommand" yaml:"shellCommand" comment:"Run this command when a new shell is requested." default:"[]"`
	// IdleCommand is the command that runs as the first process in the container. The only job of this command is to
	// keep the container alive and exit when a TERM signal is sent.
	IdleCommand []string `` /* 191-byte string literal not displayed */
	// ImagePullPolicy controls when to pull container images.
	ImagePullPolicy ImagePullPolicy `json:"imagePullPolicy" yaml:"imagePullPolicy" comment:"Image pull policy" default:"IfNotPresent"`
	// Timeout is the timeout for container start.
	Timeout time.Duration `json:"timeout" yaml:"timeout" comment:"Timeout for container start." default:"60s"`
}

ContainerConfig contains the configuration of what container to run in Docker.

func (ContainerConfig) Validate

func (c ContainerConfig) Validate() error

Validate validates the dockerrun config structure.

type ImagePullPolicy

type ImagePullPolicy string

const (
	// ImagePullPolicyAlways means that the container image will be pulled on every connection.
	ImagePullPolicyAlways ImagePullPolicy = "Always"
	// ImagePullPolicyIfNotPresent means the image will be pulled if the image is not present locally, an empty tag, or
	// the "latest" tag was specified.
	ImagePullPolicyIfNotPresent ImagePullPolicy = "IfNotPresent"
	// ImagePullPolicyNever means that the image will be never pulled, and if the image is not available locally the
	// connection will fail.
	ImagePullPolicyNever ImagePullPolicy = "Never"
)

func (ImagePullPolicy) Validate

func (p ImagePullPolicy) Validate() error

Validate checks if the given image pull policy is valid.