Documentation
¶
Index ¶
- Constants
- func New(client net.TCPAddr, connectionID string, config Config, logger log.Logger, ...) (sshserver.NetworkConnectionHandler, error)
- func NewDockerRun(client net.TCPAddr, connectionID string, legacyConfig DockerRunConfig, ...) (sshserver.NetworkConnectionHandler, error)
- type Config
- type ConnectionConfig
- type DockerRunConfig
- type DockerRunContainerConfigdeprecated
- type ExecutionConfig
- type ExecutionMode
- type ImagePullPolicy
- type LaunchConfig
- type TimeoutConfig
Constants ¶
const ECannotSendSignalNoAgent = "DOCKER_EXEC_SIGNAL_FAILED_NO_AGENT"
The ContainerSSH Docker module failed to deliver a signal because [ContainerSSH Guest Agent](https://github.com/containerssh/agent) support is disabled.
const EConfigError = "DOCKER_CONFIG_ERROR"
The ContainerSSH Docker module detected a configuration error. Please check your configuration.
const EContainerRestarting = "DOCKER_EXIT_CODE_CONTAINER_RESTARTING"
The ContainerSSH Docker module could not fetch the exit code from the program because the container is restarting. This is typically a misconfiguration as ContainerSSH containers should not automatically restart.
const EContainerStopFailed = "DOCKER_CONTAINER_STOP_FAILED"
The ContainerSSH Docker module failed to stop the container. This message can be either temporary and retried or permanent. Check the log message for details.
const EDockerRun = "DOCKERRUN_DEPRECATED"
This message indicates that you are still using the deprecated DockerRun backend. This backend doesn't support all safety and functionality improvements and will be removed in the future. Please read the [deprecation notice for a migration guide](https://containerssh.io/deprecations/dockerrun)
const EFailedAgentRead = "DOCKER_AGENT_READ_FAILED"
The ContainerSSH Docker module failed to read from the ContainerSSH agent. This is most likely because the ContainerSSH guest agent is not present in the guest image, but agent support is enabled.
const EFailedContainerAttach = "DOCKER_CONTAINER_ATTACH_FAILED"
The ContainerSSH Docker module has failed to attach to a container in session mode.
const EFailedContainerCreate = "DOCKER_CONTAINER_CREATE_FAILED"
The ContainerSSH Docker module failed to create a container. This may be a temporary and retried or a permanent error message. Check the log message for details.
const EFailedContainerRemove = "DOCKER_CONTAINER_REMOVE_FAILED"
The ContainerSSH Docker module could not remove the container. This message may be temporary and retried or permanent. Check the log message for details.
const EFailedContainerSignal = "DOCKER_CONTAINER_SIGNAL_FAILED"
The ContainerSSH Docker module has failed to send a signal to the container.
const EFailedContainerStart = "DOCKER_CONTAINER_START_FAILED"
The ContainerSSH docker module failed to start the container. This message can either be temporary and retried or permanent. Check the log message for details.
const EFailedExecAttach = "DOCKER_EXEC_ATTACH_FAILED"
The ContainerSSH Docker module could not attach to the previously-created execution.
const EFailedExecCreate = "DOCKER_EXEC_CREATE_FAILED"
The ContainerSSH Docker module has failed to create an execution. This can be temporary and retried or permanent. See the error message for details.
const EFailedExecSignal = "DOCKER_EXEC_SIGNAL_FAILED"
The ContainerSSH Docker module failed to deliver a signal.
const EFailedImageList = "DOCKER_IMAGE_LISTING_FAILED"
The ContainerSSH Docker module failed to list the images present in the local Docker daemon. This is used to determine if the image needs to be pulled. This can be because the Docker daemon is not reachable, the certificate is invalid, or there is something else interfering with listing the images.
const EFailedImagePull = "DOCKER_IMAGE_PULL_FAILED"
The ContainerSSH Docker module failed to pull the specified container image. This can be because of connection issues to the Docker daemon, or because the Docker daemon itself can't pull the image. If you don't intend to have the image pulled you should set the `ImagePullPolicy` to `Never`. See the [Docker documentation](https://containerssh.io/reference/upcoming/docker) for details.
const EFailedInputCloseWriting = "DOCKER_CLOSE_INPUT_FAILED"
The ContainerSSH Docker module attempted to close the input (stdin) for reading but failed to do so.
const EFailedInputStream = "DOCKER_STREAM_INPUT_FAILED"
The ContainerSSH Docker module failed to stream stdin to the Docker engine.
const EFailedOutputCloseWriting = "DOCKER_CLOSE_OUTPUT_FAILED"
The ContainerSSH Docker module attempted to close the output (stdout and stderr) for writing but failed to do so.
const EFailedOutputStream = "DOCKER_STREAM_OUTPUT_FAILED"
The ContainerSSH Docker module failed to stream stdout and stderr from the Docker engine.
const EFailedPIDRead = "DOCKER_EXEC_PID_READ_FAILED"
The ContainerSSH Docker module has failed to read the process ID from the [ContainerSSH Guest Agent](https://github.com/containerssh/agent). This is most likely because the guest image does not contain the guest agent, but guest agent support has been enabled.
const EFailedResize = "DOCKER_EXEC_RESIZE_FAILED"
The ContainerSSH Docker module failed to resize the console.
const EFailedSignalNoPID = "DOCKER_SIGNAL_FAILED_NO_PID"
The ContainerSSH Docker module can't deliver a signal because no PID has been recorded. This is most likely because guest agent support is disabled.
const EFetchingExitCodeFailed = "DOCKER_EXIT_CODE_FAILED"
The ContainerSSH Docker module has failed to fetch the exit code of the program.
const EGuestAgentDisabled = "DOCKER_GUEST_AGENT_DISABLED"
The [ContainerSSH Guest Agent](https://github.com/containerssh/agent) has been disabled, which is strongly discouraged. ContainerSSH requires the guest agent to be installed in the container image to facilitate all SSH features. Disabling the guest agent will result in breaking the expectations a user has towards an SSH server. We provide the ability to disable guest agent support only for cases where the guest agent binary cannot be installed in the image at all.
const ENegativeExitCode = "DOCKER_EXIT_CODE_NEGATIVE"
The ContainerSSH Docker module has received a negative exit code from Docker. This should never happen and is most likely a bug.
const EProgramAlreadyRunning = "DOCKER_PROGRAM_ALREADY_RUNNING"
The ContainerSSH Docker module can't execute the request because the program is already running. This is a client error.
const EProgramExecutionDisabled = "DOCKERRUN_EXEC_DISABLED"
This message indicates that the user tried to execute a program, but program execution is disabled in the legacy DockerRun configuration.
const EProgramNotRunning = "DOCKER_PROGRAM_NOT_RUNNING"
This message indicates that the user requested an action that can only be performed when a program is running, but there is currently no program running.
const EShuttingDown = "DOCKER_CONTAINER_SHUTTING_DOWN"
The ContainerSSH Docker module is shutting down a container.
const EStillRunning = "DOCKER_EXIT_CODE_STILL_RUNNING"
The ContainerSSH Docker module could not fetch the program exit code because the program is still running. This error may be temporary and retried or permanent.
const ESubsystemNotSupported = "DOCKER_SUBSYSTEM_NOT_SUPPORTED"
The ContainerSSH Docker module is not configured to run the requested subsystem.
const MContainerAttach = "DOCKER_CONTAINER_ATTACH"
The ContainerSSH Docker module is attaching to a container in session mode.
const MContainerCreate = "DOCKER_CONTAINER_CREATE"
The ContainerSSH Docker module is creating a container.
const MContainerRemove = "DOCKER_CONTAINER_REMOVE"
The ContainerSSH Docker module os removing the container.
const MContainerRemoveSuccessful = "DOCKER_CONTAINER_REMOVE_SUCCESSFUL"
The ContainerSSH Docker module has successfully removed the container.
const MContainerSignal = "DOCKER_CONTAINER_SIGNAL"
The ContainerSSH Docker module is sending a signal to the container.
const MContainerStart = "DOCKER_CONTAINER_START"
The ContainerSSH Docker module is starting the previously-created container.
const MContainerStop = "DOCKER_CONTAINER_STOP"
The ContainerSSH Docker module is stopping the container.
const MExec = "DOCKER_EXEC"
The ContainerSSH Docker module is creating an execution. This may be in connection mode, or it may be the module internally using the exec mechanism to deliver a payload into the container.
const MExecAttach = "DOCKER_EXEC_ATTACH"
The ContainerSSH Docker module is attaching to the previously-created execution.
const MExecCreate = "DOCKER_EXEC_CREATE"
The ContainerSSH Docker module is creating an execution.
const MExecSignal = "DOCKER_EXEC_SIGNAL"
The ContainerSSH Docker module is delivering a signal in container mode.
const MExecSignalSuccessful = "DOCKER_EXEC_SIGNAL_SUCCESSFUL"
The ContainerSSH Docker module successfully delivered the requested signal.
const MExitCode = "DOCKER_EXIT_CODE"
The ContainerSSH Docker module is fetching the exit code from the program.
const MImageList = "DOCKER_IMAGE_LISTING"
The ContainerSSH Docker module is listing the locally present container images to determine if the specified container image needs to be pulled.
const MImagePull = "DOCKER_IMAGE_PULL"
The ContainerSSH Docker module is pulling the container image.
const MImagePullNeeded = "DOCKER_IMAGE_PULL_NEEDED_CHECKING"
The ContainerSSH Docker module is checking if an image pull is needed.
const MResizing = "DOCKER_EXEC_RESIZE"
The ContainerSSH Docker module is resizing the console.
const UserMessageInitializeSSHSession = "Failed to initialize SSH session."
This message is the user-visible message if the Docker initialization fails.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New( client net.TCPAddr, connectionID string, config Config, logger log.Logger, backendRequestsMetric metrics.SimpleCounter, backendFailuresMetric metrics.SimpleCounter, ) ( sshserver.NetworkConnectionHandler, error, )
New creates a new NetworkConnectionHandler for a specific client.
func NewDockerRun ¶
func NewDockerRun( client net.TCPAddr, connectionID string, legacyConfig DockerRunConfig, logger log.Logger, backendRequestsMetric metrics.SimpleCounter, backendFailuresMetric metrics.SimpleCounter, ) (sshserver.NetworkConnectionHandler, error)
NewDockerRun creates a new NetworkConnectionHandler based on the deprecated "dockerrun" config structure. Deprecated: use New instead
Types ¶
type Config ¶
type Config struct {
// Connection configures how to connect to dockerd
Connection ConnectionConfig `json:"connection" yaml:"connection"`
// Execution drives how the container and the workload is executed
Execution ExecutionConfig `json:"execution" yaml:"execution"`
// Timeouts configures the various timeouts when interacting with dockerd.
Timeouts TimeoutConfig `json:"timeouts" yaml:"timeouts"`
}
Config is the base configuration structure of the DockerRun backend.
type ConnectionConfig ¶
type ConnectionConfig struct {
// Host is the docker connect URL.
Host string `json:"host" yaml:"host" default:"unix:///var/run/docker.sock"`
// CaCert is the CA certificate for Docker connection embedded in the configuration in PEM format.
CaCert string `json:"cacert" yaml:"cacert"`
// Cert is the client certificate in PEM format embedded in the configuration.
Cert string `json:"cert" yaml:"cert"`
// Key is the client key in PEM format embedded in the configuration.
Key string `json:"key" yaml:"key"`
}
ConnectionConfig configures how to connect to dockerd.
func (ConnectionConfig) Validate ¶
func (c ConnectionConfig) Validate() error
type DockerRunConfig ¶
type DockerRunConfig 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 DockerRunContainerConfig `json:"config" yaml:"config" comment:"Config configuration"`
}
DockerRunConfig describes the old ContainerSSH 0.3 configuration format that can still be read and used. Deprecated: Switch to the more generic "docker" backend.
func (DockerRunConfig) Validate ¶ added in v0.9.6
func (config DockerRunConfig) Validate() error
Validate validates the docker run config
type DockerRunContainerConfig
deprecated
type DockerRunContainerConfig struct {
LaunchConfig `json:",inline" yaml:",inline"`
Subsystems map[string]string `` /* 133-byte string literal not displayed */
DisableCommand bool `json:"disableCommand" yaml:"disableCommand" comment:"Disable command execution passed from SSH"`
Timeout time.Duration `json:"timeout" yaml:"timeout" comment:"Timeout for pod creation" default:"60s"`
}
Deprecated: Switch to the more generic "docker" backend.
func (*DockerRunContainerConfig) UnmarshalJSON ¶ added in v0.9.2
func (d *DockerRunContainerConfig) UnmarshalJSON(b []byte) error
func (*DockerRunContainerConfig) UnmarshalYAML ¶ added in v0.9.2
func (d *DockerRunContainerConfig) UnmarshalYAML(unmarshal func(interface{}) error) error
func (*DockerRunContainerConfig) Validate ¶ added in v0.9.6
func (d *DockerRunContainerConfig) Validate() error
Validate validates the container config
type ExecutionConfig ¶
type ExecutionConfig struct {
// Launch contains the Docker-specific launch configuration.
Launch LaunchConfig `json:",inline" yaml:",inline"`
// Mode influences how commands are executed.
//
// - If ExecutionModeConnection is chosen (default) a new container is launched per connection. In this mode
// sessions are executed using the "docker exec" functionality and the main container console runs a script that
// waits for a termination signal.
// - If ExecutionModeSession is chosen a new container is launched per session, leading to potentially multiple
// containers per connection. In this mode the program is launched directly as the main process of the container.
// When configuring this mode you should explicitly configure the "cmd" option to an empty list if you want the
// default command in the container to launch.
Mode ExecutionMode `json:"mode" yaml:"mode" default:"connection"`
// IdleCommand is the command that runs as the first process in the container in ExecutionModeConnection. Ignored in ExecutionModeSession.
IdleCommand []string `` /* 191-byte string literal not displayed */
// ShellCommand is the command used for launching shells when the container is in ExecutionModeConnection. Ignored in ExecutionModeSession.
ShellCommand []string `json:"shellCommand" yaml:"shellCommand" comment:"Run this command as a default shell." default:"[\"/bin/bash\"]"`
// AgentPath contains the path to the ContainerSSH Guest Agent.
AgentPath string `json:"agentPath" yaml:"agentPath" default:"/usr/bin/containerssh-agent"`
// DisableAgent enables using the ContainerSSH Guest Agent.
DisableAgent bool `json:"disableAgent" yaml:"disableAgent"`
// Subsystems contains a map of subsystem names and their corresponding binaries in the container.
Subsystems map[string]string `` /* 133-byte string literal not displayed */
// ImagePullPolicy controls when to pull container images.
ImagePullPolicy ImagePullPolicy `json:"imagePullPolicy" yaml:"imagePullPolicy" comment:"Image pull policy" default:"IfNotPresent"`
// contains filtered or unexported fields
}
ExecutionConfig contains the configuration of what container to run in Docker.
func (ExecutionConfig) Validate ¶
func (c ExecutionConfig) Validate() error
Validate validates the docker config structure.
type ExecutionMode ¶
type ExecutionMode string
ExecutionMode determines when a container is launched. ExecutionModeConnection launches one container per SSH connection (default), while ExecutionModeSession launches one container per SSH session.
const ( // ExecutionModeConnection launches one container per SSH connection. ExecutionModeConnection ExecutionMode = "connection" // ExecutionModeSession launches one container per SSH session (multiple containers per connection). ExecutionModeSession ExecutionMode = "session" )
func (ExecutionMode) Validate ¶
func (e ExecutionMode) Validate() error
Validate validates the execution config.
type ImagePullPolicy ¶
type ImagePullPolicy string
ImagePullPolicy drives how and when images are pulled. The values are closely aligned with the Kubernetes image pull policy.
- ImagePullPolicyAlways means that the container image will be pulled on every connection.
- ImagePullPolicyIfNotPresent means the image will be pulled if the image is not present locally, an empty tag, or the "latest" tag was specified.
- ImagePullPolicyNever means that the image will be never pulled, and if the image is not available locally the connection will fail.
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.
type LaunchConfig ¶
type LaunchConfig 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"`
}
LaunchConfig contains the container configuration for the Docker client version 20.
func (*LaunchConfig) UnmarshalJSON ¶
func (l *LaunchConfig) UnmarshalJSON(b []byte) error
UnmarshalJSON implements the special unmarshalling of the LaunchConfig that ignores unknown fields. This is needed because Docker treats removing fields as backwards-compatible. See https://github.com/moby/moby/pull/39158#issuecomment-489704731
func (*LaunchConfig) UnmarshalYAML ¶
func (l *LaunchConfig) UnmarshalYAML(unmarshal func(interface{}) error) error
UnmarshalYAML implements the special unmarshalling of the LaunchConfig that ignores unknown fields. This is needed because Docker treats removing fields as backwards-compatible. See https://github.com/moby/moby/pull/39158#issuecomment-489704731
func (*LaunchConfig) Validate ¶ added in v0.9.6
func (l *LaunchConfig) Validate() error
Validate validates the launch configuration.
type TimeoutConfig ¶
type TimeoutConfig struct {
// ContainerStart is the maximum time starting a container may take.
ContainerStart time.Duration `json:"containerStart" yaml:"containerStart" default:"60s"`
// ContainerStop is the maximum time to wait for a container to stop. This should always be set higher than the Docker StopTimeout.
ContainerStop time.Duration `json:"containerStop" yaml:"containerStop" default:"60s"`
// CommandStart sets the maximum time starting a command may take.
CommandStart time.Duration `json:"commandStart" yaml:"commandStart" default:"60s"`
// Signal sets the maximum time sending a signal may take.
Signal time.Duration `json:"signal" yaml:"signal" default:"60s"`
// Signal sets the maximum time setting the window size may take.
Window time.Duration `json:"window" yaml:"window" default:"60s"`
// HTTP
HTTP time.Duration `json:"http" yaml:"http" default:"15s"`
}
TimeoutConfig drives the various timeouts in the Docker backend.
func (*TimeoutConfig) UnmarshalJSON ¶ added in v0.9.2
func (t *TimeoutConfig) UnmarshalJSON(b []byte) error
UnmarshalJSON takes a JSON byte array and unmarshalls it into a structure.
func (*TimeoutConfig) UnmarshalYAML ¶ added in v0.9.2
func (t *TimeoutConfig) UnmarshalYAML(unmarshal func(interface{}) error) error
UnmarshalYAML takes a YAML byte array and unmarshalls it into a structure.
Source Files
¶
- codes.go
- codes_doc.go
- config.go
- config_connection.go
- config_connection_unix.go
- config_dockerrun.go
- config_dockerrun_unix.go
- config_duration.go
- config_execution.go
- config_launch.go
- config_timeout.go
- const.go
- docker.go
- docker_impl.go
- factory.go
- factory_dockerrun.go
- handler_channel.go
- handler_network.go
- handler_ssh.go
- http.go
- image.go