ssh2docker

README

ssh2docker

🔧 SSH server that creates a Docker container per connection (chroot++)

Example

Server

$ ssh2docker
INFO[0000] Listening on port 2222
INFO[0004] conn: User="alpine", ClientVersion=%!(NOVERB)%!(EXTRA string=5353482d322e302d4f70656e5353485f362e32)
INFO[0004] Creating pty...
INFO[0004] Window resize 181x50
INFO[0004] pty-req: xterm-256color
INFO[0004] Executing docker [run -it --rm alpine /bin/sh]
INFO[0010] session closed
INFO[0016] conn: User="ubuntu", ClientVersion=%!(NOVERB)%!(EXTRA string=5353482d322e302d4f70656e5353485f362e32)
INFO[0016] Creating pty...
INFO[0016] Window resize 181x50
INFO[0016] pty-req: xterm-256color
INFO[0016] Executing docker [run -it --rm ubuntu /bin/sh]
INFO[0023] session closed

Client

$ ssh localhost -p 2222 -l alpine
Host key fingerprint is 59:46:d7:cf:ca:33:be:1f:58:fd:46:c8:ca:5d:56:03
+--[ RSA 2048]----+
|          . .E   |
|         . .  o  |
|          o    +.|
|         +   . .*|
|        S    .oo=|
|           . oB+.|
|            oo.+o|
|              ...|
|              .o.|
+-----------------+

alpine@localhost's password:
/ # cat /etc/alpine-release
3.2.0
/ # ^D

$ ssh localhost -p 2222 -l ubuntu
Host key fingerprint is 59:46:d7:cf:ca:33:be:1f:58:fd:46:c8:ca:5d:56:03
+--[ RSA 2048]----+
|          . .E   |
|         . .  o  |
|          o    +.|
|         +   . .*|
|        S    .oo=|
|           . oB+.|
|            oo.+o|
|              ...|
|              .o.|
+-----------------+

ubuntu@localhost's password:
# lsb_release -a
No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 14.04.3 LTS
Release:	14.04
Codename:	trusty
# ^D

Install

Install latest version using Golang (recommended)

$ go get github.com/moul/ssh2docker/cmd/ssh2docker

---

Install latest version using Homebrew (Mac OS X)

$ brew install https://raw.githubusercontent.com/moul/ssh2docker/master/contrib/homebrew/assh.rb --HEAD

or the latest released version

$ brew install https://raw.githubusercontent.com/moul/ssh2docker/master/contrib/homebrew/assh.rb

Test with Docker

You can test ssh2docker within Docker, but you will have some limitations, i.e: cannot run with boot2docker.

Here is an example about how to use ssh2docker inside Docker

$ docker run --privileged -v /var/lib/docker:/var/lib/docker -it --rm -p 2222:2222 moul/ssh2docker

Usage

NAME:
   ssh2docker - SSH portal to Docker containers

USAGE:
   ssh2docker [global options] command [command options] [arguments...]

AUTHOR(S):
   Manfred Touron <https://github.com/moul/ssh2docker>

COMMANDS:
   help, h	Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --verbose, -V		Enable verbose mode
   --bind, -b ":2222"		Listen to address
   --host-key, -k "built-in"	Path or complete SSH host key to use
   --allowed-images 		List of allowed images, i.e: alpine,ubuntu:trusty,1cf3e6c
   --shell "/bin/sh"		Default shell
   --docker-run-args "-it --rm"	'docker run' arguments
   --help, -h			show help
   --version, -v		print the version

Changelog

v1.1.0 (2015-10-07)

• Fix runtime error on Linux (#38)
• Initial version of the native Scaleway support (#36)
• Support of 'ssh2docker --password-auth-script' options (#28)
• Add docker support (#17)
• Add GOXC support to build binaries for multiple architectures (#18)
• Support of 'ssh2docker --clean-on-startup' (#23)
• Add homebrew support (#16)
• Add Changelog (#19)

full commits list

v1.0.1 (2015-09-27)

• Using party to manage dependencies

full commits list

v1.0.0 (2015-09-27)

Initial release

Features

• Basic logging
• Handling environment-variable requests
• Support of --allowed-images option (#4)
• Ability to configure docker run arguments (#13)
• Reconnecting to existing containers (#14)
• Support of --no-join option (#6)

full commits list

License

MIT

Documentation

Index

• func DockerCleanup() error
• func DockerKill(containerID string) error
• func DockerListContainers(all bool) ([]string, error)
• func DockerRemove(containerID string) error
• func SetWinsize(fd uintptr, w, h uint32)
• type Client
  • func NewClient(conn *ssh.ServerConn, chans <-chan ssh.NewChannel, reqs <-chan *ssh.Request, ...) *Client
  • func (c *Client) HandleChannel(newChannel ssh.NewChannel) error
  • func (c *Client) HandleChannelRequests(channel ssh.Channel, requests <-chan *ssh.Request)
  • func (c *Client) HandleChannels() error
  • func (c *Client) HandleRequests() error
• type ClientConfig
• type Environment
  • func (e *Environment) List() []string
• type Server
  • func NewServer() (*Server, error)
  • func (s *Server) AddHostKey(keystring string) error
  • func (s *Server) Handle(netConn net.Conn) error
  • func (s *Server) ImageIsAllowed(target string) bool
  • func (s *Server) Init() error
  • func (s *Server) PasswordCallback(conn ssh.ConnMetadata, password []byte) (*ssh.Permissions, error)
• type Winsize

Functions

func DockerCleanup

func DockerCleanup() error

DockerCleanup cleans all containers created by ssh2docker

func DockerKill

func DockerKill(containerID string) error

DockerKill kills a container

func DockerListContainers

func DockerListContainers(all bool) ([]string, error)

DockerListContainers lists containers created by ssh2docker

func DockerRemove

func DockerRemove(containerID string) error

DockerRemove removes a container

func SetWinsize

func SetWinsize(fd uintptr, w, h uint32)

Types

type Client

type Client struct {
	Idx        int
	ChannelIdx int
	Conn       *ssh.ServerConn
	Chans      <-chan ssh.NewChannel
	Reqs       <-chan *ssh.Request
	Server     *Server
	Pty, Tty   *os.File
	Env        Environment
	Config     *ClientConfig
	ClientID   string
}

Client is one client connection

func NewClient

func NewClient(conn *ssh.ServerConn, chans <-chan ssh.NewChannel, reqs <-chan *ssh.Request, server *Server) *Client

NewClient initializes a new client

func (*Client) HandleChannel

func (c *Client) HandleChannel(newChannel ssh.NewChannel) error

HandleChannel handles one SSH channel

func (*Client) HandleChannelRequests

func (c *Client) HandleChannelRequests(channel ssh.Channel, requests <-chan *ssh.Request)

HandleChannelRequests handles channel requests

func (*Client) HandleChannels

func (c *Client) HandleChannels() error

HandleChannels handles SSH channels

func (*Client) HandleRequests

func (c *Client) HandleRequests() error

HandleRequests handles SSH requests

type ClientConfig

type ClientConfig struct {
	ImageName  string `json:"image-name",omitempty`
	RemoteUser string `json:"remote-user",omitempty`
	Allowed    bool   `json:"allowed",omitempty`
}

type Environment

type Environment map[string]string

func (*Environment) List

func (e *Environment) List() []string

type Server

type Server struct {
	SshConfig *ssh.ServerConfig
	// Clients   map[string]Client
	ClientConfigs map[string]*ClientConfig

	AllowedImages      []string
	DefaultShell       string
	DockerRunArgs      []string
	NoJoin             bool
	CleanOnStartup     bool
	PasswordAuthScript string
	// contains filtered or unexported fields
}

Server is the ssh2docker main structure

func NewServer

func NewServer() (*Server, error)

NewServer initialize a new Server instance with default values

func (*Server) AddHostKey

func (s *Server) AddHostKey(keystring string) error

AddHostKey parses/loads an ssh key and registers it to the server

func (*Server) Handle

func (s *Server) Handle(netConn net.Conn) error

Handle is the SSH client entrypoint, it takes a net.Conn instance and handle all the ssh and ssh2docker stuff

func (*Server) ImageIsAllowed

func (s *Server) ImageIsAllowed(target string) bool

ImageIsAllowed returns true if the target image is in the allowed list

func (*Server) Init

func (s *Server) Init() error

Init initializes server

func (*Server) PasswordCallback

func (s *Server) PasswordCallback(conn ssh.ConnMetadata, password []byte) (*ssh.Permissions, error)

PasswordCallback is called when the user tries to authenticate using a password

type Winsize

type Winsize struct {
	Height uint16
	Width  uint16
	// contains filtered or unexported fields
}