Bumped version to 0.1.4

Added code and color for 'note' and updated the examples note.

AUTHORS

@@ -21,6 +21,7 @@ Jonathan Rudenberg <jonathan@titanous.com>
 Julien Barbier <write0@gmail.com>
 Jérôme Petazzoni <jerome.petazzoni@dotcloud.com>
 Ken Cochrane <kencochrane@gmail.com>
+Kevin J. Lynagh <kevin@keminglabs.com>
 Louis Opter <kalessin@kalessin.fr>
 Mikhail Sobolev <mss@mawhrin.net>
 Nelson Chen <crazysim@gmail.com>

README.md

@@ -134,6 +134,12 @@ docker pull base
 docker run -i -t base /bin/bash
 ```
 
+Detaching from the interactive shell
+------------------------------------
+```
+# In order to detach without killing the shell, you can use the escape sequence Ctrl-p + Ctrl-q
+# Note: this works only in tty mode (run with -t option).
+```
 
 Starting a long-running worker process
 --------------------------------------
@@ -183,7 +189,9 @@ JOB=$(docker run -d -p 4444 base /bin/nc -l -p 4444)
 PORT=$(docker port $JOB 4444)
 
 # Connect to the public port via the host's public address
-echo hello world | nc $(hostname) $PORT
+# Please note that because of how routing works connecting to localhost or 127.0.0.1 $PORT will not work.
+IP=$(ifconfig eth0 | perl -n -e 'if (m/inet addr:([\d\.]+)/g) { print $1 }')
+echo hello world | nc $IP $PORT
 
 # Verify that the network connection worked
 echo "Daemon received: $(docker logs $JOB)"

commands.go

@@ -18,7 +18,7 @@ import (
 	"unicode"
 )
 
-const VERSION = "0.1.2"
+const VERSION = "0.1.4"
 
 var GIT_COMMIT string
 
@@ -62,7 +62,7 @@ func (srv *Server) Help() string {
 }
 
 // 'docker login': login / register a user to registry service.
-func (srv *Server) CmdLogin(stdin io.ReadCloser, stdout io.Writer, args ...string) error {
+func (srv *Server) CmdLogin(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {
 	// Read a line on raw terminal with support for simple backspace
 	// sequences and echo.
 	//
@@ -99,7 +99,7 @@ func (srv *Server) CmdLogin(stdin io.ReadCloser, stdout io.Writer, args ...strin
 			}
 			if err != nil {
 				if err != io.EOF {
-					fmt.Fprint(stdout, "Read error: %v\n", err)
+					fmt.Fprintf(stdout, "Read error: %v\n", err)
 				}
 				break
 			}
@@ -113,6 +113,8 @@ func (srv *Server) CmdLogin(stdin io.ReadCloser, stdout io.Writer, args ...strin
 		return readStringOnRawTerminal(stdin, stdout, false)
 	}
 
+	stdout.SetOptionRawTerminal()
+
 	cmd := rcli.Subcmd(stdout, "login", "", "Register or Login to the docker registry server")
 	if err := cmd.Parse(args); err != nil {
 		return nil
@@ -417,7 +419,8 @@ func (srv *Server) CmdKill(stdin io.ReadCloser, stdout io.Writer, args ...string
 	return nil
 }
 
-func (srv *Server) CmdImport(stdin io.ReadCloser, stdout io.Writer, args ...string) error {
+func (srv *Server) CmdImport(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {
+	stdout.Flush()
 	cmd := rcli.Subcmd(stdout, "import", "[OPTIONS] URL|- [REPOSITORY [TAG]]", "Create a new filesystem image from the contents of a tarball")
 	var archive io.Reader
 	var resp *http.Response
@@ -464,7 +467,7 @@ func (srv *Server) CmdImport(stdin io.ReadCloser, stdout io.Writer, args ...stri
 	return nil
 }
 
-func (srv *Server) CmdPush(stdin io.ReadCloser, stdout io.Writer, args ...string) error {
+func (srv *Server) CmdPush(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {
 	cmd := rcli.Subcmd(stdout, "push", "NAME", "Push an image or a repository to the registry")
 	if err := cmd.Parse(args); err != nil {
 		return nil
@@ -512,10 +515,9 @@ func (srv *Server) CmdPush(stdin io.ReadCloser, stdout io.Writer, args ...string
 				return err
 			}
 			return nil
-		} else {
-			return err
 		}
-		return nil
+
+		return err
 	}
 	err = srv.runtime.graph.PushImage(stdout, img, srv.runtime.authConfig)
 	if err != nil {
@@ -785,7 +787,7 @@ func (srv *Server) CmdLogs(stdin io.ReadCloser, stdout io.Writer, args ...string
 	return fmt.Errorf("No such container: %s", cmd.Arg(0))
 }
 
-func (srv *Server) CmdAttach(stdin io.ReadCloser, stdout io.Writer, args ...string) error {
+func (srv *Server) CmdAttach(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {
 	cmd := rcli.Subcmd(stdout, "attach", "CONTAINER", "Attach to a running container")
 	if err := cmd.Parse(args); err != nil {
 		return nil
@@ -799,7 +801,13 @@ func (srv *Server) CmdAttach(stdin io.ReadCloser, stdout io.Writer, args ...stri
 	if container == nil {
 		return fmt.Errorf("No such container: %s", name)
 	}
-	return <-container.Attach(stdin, stdout, stdout)
+
+	if container.Config.Tty {
+		stdout.SetOptionRawTerminal()
+	}
+	// Flush the options to make sure the client sets the raw mode
+	stdout.Flush()
+	return <-container.Attach(stdin, nil, stdout, stdout)
 }
 
 // Ports type - Used to parse multiple -p flags
@@ -833,25 +841,25 @@ func (opts *ListOpts) Set(value string) error {
 // AttachOpts stores arguments to 'docker run -a', eg. which streams to attach to
 type AttachOpts map[string]bool
 
-func NewAttachOpts() *AttachOpts {
-	opts := make(map[string]bool)
-	return (*AttachOpts)(&opts)
+func NewAttachOpts() AttachOpts {
+	return make(AttachOpts)
 }
 
-func (opts *AttachOpts) String() string {
-	return fmt.Sprint(*opts)
+func (opts AttachOpts) String() string {
+	// Cast to underlying map type to avoid infinite recursion
+	return fmt.Sprintf("%v", map[string]bool(opts))
 }
 
-func (opts *AttachOpts) Set(val string) error {
+func (opts AttachOpts) Set(val string) error {
 	if val != "stdin" && val != "stdout" && val != "stderr" {
 		return fmt.Errorf("Unsupported stream name: %s", val)
 	}
-	(*opts)[val] = true
+	opts[val] = true
 	return nil
 }
 
-func (opts *AttachOpts) Get(val string) bool {
-	if res, exists := (*opts)[val]; exists {
+func (opts AttachOpts) Get(val string) bool {
+	if res, exists := opts[val]; exists {
 		return res
 	}
 	return false
@@ -870,7 +878,7 @@ func (srv *Server) CmdTag(stdin io.ReadCloser, stdout io.Writer, args ...string)
 	return srv.runtime.repositories.Set(cmd.Arg(1), cmd.Arg(2), cmd.Arg(0), *force)
 }
 
-func (srv *Server) CmdRun(stdin io.ReadCloser, stdout io.Writer, args ...string) error {
+func (srv *Server) CmdRun(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {
 	config, err := ParseRun(args, stdout)
 	if err != nil {
 		return err
@@ -884,6 +892,13 @@ func (srv *Server) CmdRun(stdin io.ReadCloser, stdout io.Writer, args ...string)
 		return fmt.Errorf("Command not specified")
 	}
 
+	if config.Tty {
+		stdout.SetOptionRawTerminal()
+	}
+	// Flush the options to make sure the client sets the raw mode
+	// or tell the client there is no options
+	stdout.Flush()
+
 	// Create new container
 	container, err := srv.runtime.Create(config)
 	if err != nil {
@@ -901,11 +916,17 @@ func (srv *Server) CmdRun(stdin io.ReadCloser, stdout io.Writer, args ...string)
 		}
 	}
 	var (
-		cStdin           io.Reader
+		cStdin           io.ReadCloser
 		cStdout, cStderr io.Writer
 	)
 	if config.AttachStdin {
-		cStdin = stdin
+		r, w := io.Pipe()
+		go func() {
+			defer w.Close()
+			defer Debugf("Closing buffered stdin pipe")
+			io.Copy(w, stdin)
+		}()
+		cStdin = r
 	}
 	if config.AttachStdout {
 		cStdout = stdout
@@ -913,7 +934,8 @@ func (srv *Server) CmdRun(stdin io.ReadCloser, stdout io.Writer, args ...string)
 	if config.AttachStderr {
 		cStderr = stdout // FIXME: rcli can't differentiate stdout from stderr
 	}
-	attachErr := container.Attach(cStdin, cStdout, cStderr)
+
+	attachErr := container.Attach(cStdin, stdin, cStdout, cStderr)
 	Debugf("Starting\n")
 	if err := container.Start(); err != nil {
 		return err
@@ -922,7 +944,9 @@ func (srv *Server) CmdRun(stdin io.ReadCloser, stdout io.Writer, args ...string)
 		fmt.Fprintln(stdout, container.ShortId())
 	}
 	Debugf("Waiting for attach to return\n")
-	return <-attachErr
+	<-attachErr
+	// Expecting I/O pipe error, discarding
+	return nil
 }
 
 func NewServer() (*Server, error) {

commands_test.go

@@ -2,8 +2,8 @@ package docker
 
 import (
 	"bufio"
-	"bytes"
 	"fmt"
+	"github.com/dotcloud/docker/rcli"
 	"io"
 	"io/ioutil"
 	"strings"
@@ -69,14 +69,77 @@ func TestRunHostname(t *testing.T) {
 
 	srv := &Server{runtime: runtime}
 
-	var stdin, stdout bytes.Buffer
+	stdin, _ := io.Pipe()
+	stdout, stdoutPipe := io.Pipe()
+
+	c := make(chan struct{})
+	go func() {
+		if err := srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-h", "foobar", GetTestImage(runtime).Id, "hostname"); err != nil {
+			t.Fatal(err)
+		}
+		close(c)
+	}()
+	cmdOutput, err := bufio.NewReader(stdout).ReadString('\n')
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cmdOutput != "foobar\n" {
+		t.Fatalf("'hostname' should display '%s', not '%s'", "foobar\n", cmdOutput)
+	}
+
 	setTimeout(t, "CmdRun timed out", 2*time.Second, func() {
-		if err := srv.CmdRun(ioutil.NopCloser(&stdin), &nopWriteCloser{&stdout}, "-h", "foobar", GetTestImage(runtime).Id, "hostname"); err != nil {
+		<-c
+	})
+}
+
+func TestRunExit(t *testing.T) {
+	runtime, err := newTestRuntime()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer nuke(runtime)
+
+	srv := &Server{runtime: runtime}
+
+	stdin, stdinPipe := io.Pipe()
+	stdout, stdoutPipe := io.Pipe()
+	c1 := make(chan struct{})
+	go func() {
+		srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-i", GetTestImage(runtime).Id, "/bin/cat")
+		close(c1)
+	}()
+
+	setTimeout(t, "Read/Write assertion timed out", 2*time.Second, func() {
+		if err := assertPipe("hello\n", "hello", stdout, stdinPipe, 15); err != nil {
 			t.Fatal(err)
 		}
 	})
-	if output := string(stdout.Bytes()); output != "foobar\n" {
-		t.Fatalf("'hostname' should display '%s', not '%s'", "foobar\n", output)
+
+	container := runtime.List()[0]
+
+	// Closing /bin/cat stdin, expect it to exit
+	p, err := container.StdinPipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := p.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	// as the process exited, CmdRun must finish and unblock. Wait for it
+	setTimeout(t, "Waiting for CmdRun timed out", 2*time.Second, func() {
+		<-c1
+	})
+
+	// Make sure that the client has been disconnected
+	setTimeout(t, "The client should have been disconnected once the remote process exited.", 2*time.Second, func() {
+		// Expecting pipe i/o error, just check that read does not block
+		stdin.Read([]byte{})
+	})
+
+	// Cleanup pipes
+	if err := closeWrap(stdin, stdinPipe, stdout, stdoutPipe); err != nil {
+		t.Fatal(err)
 	}
 }
 
@@ -96,7 +159,7 @@ func TestRunDisconnect(t *testing.T) {
 	go func() {
 		// We're simulating a disconnect so the return value doesn't matter. What matters is the
 		// fact that CmdRun returns.
-		srv.CmdRun(stdin, stdoutPipe, "-i", GetTestImage(runtime).Id, "/bin/cat")
+		srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-i", GetTestImage(runtime).Id, "/bin/cat")
 		close(c1)
 	}()
 
@@ -128,10 +191,56 @@ func TestRunDisconnect(t *testing.T) {
 	})
 }
 
+// Expected behaviour: the process dies when the client disconnects
+func TestRunDisconnectTty(t *testing.T) {
+	runtime, err := newTestRuntime()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer nuke(runtime)
+
+	srv := &Server{runtime: runtime}
+
+	stdin, stdinPipe := io.Pipe()
+	stdout, stdoutPipe := io.Pipe()
+	c1 := make(chan struct{})
+	go func() {
+		// We're simulating a disconnect so the return value doesn't matter. What matters is the
+		// fact that CmdRun returns.
+		srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-i", "-t", GetTestImage(runtime).Id, "/bin/cat")
+		close(c1)
+	}()
+
+	setTimeout(t, "Read/Write assertion timed out", 2*time.Second, func() {
+		if err := assertPipe("hello\n", "hello", stdout, stdinPipe, 15); err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	// Close pipes (simulate disconnect)
+	if err := closeWrap(stdin, stdinPipe, stdout, stdoutPipe); err != nil {
+		t.Fatal(err)
+	}
+
+	// as the pipes are close, we expect the process to die,
+	// therefore CmdRun to unblock. Wait for CmdRun
+	setTimeout(t, "Waiting for CmdRun timed out", 2*time.Second, func() {
+		<-c1
+	})
+
+	// Client disconnect after run -i should keep stdin out in TTY mode
+	container := runtime.List()[0]
+	// Give some time to monitor to do his thing
+	container.WaitTimeout(500 * time.Millisecond)
+	if !container.State.Running {
+		t.Fatalf("/bin/cat should  still be running after closing stdin (tty mode)")
+	}
+}
+
 // TestAttachStdin checks attaching to stdin without stdout and stderr.
 // 'docker run -i -a stdin' should sends the client's stdin to the command,
 // then detach from it and print the container id.
-func TestAttachStdin(t *testing.T) {
+func TestRunAttachStdin(t *testing.T) {
 	runtime, err := newTestRuntime()
 	if err != nil {
 		t.Fatal(err)
@@ -139,31 +248,41 @@ func TestAttachStdin(t *testing.T) {
 	defer nuke(runtime)
 	srv := &Server{runtime: runtime}
 
-	stdinR, stdinW := io.Pipe()
-	var stdout bytes.Buffer
+	stdin, stdinPipe := io.Pipe()
+	stdout, stdoutPipe := io.Pipe()
 
 	ch := make(chan struct{})
 	go func() {
-		srv.CmdRun(stdinR, &stdout, "-i", "-a", "stdin", GetTestImage(runtime).Id, "sh", "-c", "echo hello; cat")
+		srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-i", "-a", "stdin", GetTestImage(runtime).Id, "sh", "-c", "echo hello; cat")
 		close(ch)
 	}()
 
-	// Send input to the command, close stdin, wait for CmdRun to return
-	setTimeout(t, "Read/Write timed out", 2*time.Second, func() {
-		if _, err := stdinW.Write([]byte("hi there\n")); err != nil {
+	// Send input to the command, close stdin
+	setTimeout(t, "Write timed out", 2*time.Second, func() {
+		if _, err := stdinPipe.Write([]byte("hi there\n")); err != nil {
+			t.Fatal(err)
+		}
+		if err := stdinPipe.Close(); err != nil {
 			t.Fatal(err)
 		}
-		stdinW.Close()
-		<-ch
 	})
 
-	// Check output
-	cmdOutput := string(stdout.Bytes())
 	container := runtime.List()[0]
+
+	// Check output
+	cmdOutput, err := bufio.NewReader(stdout).ReadString('\n')
+	if err != nil {
+		t.Fatal(err)
+	}
 	if cmdOutput != container.ShortId()+"\n" {
 		t.Fatalf("Wrong output: should be '%s', not '%s'\n", container.ShortId()+"\n", cmdOutput)
 	}
 
+	// wait for CmdRun to return
+	setTimeout(t, "Waiting for CmdRun timed out", 2*time.Second, func() {
+		<-ch
+	})
+
 	setTimeout(t, "Waiting for command to exit timed out", 2*time.Second, func() {
 		container.Wait()
 	})
@@ -219,7 +338,7 @@ func TestAttachDisconnect(t *testing.T) {
 	go func() {
 		// We're simulating a disconnect so the return value doesn't matter. What matters is the
 		// fact that CmdAttach returns.
-		srv.CmdAttach(stdin, stdoutPipe, container.Id)
+		srv.CmdAttach(stdin, rcli.NewDockerLocalConn(stdoutPipe), container.Id)
 		close(c1)
 	}()
 
@@ -237,6 +356,7 @@ func TestAttachDisconnect(t *testing.T) {
 	setTimeout(t, "Waiting for CmdAttach timed out", 2*time.Second, func() {
 		<-c1
 	})
+
 	// We closed stdin, expect /bin/cat to still be running
 	// Wait a little bit to make sure container.monitor() did his thing
 	err = container.WaitTimeout(500 * time.Millisecond)

container.go

@@ -40,11 +40,11 @@ type Container struct {
 	stdin       io.ReadCloser
 	stdinPipe   io.WriteCloser
 
-	ptyStdinMaster  io.Closer
-	ptyStdoutMaster io.Closer
-	ptyStderrMaster io.Closer
+	ptyMaster io.Closer
 
 	runtime *Runtime
+
+	waitLock chan struct{}
 }
 
 type Config struct {
@@ -55,7 +55,7 @@ type Config struct {
 	AttachStdin  bool
 	AttachStdout bool
 	AttachStderr bool
-	Ports        []int
+	PortSpecs    []string
 	Tty          bool // Attach standard streams to a tty, including stdin if it is not closed.
 	OpenStdin    bool // Open stdin
 	StdinOnce    bool // If true, close stdin after the 1 attached client disconnects.
@@ -79,8 +79,8 @@ func ParseRun(args []string, stdout io.Writer) (*Config, error) {
 	flTty := cmd.Bool("t", false, "Allocate a pseudo-tty")
 	flMemory := cmd.Int64("m", 0, "Memory limit (in bytes)")
 
-	var flPorts ports
-	cmd.Var(&flPorts, "p", "Map a network port to the container")
+	var flPorts ListOpts
+	cmd.Var(&flPorts, "p", "Expose a container's port to the host (use 'docker port' to see the actual mapping)")
 
 	var flEnv ListOpts
 	cmd.Var(&flEnv, "e", "Set environment variables")
@@ -88,11 +88,11 @@ func ParseRun(args []string, stdout io.Writer) (*Config, error) {
 	if err := cmd.Parse(args); err != nil {
 		return nil, err
 	}
-	if *flDetach && len(*flAttach) > 0 {
+	if *flDetach && len(flAttach) > 0 {
 		return nil, fmt.Errorf("Conflicting options: -a and -d")
 	}
 	// If neither -d or -a are set, attach to everything by default
-	if len(*flAttach) == 0 && !*flDetach {
+	if len(flAttach) == 0 && !*flDetach {
 		if !*flDetach {
 			flAttach.Set("stdout")
 			flAttach.Set("stderr")
@@ -112,7 +112,7 @@ func ParseRun(args []string, stdout io.Writer) (*Config, error) {
 	}
 	config := &Config{
 		Hostname:     *flHostname,
-		Ports:        flPorts,
+		PortSpecs:    flPorts,
 		User:         *flUser,
 		Tty:          *flTty,
 		OpenStdin:    *flStdin,
@@ -135,6 +135,7 @@ type NetworkSettings struct {
 	IpAddress   string
 	IpPrefixLen int
 	Gateway     string
+	Bridge      string
 	PortMapping map[string]string
 }
 
@@ -179,63 +180,37 @@ func (container *Container) generateLXCConfig() error {
 }
 
 func (container *Container) startPty() error {
-	stdoutMaster, stdoutSlave, err := pty.Open()
+	ptyMaster, ptySlave, err := pty.Open()
 	if err != nil {
 		return err
 	}
-	container.ptyStdoutMaster = stdoutMaster
-	container.cmd.Stdout = stdoutSlave
-
-	stderrMaster, stderrSlave, err := pty.Open()
-	if err != nil {
-		return err
-	}
-	container.ptyStderrMaster = stderrMaster
-	container.cmd.Stderr = stderrSlave
+	container.ptyMaster = ptyMaster
+	container.cmd.Stdout = ptySlave
+	container.cmd.Stderr = ptySlave
 
 	// Copy the PTYs to our broadcasters
 	go func() {
 		defer container.stdout.CloseWriters()
 		Debugf("[startPty] Begin of stdout pipe")
-		io.Copy(container.stdout, stdoutMaster)
+		io.Copy(container.stdout, ptyMaster)
 		Debugf("[startPty] End of stdout pipe")
 	}()
 
-	go func() {
-		defer container.stderr.CloseWriters()
-		Debugf("[startPty] Begin of stderr pipe")
-		io.Copy(container.stderr, stderrMaster)
-		Debugf("[startPty] End of stderr pipe")
-	}()
-
 	// stdin
-	var stdinSlave io.ReadCloser
 	if container.Config.OpenStdin {
-		var stdinMaster io.WriteCloser
-		stdinMaster, stdinSlave, err = pty.Open()
-		if err != nil {
-			return err
-		}
-		container.ptyStdinMaster = stdinMaster
-		container.cmd.Stdin = stdinSlave
-		// FIXME: The following appears to be broken.
-		// "cannot set terminal process group (-1): Inappropriate ioctl for device"
-		// container.cmd.SysProcAttr = &syscall.SysProcAttr{Setctty: true, Setsid: true}
+		container.cmd.Stdin = ptySlave
+		container.cmd.SysProcAttr = &syscall.SysProcAttr{Setctty: true, Setsid: true}
 		go func() {
 			defer container.stdin.Close()
 			Debugf("[startPty] Begin of stdin pipe")
-			io.Copy(stdinMaster, container.stdin)
+			io.Copy(ptyMaster, container.stdin)
 			Debugf("[startPty] End of stdin pipe")
 		}()
 	}
 	if err := container.cmd.Start(); err != nil {
 		return err
 	}
-	stdoutSlave.Close()
-	stderrSlave.Close()
-	if stdinSlave != nil {
-		stdinSlave.Close()
-	}
+	ptySlave.Close()
 	return nil
 }
 
@@ -257,9 +232,9 @@ func (container *Container) start() error {
 	return container.cmd.Start()
 }
 
-func (container *Container) Attach(stdin io.Reader, stdout io.Writer, stderr io.Writer) chan error {
-	var cStdout io.ReadCloser
-	var cStderr io.ReadCloser
+func (container *Container) Attach(stdin io.ReadCloser, stdinCloser io.Closer, stdout io.Writer, stderr io.Writer) chan error {
+	var cStdout, cStderr io.ReadCloser
+
 	var nJobs int
 	errors := make(chan error, 3)
 	if stdin != nil && container.Config.OpenStdin {
@@ -269,15 +244,27 @@ func (container *Container) Attach(stdin io.Reader, stdout io.Writer, stderr io.
 		} else {
 			go func() {
 				Debugf("[start] attach stdin\n")
-				defer Debugf("[end]  attach stdin\n")
-				if container.Config.StdinOnce {
+				defer Debugf("[end] attach stdin\n")
+				// No matter what, when stdin is closed (io.Copy unblock), close stdout and stderr
+				if cStdout != nil {
+					defer cStdout.Close()
+				}
+				if cStderr != nil {
+					defer cStderr.Close()
+				}
+				if container.Config.StdinOnce && !container.Config.Tty {
 					defer cStdin.Close()
 				}
-				_, err := io.Copy(cStdin, stdin)
-				if err != nil {
-					Debugf("[error] attach stdout: %s\n", err)
+				if container.Config.Tty {
+					_, err = CopyEscapable(cStdin, stdin)
+				} else {
+					_, err = io.Copy(cStdin, stdin)
 				}
-				errors <- err
+				if err != nil {
+					Debugf("[error] attach stdin: %s\n", err)
+				}
+				// Discard error, expecting pipe error
+				errors <- nil
 			}()
 		}
 	}
@@ -290,6 +277,15 @@ func (container *Container) Attach(stdin io.Reader, stdout io.Writer, stderr io.
 			go func() {
 				Debugf("[start] attach stdout\n")
 				defer Debugf("[end]  attach stdout\n")
+				// If we are in StdinOnce mode, then close stdin
+				if container.Config.StdinOnce {
+					if stdin != nil {
+						defer stdin.Close()
+					}
+					if stdinCloser != nil {
+						defer stdinCloser.Close()
+					}
+				}
 				_, err := io.Copy(stdout, cStdout)
 				if err != nil {
 					Debugf("[error] attach stdout: %s\n", err)
@@ -307,6 +303,15 @@ func (container *Container) Attach(stdin io.Reader, stdout io.Writer, stderr io.
 			go func() {
 				Debugf("[start] attach stderr\n")
 				defer Debugf("[end]  attach stderr\n")
+				// If we are in StdinOnce mode, then close stdin
+				if container.Config.StdinOnce {
+					if stdin != nil {
+						defer stdin.Close()
+					}
+					if stdinCloser != nil {
+						defer stdinCloser.Close()
+					}
+				}
 				_, err := io.Copy(stderr, cStderr)
 				if err != nil {
 					Debugf("[error] attach stderr: %s\n", err)
@@ -338,6 +343,9 @@ func (container *Container) Attach(stdin io.Reader, stdout io.Writer, stderr io.
 }
 
 func (container *Container) Start() error {
+	container.State.lock()
+	defer container.State.unlock()
+
 	if container.State.Running {
 		return fmt.Errorf("The container %s is already running.", container.Id)
 	}
@@ -404,6 +412,9 @@ func (container *Container) Start() error {
 	// FIXME: save state on disk *first*, then converge
 	// this way disk state is used as a journal, eg. we can restore after crash etc.
 	container.State.setRunning(container.cmd.Process.Pid)
+
+	// Init the lock
+	container.waitLock = make(chan struct{})
 	container.ToDisk()
 	go container.monitor()
 	return nil
@@ -456,15 +467,16 @@ func (container *Container) allocateNetwork() error {
 		return err
 	}
 	container.NetworkSettings.PortMapping = make(map[string]string)
-	for _, port := range container.Config.Ports {
-		if extPort, err := iface.AllocatePort(port); err != nil {
+	for _, spec := range container.Config.PortSpecs {
+		if nat, err := iface.AllocatePort(spec); err != nil {
 			iface.Release()
 			return err
 		} else {
-			container.NetworkSettings.PortMapping[strconv.Itoa(port)] = strconv.Itoa(extPort)
+			container.NetworkSettings.PortMapping[strconv.Itoa(nat.Backend)] = strconv.Itoa(nat.Frontend)
 		}
 	}
 	container.network = iface
+	container.NetworkSettings.Bridge = container.runtime.networkManager.bridgeIface
 	container.NetworkSettings.IpAddress = iface.IPNet.IP.String()
 	container.NetworkSettings.IpPrefixLen, _ = iface.IPNet.Mask.Size()
 	container.NetworkSettings.Gateway = iface.Gateway.String()
@@ -502,19 +514,9 @@ func (container *Container) monitor() {
 		Debugf("%s: Error close stderr: %s", container.Id, err)
 	}
 
-	if container.ptyStdinMaster != nil {
-		if err := container.ptyStdinMaster.Close(); err != nil {
-			Debugf("%s: Error close pty stdin master: %s", container.Id, err)
-		}
-	}
-	if container.ptyStdoutMaster != nil {
-		if err := container.ptyStdoutMaster.Close(); err != nil {
-			Debugf("%s: Error close pty stdout master: %s", container.Id, err)
-		}
-	}
-	if container.ptyStderrMaster != nil {
-		if err := container.ptyStderrMaster.Close(); err != nil {
-			Debugf("%s: Error close pty stderr master: %s", container.Id, err)
+	if container.ptyMaster != nil {
+		if err := container.ptyMaster.Close(); err != nil {
+			Debugf("%s: Error closing Pty master: %s", container.Id, err)
 		}
 	}
 
@@ -529,6 +531,10 @@ func (container *Container) monitor() {
 
 	// Report status back
 	container.State.setStopped(exitCode)
+
+	// Release the lock
+	close(container.waitLock)
+
 	if err := container.ToDisk(); err != nil {
 		// FIXME: there is a race condition here which causes this to fail during the unit tests.
 		// If another goroutine was waiting for Wait() to return before removing the container's root
@@ -541,7 +547,7 @@ func (container *Container) monitor() {
 }
 
 func (container *Container) kill() error {
-	if container.cmd == nil {
+	if !container.State.Running || container.cmd == nil {
 		return nil
 	}
 	if err := container.cmd.Process.Kill(); err != nil {
@@ -553,13 +559,14 @@ func (container *Container) kill() error {
 }
 
 func (container *Container) Kill() error {
-	if !container.State.Running {
-		return nil
-	}
+	container.State.lock()
+	defer container.State.unlock()
 	return container.kill()
 }
 
 func (container *Container) Stop() error {
+	container.State.lock()
+	defer container.State.unlock()
 	if !container.State.Running {
 		return nil
 	}
@@ -568,7 +575,7 @@ func (container *Container) Stop() error {
 	if output, err := exec.Command("lxc-kill", "-n", container.Id, "15").CombinedOutput(); err != nil {
 		log.Print(string(output))
 		log.Print("Failed to send SIGTERM to the process, force killing")
-		if err := container.Kill(); err != nil {
+		if err := container.kill(); err != nil {
 			return err
 		}
 	}
@@ -576,7 +583,7 @@ func (container *Container) Stop() error {
 	// 2. Wait for the process to exit on its own
 	if err := container.WaitTimeout(10 * time.Second); err != nil {
 		log.Printf("Container %v failed to exit within 10 seconds of SIGTERM - using the force", container.Id)
-		if err := container.Kill(); err != nil {
+		if err := container.kill(); err != nil {
 			return err
 		}
 	}
@@ -595,10 +602,7 @@ func (container *Container) Restart() error {
 
 // Wait blocks until the container stops running, then returns its exit code.
 func (container *Container) Wait() int {
-
-	for container.State.Running {
-		container.State.wait()
-	}
+	<-container.waitLock
 	return container.State.ExitCode
 }
 
@@ -626,7 +630,7 @@ func (container *Container) WaitTimeout(timeout time.Duration) error {
 	case <-done:
 		return nil
 	}
-	return nil
+	panic("unreachable")
 }
 
 func (container *Container) EnsureMounted() error {

container_test.go

@@ -267,6 +267,7 @@ func TestStart(t *testing.T) {
 	// Try to avoid the timeoout in destroy. Best effort, don't check error
 	cStdin, _ := container.StdinPipe()
 	cStdin.Close()
+	container.WaitTimeout(2 * time.Second)
 }
 
 func TestRun(t *testing.T) {

docker/docker.go

@@ -8,7 +8,6 @@ import (
 	"io"
 	"log"
 	"os"
-	"os/signal"
 )
 
 var GIT_COMMIT string
@@ -22,7 +21,13 @@ func main() {
 	// FIXME: Switch d and D ? (to be more sshd like)
 	flDaemon := flag.Bool("d", false, "Daemon mode")
 	flDebug := flag.Bool("D", false, "Debug mode")
+	bridgeName := flag.String("b", "", "Attach containers to a pre-existing network bridge")
 	flag.Parse()
+	if *bridgeName != "" {
+		docker.NetworkBridgeIface = *bridgeName
+	} else {
+		docker.NetworkBridgeIface = docker.DefaultNetworkBridge
+	}
 	if *flDebug {
 		os.Setenv("DEBUG", "1")
 	}
@@ -51,29 +56,21 @@ func daemon() error {
 }
 
 func runCommand(args []string) error {
-	var oldState *term.State
-	var err error
-	if term.IsTerminal(int(os.Stdin.Fd())) && os.Getenv("NORAW") == "" {
-		oldState, err = term.MakeRaw(int(os.Stdin.Fd()))
-		if err != nil {
-			return err
-		}
-		defer term.Restore(int(os.Stdin.Fd()), oldState)
-		c := make(chan os.Signal, 1)
-		signal.Notify(c, os.Interrupt)
-		go func() {
-			for _ = range c {
-				term.Restore(int(os.Stdin.Fd()), oldState)
-				log.Printf("\nSIGINT received\n")
-				os.Exit(0)
-			}
-		}()
-	}
 	// FIXME: we want to use unix sockets here, but net.UnixConn doesn't expose
 	// CloseWrite(), which we need to cleanly signal that stdin is closed without
 	// closing the connection.
 	// See http://code.google.com/p/go/issues/detail?id=3345
 	if conn, err := rcli.Call("tcp", "127.0.0.1:4242", args...); err == nil {
+		options := conn.GetOptions()
+		if options.RawTerminal &&
+			term.IsTerminal(int(os.Stdin.Fd())) &&
+			os.Getenv("NORAW") == "" {
+			if oldState, err := rcli.SetRawTerminal(); err != nil {
+				return err
+			} else {
+				defer rcli.RestoreTerminal(oldState)
+			}
+		}
 		receiveStdout := docker.Go(func() error {
 			_, err := io.Copy(os.Stdout, conn)
 			return err
@@ -98,12 +95,11 @@ func runCommand(args []string) error {
 		if err != nil {
 			return err
 		}
-		if err := rcli.LocalCall(service, os.Stdin, os.Stdout, args...); err != nil {
+		dockerConn := rcli.NewDockerLocalConn(os.Stdout)
+		defer dockerConn.Close()
+		if err := rcli.LocalCall(service, os.Stdin, dockerConn, args...); err != nil {
 			return err
 		}
 	}
-	if oldState != nil {
-		term.Restore(int(os.Stdin.Fd()), oldState)
-	}
 	return nil
 }

docs/README.md

@@ -39,4 +39,36 @@ Notes
 * The index.html and gettingstarted.html files are copied from the source dir to the output dir without modification.
 So changes to those pages should be made directly in html
 * For the template the css is compiled from less. When changes are needed they can be compiled using
-lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
+lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
+
+
+Guides on using sphinx
+----------------------
+* To make links to certain pages create a link target like so:
+
+  ```
+    .. _hello_world:
+
+    Hello world
+    ===========
+
+    This is.. (etc.)
+  ```
+
+  The ``_hello_world:`` will make it possible to link to this position (page and marker) from all other pages.
+
+* Notes, warnings and alarms
+
+  ```
+    # a note (use when something is important)
+    .. note::
+
+    # a warning (orange)
+    .. warning::
+
+    # danger (red, use sparsely)
+    .. danger::
+
+* Code examples
+
+  Start without $, so it's easy to copy and paste.

docs/sources/commandline/basics.rst

@@ -69,7 +69,8 @@ Expose a service on a TCP port
 
   # Connect to the public port via the host's public address
   # Please note that because of how routing works connecting to localhost or 127.0.0.1 $PORT will not work.
-  echo hello world | nc $(hostname) $PORT
+  IP=$(ifconfig eth0 | perl -n -e 'if (m/inet addr:([\d\.]+)/g) { print $1 }')
+  echo hello world | nc $IP $PORT
 
   # Verify that the network connection worked
   echo "Daemon received: $(docker logs $JOB)"

docs/sources/commandline/cli.rst

@@ -10,312 +10,44 @@ Command Line Interface
 Docker Usage
 ~~~~~~~~~~~~
 
-::
+To list available commands, either run ``docker`` with no parameters or execute
+``docker help``::
 
   $ docker
     Usage: docker COMMAND [arg...]
 
     A self-sufficient runtime for linux containers.
 
-    Commands:
-        attach    Attach to a running container
-        commit    Create a new image from a container's changes
-        diff      Inspect changes on a container's filesystem
-        export    Stream the contents of a container as a tar archive
-        history   Show the history of an image
-        images    List images
-        import    Create a new filesystem image from the contents of a tarball
-        info      Display system-wide information
-        inspect   Return low-level information on a container
-        kill      Kill a running container
-        login     Register or Login to the docker registry server
-        logs      Fetch the logs of a container
-        port      Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
-        ps        List containers
-        pull      Pull an image or a repository to the docker registry server
-        push      Push an image or a repository to the docker registry server
-        restart   Restart a running container
-        rm        Remove a container
-        rmi       Remove an image
-        run       Run a command in a new container
-        start     Start a stopped container
-        stop      Stop a running container
-        tag       Tag an image into a repository
-        version   Show the docker version information
-        wait      Block until a container stops, then print its exit code
-
-
-attach
-~~~~~~
-
-::
-
-  Usage: docker attach [OPTIONS]
-
-  Attach to a running container
-
-    -e=true: Attach to stderr
-    -i=false: Attach to stdin
-    -o=true: Attach to stdout
-
-
-commit
-~~~~~~
-
-::
-
-  Usage: docker commit [OPTIONS] CONTAINER [DEST]
-
-  Create a new image from a container's changes
-
-  -m="": Commit message
-
-
-diff
-~~~~
-
-::
-
-  Usage: docker diff CONTAINER [OPTIONS]
-
-  Inspect changes on a container's filesystem
-
-
-export
-~~~~~~
-
-::
-
-    Usage: docker export CONTAINER
-
-    Export the contents of a filesystem as a tar archive
-
-
-history
-~~~~~~~
-
-::
-
-    Usage: docker history [OPTIONS] IMAGE
-
-    Show the history of an image
-
-
-images
-~~~~~~
-
-::
-
-  Usage: docker images [OPTIONS] [NAME]
-
-  List images
-
-    -a=false: show all images
-    -q=false: only show numeric IDs
-
-
-import
-~~~~~~
-
-::
-
-    Usage: docker import [OPTIONS] URL|- [REPOSITORY [TAG]]
-
-    Create a new filesystem image from the contents of a tarball
-
-
-info
-~~~~
-
-::
-
-  Usage: docker info
-
-  Display system-wide information.
-
-
-inspect
-~~~~~~~
-
-::
-
-  Usage: docker inspect [OPTIONS] CONTAINER
-
-  Return low-level information on a container
-
-
-kill
-~~~~
-
-::
-
-  Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...]
-
-  Kill a running container
-
-
-login
-~~~~~
-
-::
-
-  Usage: docker login
-
-  Register or Login to the docker registry server
-
-
-logs
-~~~~
-
-::
-
-  Usage: docker logs [OPTIONS] CONTAINER
-
-  Fetch the logs of a container
-
-
-port
-~~~~
-
-::
-
-    Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT
-
-    Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
-
-
-ps
-~~
-
-::
-
-    Usage: docker ps [OPTIONS]
-
-    List containers
-
-      -a=false: Show all containers. Only running containers are shown by default.
-      -notrunc=false: Don't truncate output
-      -q=false: Only display numeric IDs
-
-
-pull
-~~~~
-
-::
-
-    Usage: docker pull NAME
-
-    Pull an image or a repository from the registry
-
-push
-~~~~
-
-::
-
-    Usage: docker push NAME
-
-    Push an image or a repository to the registry
-
-
-restart
-~~~~~~~
-
-::
-
-  Usage: docker restart [OPTIONS] NAME
-
-  Restart a running container
-
-
-rm
-~~
-
-::
-
-  Usage: docker rm [OPTIONS] CONTAINER
-
-  Remove a container
-
-
-rmi
-~~~
-
-::
-
-  Usage: docker rmi [OPTIONS] IMAGE
-
-  Remove an image
-
-    -a=false: Use IMAGE as a path and remove ALL images in this path
-    -r=false: Use IMAGE as a regular expression instead of an exact name
-
-
-run
-~~~
-
-::
-
-  Usage: docker run [OPTIONS] IMAGE COMMAND [ARG...]
-
-  Run a command in a new container
-
-    -c="": Comment
-    -i=false: Keep stdin open even if not attached
-    -m=0: Memory limit (in bytes)
-    -p=[]: Map a network port to the container
-    -t=false: Allocate a pseudo-tty
-    -h="": Container host name
-    -u="": Username or UID
-
-
-start
-~~~~~
-
-::
-
-  Usage: docker start [OPTIONS] NAME
-
-  Start a stopped container
-
-
-stop
-~~~~
-
-::
-
-  Usage: docker stop [OPTIONS] NAME
-
-  Stop a running container
-
-
-tag
-~~~
-
-::
-
-    Usage: docker tag [OPTIONS] IMAGE REPOSITORY [TAG]
-
-    Tag an image into a repository
-
-      -f=false: Force
-
-
-version
-~~~~~~~
-
-::
-
-  Usage: docker version
-
-  Show the docker version information
-
-
-wait
-~~~~
-
-::
-
-  Usage: docker wait [OPTIONS] NAME
-
-  Block until a container stops, then print its exit code.
-
+    ...
+
+Available Commands
+~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   command/attach
+   command/commit
+   command/diff
+   command/export
+   command/history
+   command/images
+   command/import
+   command/info
+   command/inspect
+   command/kill
+   command/login
+   command/logs
+   command/port
+   command/ps
+   command/pull
+   command/push
+   command/restart
+   command/rm
+   command/rmi
+   command/run
+   command/start
+   command/stop
+   command/tag
+   command/version
+   command/wait

docs/sources/commandline/command/attach.rst

@@ -0,0 +1,9 @@
+===========================================
+``attach`` -- Attach to a running container
+===========================================
+
+::
+
+    Usage: docker attach CONTAINER
+
+    Attach to a running container

docs/sources/commandline/command/commit.rst

@@ -0,0 +1,11 @@
+===========================================================
+``commit`` -- Create a new image from a container's changes
+===========================================================
+
+::
+
+    Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY [TAG]]
+
+    Create a new image from a container's changes
+
+      -m="": Commit message

docs/sources/commandline/command/diff.rst

@@ -0,0 +1,9 @@
+=======================================================
+``diff`` -- Inspect changes on a container's filesystem
+=======================================================
+
+::
+
+    Usage: docker diff CONTAINER [OPTIONS]
+
+    Inspect changes on a container's filesystem

docs/sources/commandline/command/export.rst

@@ -0,0 +1,9 @@
+=================================================================
+``export`` -- Stream the contents of a container as a tar archive
+=================================================================
+
+::
+
+    Usage: docker export CONTAINER
+
+    Export the contents of a filesystem as a tar archive

docs/sources/commandline/command/history.rst

@@ -0,0 +1,9 @@
+===========================================
+``history`` -- Show the history of an image
+===========================================
+
+::
+
+    Usage: docker history [OPTIONS] IMAGE
+
+    Show the history of an image

docs/sources/commandline/command/images.rst

@@ -0,0 +1,12 @@
+=========================
+``images`` -- List images
+=========================
+
+::
+
+    Usage: docker images [OPTIONS] [NAME]
+
+    List images
+
+      -a=false: show all images
+      -q=false: only show numeric IDs

docs/sources/commandline/command/import.rst

@@ -0,0 +1,9 @@
+==========================================================================
+``import`` -- Create a new filesystem image from the contents of a tarball
+==========================================================================
+
+::
+
+    Usage: docker import [OPTIONS] URL|- [REPOSITORY [TAG]]
+
+    Create a new filesystem image from the contents of a tarball

docs/sources/commandline/command/info.rst

@@ -0,0 +1,9 @@
+===========================================
+``info`` -- Display system-wide information
+===========================================
+
+::
+
+    Usage: docker info
+
+    Display system-wide information.

docs/sources/commandline/command/inspect.rst

@@ -0,0 +1,9 @@
+==========================================================
+``inspect`` -- Return low-level information on a container
+==========================================================
+
+::
+
+    Usage: docker inspect [OPTIONS] CONTAINER
+
+    Return low-level information on a container

docs/sources/commandline/command/kill.rst

@@ -0,0 +1,9 @@
+====================================
+``kill`` -- Kill a running container
+====================================
+
+::
+
+    Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...]
+
+    Kill a running container

docs/sources/commandline/command/login.rst

@@ -0,0 +1,9 @@
+============================================================
+``login`` -- Register or Login to the docker registry server
+============================================================
+
+::
+
+    Usage: docker login
+
+    Register or Login to the docker registry server

docs/sources/commandline/command/logs.rst

@@ -0,0 +1,9 @@
+=========================================
+``logs`` -- Fetch the logs of a container
+=========================================
+
+::
+
+    Usage: docker logs [OPTIONS] CONTAINER
+
+    Fetch the logs of a container

docs/sources/commandline/command/port.rst

@@ -0,0 +1,9 @@
+=========================================================================
+``port`` -- Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
+=========================================================================
+
+::
+
+    Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT
+
+    Lookup the public-facing port which is NAT-ed to PRIVATE_PORT

docs/sources/commandline/command/ps.rst

@@ -0,0 +1,13 @@
+=========================
+``ps`` -- List containers
+=========================
+
+::
+
+    Usage: docker ps [OPTIONS]
+
+    List containers
+
+      -a=false: Show all containers. Only running containers are shown by default.
+      -notrunc=false: Don't truncate output
+      -q=false: Only display numeric IDs

docs/sources/commandline/command/pull.rst

@@ -0,0 +1,9 @@
+=========================================================================
+``pull`` -- Pull an image or a repository from the docker registry server
+=========================================================================
+
+::
+
+    Usage: docker pull NAME
+
+    Pull an image or a repository from the registry

docs/sources/commandline/command/push.rst

@@ -0,0 +1,9 @@
+=======================================================================
+``push`` -- Push an image or a repository to the docker registry server
+=======================================================================
+
+::
+
+    Usage: docker push NAME
+
+    Push an image or a repository to the registry

docs/sources/commandline/command/restart.rst

@@ -0,0 +1,9 @@
+==========================================
+``restart`` -- Restart a running container
+==========================================
+
+::
+
+    Usage: docker restart [OPTIONS] NAME
+
+    Restart a running container

docs/sources/commandline/command/rm.rst

@@ -0,0 +1,9 @@
+============================
+``rm`` -- Remove a container
+============================
+
+::
+
+    Usage: docker rm [OPTIONS] CONTAINER
+
+    Remove a container

docs/sources/commandline/command/rmi.rst

@@ -0,0 +1,9 @@
+==========================
+``rmi`` -- Remove an image
+==========================
+
+::
+
+    Usage: docker rmimage [OPTIONS] IMAGE
+
+    Remove an image

docs/sources/commandline/command/run.rst

@@ -0,0 +1,19 @@
+===========================================
+``run`` -- Run a command in a new container
+===========================================
+
+::
+
+    Usage: docker run [OPTIONS] IMAGE COMMAND [ARG...]
+
+    Run a command in a new container
+
+      -a=map[]: Attach to stdin, stdout or stderr.
+      -d=false: Detached mode: leave the container running in the background
+      -e=[]: Set environment variables
+      -h="": Container host name
+      -i=false: Keep stdin open even if not attached
+      -m=0: Memory limit (in bytes)
+      -p=[]: Map a network port to the container
+      -t=false: Allocate a pseudo-tty
+      -u="": Username or UID

docs/sources/commandline/command/start.rst

@@ -0,0 +1,9 @@
+======================================
+``start`` -- Start a stopped container
+======================================
+
+::
+
+    Usage: docker start [OPTIONS] NAME
+
+    Start a stopped container

docs/sources/commandline/command/stop.rst

@@ -0,0 +1,9 @@
+====================================
+``stop`` -- Stop a running container
+====================================
+
+::
+
+    Usage: docker stop [OPTIONS] NAME
+
+    Stop a running container

docs/sources/commandline/command/tag.rst

@@ -0,0 +1,11 @@
+=========================================
+``tag`` -- Tag an image into a repository
+=========================================
+
+::
+
+    Usage: docker tag [OPTIONS] IMAGE REPOSITORY [TAG]
+
+    Tag an image into a repository
+
+      -f=false: Force

docs/sources/commandline/command/version.rst

@@ -0,0 +1,3 @@
+==================================================
+``version`` -- Show the docker version information
+==================================================

docs/sources/commandline/command/wait.rst

@@ -0,0 +1,9 @@
+===================================================================
+``wait`` -- Block until a container stops, then print its exit code
+===================================================================
+
+::
+
+    Usage: docker wait [OPTIONS] NAME
+
+    Block until a container stops, then print its exit code.

docs/sources/examples/example_header.inc

@@ -0,0 +1,4 @@
+
+.. note::
+    
+    This example assumes you have Docker running in daemon mode. For more information please see :ref:`running_examples`

docs/sources/examples/hello_world.rst

@@ -6,8 +6,10 @@
 
 Hello World
 ===========
-This is the most basic example available for using Docker. The example assumes you have Docker installed.
 
+.. include:: example_header.inc
+
+This is the most basic example available for using Docker.
 
 Download the base container
 

docs/sources/examples/hello_world_daemon.rst

@@ -6,6 +6,9 @@
 
 Hello World Daemon
 ==================
+
+.. include:: example_header.inc
+
 The most boring daemon ever written.
 
 This example assumes you have Docker installed and with the base image already imported ``docker pull base``.
@@ -18,7 +21,7 @@ out every second. It will continue to do this until we stop it.
 
     CONTAINER_ID=$(docker run -d base /bin/sh -c "while true; do echo hello world; sleep 1; done")
 
-We are going to run a simple hello world daemon in a new container made from the busybox daemon.
+We are going to run a simple hello world daemon in a new container made from the base image.
 
 - **"docker run -d "** run a command in a new container. We pass "-d" so it runs as a daemon.
 - **"base"** is the image we want to run the command inside of.

docs/sources/examples/index.rst

@@ -12,7 +12,8 @@ Contents:
 .. toctree::
    :maxdepth: 1
 
+   running_examples
    hello_world
    hello_world_daemon
    python_web_app
-   runningsshservice
+   running_ssh_service

docs/sources/examples/python_web_app.rst

@@ -6,6 +6,9 @@
 
 Building a python web app
 =========================
+
+.. include:: example_header.inc
+
 The goal of this example is to show you how you can author your own docker images using a parent image, making changes to it, and then saving the results as a new image. We will do that by making a simple hello flask web application image.
 
 **Steps:**
@@ -45,6 +48,11 @@ Save the changed we just made in the container to a new image called "_/builds/g
 
     WEB_WORKER=$(docker run -d -p 5000 $BUILD_IMG /usr/local/bin/runapp)
 
+- **"docker run -d "** run a command in a new container. We pass "-d" so it runs as a daemon.
+  **"-p 5000"* the web app is going to listen on this port, so it must be mapped from the container to the host system.
+- **"$BUILD_IMG"** is the image we want to run the command inside of.
+- **/usr/local/bin/runapp** is the command which starts the web app.
+
 Use the new image we just created and create a new container with network port 5000, and return the container id and store in the WEB_WORKER variable.
 
 .. code-block:: bash
@@ -54,6 +62,18 @@ Use the new image we just created and create a new container with network port 5
 
 view the logs for the new container using the WEB_WORKER variable, and if everything worked as planned you should see the line "Running on http://0.0.0.0:5000/" in the log output.
 
+.. code-block:: bash
+
+    WEB_PORT=$(docker port $WEB_WORKER 5000)
+
+lookup the public-facing port which is NAT-ed store the private port used by the container and store it inside of the WEB_PORT variable.
+
+.. code-block:: bash
+
+    curl http://`hostname`:$WEB_PORT
+      Hello world!
+
+access the web app using curl. If everything worked as planned you should see the line "Hello world!" inside of your console.
 
 **Video:**
 
@@ -65,6 +85,4 @@ See the example in action
       <iframe width="720" height="350" src="http://ascii.io/a/2573/raw" frameborder="0"></iframe>
     </div>
 
-Continue to the `base commands`_
-
-.. _base commands: ../commandline/basecommands.html
+Continue to :ref:`running_ssh_service`.

docs/sources/examples/running_examples.rst

@@ -0,0 +1,33 @@
+:title: Running the Examples
+:description: An overview on how to run the docker examples
+:keywords: docker, examples, how to
+
+.. _running_examples:
+
+Running The Examples
+--------------------
+
+There are two ways to run docker, daemon mode and standalone mode.
+
+When you run the docker command it will first check if there is a docker daemon running in the background it can connect to.
+
+* If it exists it will use that daemon to run all of the commands.
+* If it does not exist docker will run in standalone mode (docker will exit after each command).
+
+Docker needs to be run from a privileged account (root).
+
+1. The most common (and recommended) way is to run a docker daemon as root in the background, and then connect to it from the docker client from any account.
+
+   .. code-block:: bash
+
+      # starting docker daemon in the background
+      sudo docker -d &
+
+      # now you can run docker commands from any account.
+      docker <command>
+
+2. Standalone: You need to run every command as root, or using sudo
+
+   .. code-block:: bash
+
+       sudo docker <command>

docs/sources/examples/running_ssh_service.rst

@@ -1,8 +1,13 @@
+:title: Running an SSH service
+:description: A screencast of installing and running an sshd service
+:keywords: docker, example, package installation, networking
+
+.. _running_ssh_service:
 
 Create an ssh daemon service
 ============================
 
-
+.. include:: example_header.inc
 
 
 **Video:**

docs/theme/docker/static/css/main.css

@@ -82,7 +82,7 @@ h4 {
 .btn-custom {
   background-color: #292929 !important;
   background-repeat: repeat-x;
-  filter: progid:dximagetransform.microsoft.gradient(startColorstr="#515151", endColorstr="#282828");
+  filter: progid:DXImageTransform.Microsoft.gradient(startColorstr="#515151", endColorstr="#282828");
   background-image: -khtml-gradient(linear, left top, left bottom, from(#515151), to(#282828));
   background-image: -moz-linear-gradient(top, #515151, #282828);
   background-image: -ms-linear-gradient(top, #515151, #282828);
@@ -131,6 +131,27 @@ section.header {
   margin: 15px 15px 15px 0;
   border: 2px solid gray;
 }
+.admonition {
+  padding: 10px;
+  border: 1px solid grey;
+  margin-bottom: 10px;
+  margin-top: 10px;
+  -webkit-border-radius: 4px;
+  -moz-border-radius: 4px;
+  border-radius: 4px;
+}
+.admonition .admonition-title {
+  font-weight: bold;
+}
+.admonition.note {
+  background-color: #f1ebba;
+}
+.admonition.warning {
+  background-color: #eed9af;
+}
+.admonition.danger {
+  background-color: #e9bcab;
+}
 /* ===================
 	left navigation
 ===================== */

docs/theme/docker/static/css/main.less

@@ -179,7 +179,33 @@ section.header {
   border: 2px solid gray;
 }
 
+.admonition {
+  padding: 10px;
+  border: 1px solid grey;
 
+  margin-bottom: 10px;
+  margin-top: 10px;
+
+  -webkit-border-radius: 4px;
+  -moz-border-radius: 4px;
+  border-radius: 4px;
+}
+
+.admonition .admonition-title {
+  font-weight: bold;
+}
+
+.admonition.note {
+  background-color: rgb(241, 235, 186);
+}
+
+.admonition.warning {
+  background-color: rgb(238, 217, 175);
+}
+
+.admonition.danger {
+  background-color: rgb(233, 188, 171);
+}
 
 /* ===================
 	left navigation

graph.go

@@ -85,9 +85,10 @@ func (graph *Graph) Get(name string) (*Image, error) {
 // Create creates a new image and registers it in the graph.
 func (graph *Graph) Create(layerData Archive, container *Container, comment string) (*Image, error) {
 	img := &Image{
-		Id:      GenerateId(),
-		Comment: comment,
-		Created: time.Now(),
+		Id:            GenerateId(),
+		Comment:       comment,
+		Created:       time.Now(),
+		DockerVersion: VERSION,
 	}
 	if container != nil {
 		img.Parent = container.Image
@@ -129,6 +130,9 @@ func (graph *Graph) Register(layerData Archive, img *Image) error {
 
 // Mktemp creates a temporary sub-directory inside the graph's filesystem.
 func (graph *Graph) Mktemp(id string) (string, error) {
+	if id == "" {
+		id = GenerateId()
+	}
 	tmp, err := NewGraph(path.Join(graph.Root, ":tmp:"))
 	if err != nil {
 		return "", fmt.Errorf("Couldn't create temp: %s", err)
@@ -139,13 +143,6 @@ func (graph *Graph) Mktemp(id string) (string, error) {
 	return tmp.imageRoot(id), nil
 }
 
-// Garbage returns the "garbage", a staging area for deleted images.
-// This allows images to be deleted atomically by os.Rename(), instead of
-// os.RemoveAll() which is prone to race conditions.
-func (graph *Graph) Garbage() (*Graph, error) {
-	return NewGraph(path.Join(graph.Root, ":garbage:"))
-}
-
 // Check if given error is "not empty".
 // Note: this is the way golang does it internally with os.IsNotExists.
 func isNotEmpty(err error) bool {
@@ -166,54 +163,16 @@ func (graph *Graph) Delete(name string) error {
 	if err != nil {
 		return err
 	}
-	garbage, err := graph.Garbage()
+	tmp, err := graph.Mktemp("")
 	if err != nil {
 		return err
 	}
 	graph.idIndex.Delete(id)
-	err = os.Rename(graph.imageRoot(id), garbage.imageRoot(id))
-	if err != nil {
-		// FIXME: this introduces a race condition in Delete() if the image is already present
-		// in garbage. Let's store at random names in grabage instead.
-		if isNotEmpty(err) {
-			Debugf("The image %s is already present in garbage. Removing it.", id)
-			if err = os.RemoveAll(garbage.imageRoot(id)); err != nil {
-				Debugf("Error while removing the image %s from garbage: %s\n", id, err)
-				return err
-			}
-			Debugf("Image %s removed from garbage", id)
-			if err = os.Rename(graph.imageRoot(id), garbage.imageRoot(id)); err != nil {
-				return err
-			}
-			Debugf("Image %s put in the garbage", id)
-		} else {
-			Debugf("Error putting the image %s to garbage: %s\n", id, err)
-		}
-		return err
-	}
-	return nil
-}
-
-// Undelete moves an image back from the garbage to the main graph.
-func (graph *Graph) Undelete(id string) error {
-	garbage, err := graph.Garbage()
+	err = os.Rename(graph.imageRoot(id), tmp)
 	if err != nil {
 		return err
 	}
-	if err := os.Rename(garbage.imageRoot(id), graph.imageRoot(id)); err != nil {
-		return err
-	}
-	graph.idIndex.Add(id)
-	return nil
-}
-
-// GarbageCollect definitely deletes all images moved to the garbage.
-func (graph *Graph) GarbageCollect() error {
-	garbage, err := graph.Garbage()
-	if err != nil {
-		return err
-	}
-	return os.RemoveAll(garbage.Root)
+	return os.RemoveAll(tmp)
 }
 
 // Map returns a list of all images in the graph, addressable by ID.

graph_test.go

@@ -45,6 +45,9 @@ func TestGraphCreate(t *testing.T) {
 	if image.Comment != "Testing" {
 		t.Fatalf("Wrong comment: should be '%s', not '%s'", "Testing", image.Comment)
 	}
+	if image.DockerVersion != VERSION {
+		t.Fatalf("Wrong docker_version: should be '%s', not '%s'", VERSION, image.DockerVersion)
+	}
 	if images, err := graph.All(); err != nil {
 		t.Fatal(err)
 	} else if l := len(images); l != 1 {

image.go

@@ -20,6 +20,7 @@ type Image struct {
 	Created         time.Time `json:"created"`
 	Container       string    `json:"container,omitempty"`
 	ContainerConfig Config    `json:"container_config,omitempty"`
+	DockerVersion   string    `json:"docker_version,omitempty"`
 	graph           *Graph
 }
 

lxc_template.go

@@ -16,7 +16,7 @@ lxc.utsname = {{.Id}}
 # network configuration
 lxc.network.type = veth
 lxc.network.flags = up
-lxc.network.link = lxcbr0
+lxc.network.link = {{.NetworkSettings.Bridge}}
 lxc.network.name = eth0
 lxc.network.mtu = 1500
 lxc.network.ipv4 = {{.NetworkSettings.IpAddress}}/{{.NetworkSettings.IpPrefixLen}}

network.go

@@ -9,12 +9,15 @@ import (
 	"os/exec"
 	"strconv"
 	"strings"
+	"sync"
 )
 
+var NetworkBridgeIface string
+
 const (
-	networkBridgeIface = "lxcbr0"
-	portRangeStart     = 49153
-	portRangeEnd       = 65535
+	DefaultNetworkBridge = "docker0"
+	portRangeStart       = 49153
+	portRangeEnd         = 65535
 )
 
 // Calculates the first and last IP addresses in an IPNet
@@ -28,6 +31,19 @@ func networkRange(network *net.IPNet) (net.IP, net.IP) {
 	return firstIP, lastIP
 }
 
+// Detects overlap between one IPNet and another
+func networkOverlaps(netX *net.IPNet, netY *net.IPNet) bool {
+	firstIP, _ := networkRange(netX)
+	if netY.Contains(firstIP) {
+		return true
+	}
+	firstIP, _ = networkRange(netY)
+	if netX.Contains(firstIP) {
+		return true
+	}
+	return false
+}
+
 // Converts a 4 bytes IP into a 32 bit integer
 func ipToInt(ip net.IP) int32 {
 	return int32(binary.BigEndian.Uint32(ip.To4()))
@@ -50,6 +66,19 @@ func networkSize(mask net.IPMask) int32 {
 	return int32(binary.BigEndian.Uint32(m)) + 1
 }
 
+//Wrapper around the ip command
+func ip(args ...string) (string, error) {
+	path, err := exec.LookPath("ip")
+	if err != nil {
+		return "", fmt.Errorf("command not found: ip")
+	}
+	output, err := exec.Command(path, args...).CombinedOutput()
+	if err != nil {
+		return "", fmt.Errorf("ip failed: ip %v", strings.Join(args, " "))
+	}
+	return string(output), nil
+}
+
 // Wrapper around the iptables command
 func iptables(args ...string) error {
 	path, err := exec.LookPath("iptables")
@@ -62,6 +91,66 @@ func iptables(args ...string) error {
 	return nil
 }
 
+func checkRouteOverlaps(dockerNetwork *net.IPNet) error {
+	output, err := ip("route")
+	if err != nil {
+		return err
+	}
+	Debugf("Routes:\n\n%s", output)
+	for _, line := range strings.Split(output, "\n") {
+		if strings.Trim(line, "\r\n\t ") == "" || strings.Contains(line, "default") {
+			continue
+		}
+		if _, network, err := net.ParseCIDR(strings.Split(line, " ")[0]); err != nil {
+			return fmt.Errorf("Unexpected ip route output: %s (%s)", err, line)
+		} else if networkOverlaps(dockerNetwork, network) {
+			return fmt.Errorf("Network %s is already routed: '%s'", dockerNetwork.String(), line)
+		}
+	}
+	return nil
+}
+
+func CreateBridgeIface(ifaceName string) error {
+	// FIXME: try more IP ranges
+	// FIXME: try bigger ranges! /24 is too small.
+	addrs := []string{"172.16.42.1/24", "10.0.42.1/24", "192.168.42.1/24"}
+
+	var ifaceAddr string
+	for _, addr := range addrs {
+		_, dockerNetwork, err := net.ParseCIDR(addr)
+		if err != nil {
+			return err
+		}
+		if err := checkRouteOverlaps(dockerNetwork); err == nil {
+			ifaceAddr = addr
+			break
+		} else {
+			Debugf("%s: %s", addr, err)
+		}
+	}
+	if ifaceAddr == "" {
+		return fmt.Errorf("Could not find a free IP address range for interface '%s'. Please configure its address manually and run 'docker -b %s'", ifaceName, ifaceName)
+	} else {
+		Debugf("Creating bridge %s with network %s", ifaceName, ifaceAddr)
+	}
+
+	if output, err := ip("link", "add", ifaceName, "type", "bridge"); err != nil {
+		return fmt.Errorf("Error creating bridge: %s (output: %s)", err, output)
+	}
+
+	if output, err := ip("addr", "add", ifaceAddr, "dev", ifaceName); err != nil {
+		return fmt.Errorf("Unable to add private network: %s (%s)", err, output)
+	}
+	if output, err := ip("link", "set", ifaceName, "up"); err != nil {
+		return fmt.Errorf("Unable to start network bridge: %s (%s)", err, output)
+	}
+	if err := iptables("-t", "nat", "-A", "POSTROUTING", "-s", ifaceAddr,
+		"!", "-d", ifaceAddr, "-j", "MASQUERADE"); err != nil {
+		return fmt.Errorf("Unable to enable network bridge NAT: %s", err)
+	}
+	return nil
+}
+
 // Return the IPv4 address of a network interface
 func getIfaceAddr(name string) (net.Addr, error) {
 	iface, err := net.InterfaceByName(name)
@@ -98,6 +187,9 @@ type PortMapper struct {
 
 func (mapper *PortMapper) cleanup() error {
 	// Ignore errors - This could mean the chains were never set up
+	iptables("-t", "nat", "-D", "PREROUTING", "-m", "addrtype", "--dst-type", "LOCAL", "-j", "DOCKER")
+	iptables("-t", "nat", "-D", "OUTPUT", "-m", "addrtype", "--dst-type", "LOCAL", "-j", "DOCKER")
+	// Also cleanup rules created by older versions, or -X might fail.
 	iptables("-t", "nat", "-D", "PREROUTING", "-j", "DOCKER")
 	iptables("-t", "nat", "-D", "OUTPUT", "-j", "DOCKER")
 	iptables("-t", "nat", "-F", "DOCKER")
@@ -110,10 +202,10 @@ func (mapper *PortMapper) setup() error {
 	if err := iptables("-t", "nat", "-N", "DOCKER"); err != nil {
 		return fmt.Errorf("Failed to create DOCKER chain: %s", err)
 	}
-	if err := iptables("-t", "nat", "-A", "PREROUTING", "-j", "DOCKER"); err != nil {
+	if err := iptables("-t", "nat", "-A", "PREROUTING", "-m", "addrtype", "--dst-type", "LOCAL", "-j", "DOCKER"); err != nil {
 		return fmt.Errorf("Failed to inject docker in PREROUTING chain: %s", err)
 	}
-	if err := iptables("-t", "nat", "-A", "OUTPUT", "-j", "DOCKER"); err != nil {
+	if err := iptables("-t", "nat", "-A", "OUTPUT", "-m", "addrtype", "--dst-type", "LOCAL", "-j", "DOCKER"); err != nil {
 		return fmt.Errorf("Failed to inject docker in OUTPUT chain: %s", err)
 	}
 	return nil
@@ -157,39 +249,54 @@ func newPortMapper() (*PortMapper, error) {
 
 // Port allocator: Atomatically allocate and release networking ports
 type PortAllocator struct {
-	ports chan (int)
+	inUse    map[int]struct{}
+	fountain chan (int)
+	lock     sync.Mutex
 }
 
-func (alloc *PortAllocator) populate(start, end int) {
-	alloc.ports = make(chan int, end-start)
-	for port := start; port < end; port++ {
-		alloc.ports <- port
+func (alloc *PortAllocator) runFountain() {
+	for {
+		for port := portRangeStart; port < portRangeEnd; port++ {
+			alloc.fountain <- port
+		}
 	}
 }
 
-func (alloc *PortAllocator) Acquire() (int, error) {
-	select {
-	case port := <-alloc.ports:
-		return port, nil
-	default:
-		return -1, errors.New("No more ports available")
-	}
-	return -1, nil
-}
-
+// FIXME: Release can no longer fail, change its prototype to reflect that.
 func (alloc *PortAllocator) Release(port int) error {
-	select {
-	case alloc.ports <- port:
-		return nil
-	default:
-		return errors.New("Too many ports have been released")
-	}
+	Debugf("Releasing %d", port)
+	alloc.lock.Lock()
+	delete(alloc.inUse, port)
+	alloc.lock.Unlock()
 	return nil
 }
 
-func newPortAllocator(start, end int) (*PortAllocator, error) {
-	allocator := &PortAllocator{}
-	allocator.populate(start, end)
+func (alloc *PortAllocator) Acquire(port int) (int, error) {
+	Debugf("Acquiring %d", port)
+	if port == 0 {
+		// Allocate a port from the fountain
+		for port := range alloc.fountain {
+			if _, err := alloc.Acquire(port); err == nil {
+				return port, nil
+			}
+		}
+		return -1, fmt.Errorf("Port generator ended unexpectedly")
+	}
+	alloc.lock.Lock()
+	defer alloc.lock.Unlock()
+	if _, inUse := alloc.inUse[port]; inUse {
+		return -1, fmt.Errorf("Port already in use: %d", port)
+	}
+	alloc.inUse[port] = struct{}{}
+	return port, nil
+}
+
+func newPortAllocator() (*PortAllocator, error) {
+	allocator := &PortAllocator{
+		inUse: make(map[int]struct{}),
+		fountain: make(chan int),
+	}
+	go allocator.runFountain()
 	return allocator, nil
 }
 
@@ -298,17 +405,50 @@ type NetworkInterface struct {
 }
 
 // Allocate an external TCP port and map it to the interface
-func (iface *NetworkInterface) AllocatePort(port int) (int, error) {
-	extPort, err := iface.manager.portAllocator.Acquire()
+func (iface *NetworkInterface) AllocatePort(spec string) (*Nat, error) {
+	nat, err := parseNat(spec)
 	if err != nil {
-		return -1, err
+		return nil, err
 	}
-	if err := iface.manager.portMapper.Map(extPort, net.TCPAddr{IP: iface.IPNet.IP, Port: port}); err != nil {
-		iface.manager.portAllocator.Release(extPort)
-		return -1, err
+	// Allocate a random port if Frontend==0
+	if extPort, err := iface.manager.portAllocator.Acquire(nat.Frontend); err != nil {
+		return nil, err
+	} else {
+		nat.Frontend = extPort
 	}
-	iface.extPorts = append(iface.extPorts, extPort)
-	return extPort, nil
+	if err := iface.manager.portMapper.Map(nat.Frontend, net.TCPAddr{IP: iface.IPNet.IP, Port: nat.Backend}); err != nil {
+		iface.manager.portAllocator.Release(nat.Frontend)
+		return nil, err
+	}
+	iface.extPorts = append(iface.extPorts, nat.Frontend)
+	return nat, nil
+}
+
+type Nat struct {
+	Proto    string
+	Frontend int
+	Backend  int
+}
+
+func parseNat(spec string) (*Nat, error) {
+	var nat Nat
+	// If spec starts with ':', external and internal ports must be the same.
+	// This might fail if the requested external port is not available.
+	var sameFrontend bool
+	if spec[0] == ':' {
+		sameFrontend = true
+		spec = spec[1:]
+	}
+	port, err := strconv.ParseUint(spec, 10, 16)
+	if err != nil {
+		return nil, err
+	}
+	nat.Backend = int(port)
+	if sameFrontend {
+		nat.Frontend = nat.Backend
+	}
+	nat.Proto = "tcp"
+	return &nat, nil
 }
 
 // Release: Network cleanup - release all resources
@@ -354,13 +494,20 @@ func (manager *NetworkManager) Allocate() (*NetworkInterface, error) {
 func newNetworkManager(bridgeIface string) (*NetworkManager, error) {
 	addr, err := getIfaceAddr(bridgeIface)
 	if err != nil {
-		return nil, err
+		// If the iface is not found, try to create it
+		if err := CreateBridgeIface(bridgeIface); err != nil {
+			return nil, err
+		}
+		addr, err = getIfaceAddr(bridgeIface)
+		if err != nil {
+			return nil, err
+		}
 	}
 	network := addr.(*net.IPNet)
 
 	ipAllocator := newIPAllocator(network)
 
-	portAllocator, err := newPortAllocator(portRangeStart, portRangeEnd)
+	portAllocator, err := newPortAllocator()
 	if err != nil {
 		return nil, err
 	}

network_test.go

@@ -18,6 +18,42 @@ func TestIptables(t *testing.T) {
 	}
 }
 
+func TestPortAllocation(t *testing.T) {
+	allocator, err := newPortAllocator()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if port, err := allocator.Acquire(80); err != nil {
+		t.Fatal(err)
+	} else if port != 80 {
+		t.Fatalf("Acquire(80) should return 80, not %d", port)
+	}
+	port, err := allocator.Acquire(0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if port <= 0 {
+		t.Fatalf("Acquire(0) should return a non-zero port")
+	}
+	if _, err := allocator.Acquire(port); err == nil {
+		t.Fatalf("Acquiring a port already in use should return an error")
+	}
+	if newPort, err := allocator.Acquire(0); err != nil {
+		t.Fatal(err)
+	} else if newPort == port {
+		t.Fatalf("Acquire(0) allocated the same port twice: %d", port)
+	}
+	if _, err := allocator.Acquire(80); err == nil {
+		t.Fatalf("Acquiring a port already in use should return an error")
+	}
+	if err := allocator.Release(80); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := allocator.Acquire(80); err != nil {
+		t.Fatal(err)
+	}
+}
+
 func TestNetworkRange(t *testing.T) {
 	// Simple class C test
 	_, network, _ := net.ParseCIDR("192.168.0.1/24")
@@ -217,3 +253,38 @@ func assertIPEquals(t *testing.T, ip1, ip2 net.IP) {
 		t.Fatalf("Expected IP %s, got %s", ip1, ip2)
 	}
 }
+
+func AssertOverlap(CIDRx string, CIDRy string, t *testing.T) {
+	_, netX, _ := net.ParseCIDR(CIDRx)
+	_, netY, _ := net.ParseCIDR(CIDRy)
+	if !networkOverlaps(netX, netY) {
+		t.Errorf("%v and %v should overlap", netX, netY)
+	}
+}
+
+func AssertNoOverlap(CIDRx string, CIDRy string, t *testing.T) {
+	_, netX, _ := net.ParseCIDR(CIDRx)
+	_, netY, _ := net.ParseCIDR(CIDRy)
+	if networkOverlaps(netX, netY) {
+		t.Errorf("%v and %v should not overlap", netX, netY)
+	}
+}
+
+func TestNetworkOverlaps(t *testing.T) {
+	//netY starts at same IP and ends within netX
+	AssertOverlap("172.16.0.1/24", "172.16.0.1/25", t)
+	//netY starts within netX and ends at same IP
+	AssertOverlap("172.16.0.1/24", "172.16.0.128/25", t)
+	//netY starts and ends within netX
+	AssertOverlap("172.16.0.1/24", "172.16.0.64/25", t)
+	//netY starts at same IP and ends outside of netX
+	AssertOverlap("172.16.0.1/24", "172.16.0.1/23", t)
+	//netY starts before and ends at same IP of netX
+	AssertOverlap("172.16.1.1/24", "172.16.0.1/23", t)
+	//netY starts before and ends outside of netX
+	AssertOverlap("172.16.1.1/24", "172.16.0.1/23", t)
+	//netY starts and ends before netX
+	AssertNoOverlap("172.16.1.1/25", "172.16.0.1/24", t)
+	//netX starts and ends before netY
+	AssertNoOverlap("172.16.1.1/25", "172.16.2.1/24", t)
+}

rcli/http.go

@@ -1,38 +0,0 @@
-package rcli
-
-import (
-	"fmt"
-	"net/http"
-	"net/url"
-	"path"
-)
-
-// Use this key to encode an RPC call into an URL,
-// eg. domain.tld/path/to/method?q=get_user&q=gordon
-const ARG_URL_KEY = "q"
-
-func URLToCall(u *url.URL) (method string, args []string) {
-	return path.Base(u.Path), u.Query()[ARG_URL_KEY]
-}
-
-func ListenAndServeHTTP(addr string, service Service) error {
-	return http.ListenAndServe(addr, http.HandlerFunc(
-		func(w http.ResponseWriter, r *http.Request) {
-			cmd, args := URLToCall(r.URL)
-			if err := call(service, r.Body, &AutoFlush{w}, append([]string{cmd}, args...)...); err != nil {
-				fmt.Fprintln(w, "Error:", err.Error())
-			}
-		}))
-}
-
-type AutoFlush struct {
-	http.ResponseWriter
-}
-
-func (w *AutoFlush) Write(data []byte) (int, error) {
-	ret, err := w.ResponseWriter.Write(data)
-	if flusher, ok := w.ResponseWriter.(http.Flusher); ok {
-		flusher.Flush()
-	}
-	return ret, err
-}

rcli/tcp.go

@@ -2,6 +2,7 @@ package rcli
 
 import (
 	"bufio"
+	"bytes"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -15,22 +16,109 @@ import (
 var DEBUG_FLAG bool = false
 var CLIENT_SOCKET io.Writer = nil
 
+type DockerTCPConn struct {
+	conn       *net.TCPConn
+	options    *DockerConnOptions
+	optionsBuf *[]byte
+	handshaked bool
+	client     bool
+}
+
+func NewDockerTCPConn(conn *net.TCPConn, client bool) *DockerTCPConn {
+	return &DockerTCPConn{
+		conn:    conn,
+		options: &DockerConnOptions{},
+		client:  client,
+	}
+}
+
+func (c *DockerTCPConn) SetOptionRawTerminal() {
+	c.options.RawTerminal = true
+}
+
+func (c *DockerTCPConn) GetOptions() *DockerConnOptions {
+	if c.client && !c.handshaked {
+		// Attempt to parse options encoded as a JSON dict and store
+		// the reminder of what we read from the socket in a buffer.
+		//
+		// bufio (and its ReadBytes method) would have been nice here,
+		// but if json.Unmarshal() fails (which will happen if we speak
+		// to a version of docker that doesn't send any option), then
+		// we can't put the data back in it for the next Read().
+		c.handshaked = true
+		buf := make([]byte, 4096)
+		if n, _ := c.conn.Read(buf); n > 0 {
+			buf = buf[:n]
+			if nl := bytes.IndexByte(buf, '\n'); nl != -1 {
+				if err := json.Unmarshal(buf[:nl], c.options); err == nil {
+					buf = buf[nl+1:]
+				}
+			}
+			c.optionsBuf = &buf
+		}
+	}
+
+	return c.options
+}
+
+func (c *DockerTCPConn) Read(b []byte) (int, error) {
+	if c.optionsBuf != nil {
+		// Consume what we buffered in GetOptions() first:
+		optionsBuf := *c.optionsBuf
+		optionsBuflen := len(optionsBuf)
+		copied := copy(b, optionsBuf)
+		if copied < optionsBuflen {
+			optionsBuf = optionsBuf[copied:]
+			c.optionsBuf = &optionsBuf
+			return copied, nil
+		}
+		c.optionsBuf = nil
+		return copied, nil
+	}
+	return c.conn.Read(b)
+}
+
+func (c *DockerTCPConn) Write(b []byte) (int, error) {
+	optionsLen := 0
+	if !c.client && !c.handshaked {
+		c.handshaked = true
+		options, _ := json.Marshal(c.options)
+		options = append(options, '\n')
+		if optionsLen, err := c.conn.Write(options); err != nil {
+			return optionsLen, err
+		}
+	}
+	n, err := c.conn.Write(b)
+	return n + optionsLen, err
+}
+
+func (c *DockerTCPConn) Flush() error {
+	_, err := c.Write([]byte{})
+	return err
+}
+
+func (c *DockerTCPConn) Close() error { return c.conn.Close() }
+
+func (c *DockerTCPConn) CloseWrite() error { return c.conn.CloseWrite() }
+
+func (c *DockerTCPConn) CloseRead() error { return c.conn.CloseRead() }
+
 // Connect to a remote endpoint using protocol `proto` and address `addr`,
 // issue a single call, and return the result.
 // `proto` may be "tcp", "unix", etc. See the `net` package for available protocols.
-func Call(proto, addr string, args ...string) (*net.TCPConn, error) {
+func Call(proto, addr string, args ...string) (DockerConn, error) {
 	cmd, err := json.Marshal(args)
 	if err != nil {
 		return nil, err
 	}
-	conn, err := net.Dial(proto, addr)
+	conn, err := dialDocker(proto, addr)
 	if err != nil {
 		return nil, err
 	}
 	if _, err := fmt.Fprintln(conn, string(cmd)); err != nil {
 		return nil, err
 	}
-	return conn.(*net.TCPConn), nil
+	return conn, nil
 }
 
 // Listen on `addr`, using protocol `proto`, for incoming rcli calls,
@@ -46,6 +134,10 @@ func ListenAndServe(proto, addr string, service Service) error {
 		if conn, err := listener.Accept(); err != nil {
 			return err
 		} else {
+			conn, err := newDockerServerConn(conn)
+			if err != nil {
+				return err
+			}
 			go func() {
 				if DEBUG_FLAG {
 					CLIENT_SOCKET = conn
@@ -63,7 +155,7 @@ func ListenAndServe(proto, addr string, service Service) error {
 
 // Parse an rcli call on a new connection, and pass it to `service` if it
 // is valid.
-func Serve(conn io.ReadWriter, service Service) error {
+func Serve(conn DockerConn, service Service) error {
 	r := bufio.NewReader(conn)
 	var args []string
 	if line, err := r.ReadString('\n'); err != nil {

rcli/types.go

@@ -8,15 +8,99 @@ package rcli
 // are the usual suspects.
 
 import (
-	"errors"
 	"flag"
 	"fmt"
+	"github.com/dotcloud/docker/term"
 	"io"
 	"log"
+	"net"
+	"os"
 	"reflect"
 	"strings"
 )
 
+type DockerConnOptions struct {
+	RawTerminal bool
+}
+
+type DockerConn interface {
+	io.ReadWriteCloser
+	CloseWrite() error
+	CloseRead() error
+	GetOptions() *DockerConnOptions
+	SetOptionRawTerminal()
+	Flush() error
+}
+
+type DockerLocalConn struct {
+	writer     io.WriteCloser
+	savedState *term.State
+}
+
+func NewDockerLocalConn(w io.WriteCloser) *DockerLocalConn {
+	return &DockerLocalConn{
+		writer: w,
+	}
+}
+
+func (c *DockerLocalConn) Read(b []byte) (int, error) {
+	return 0, fmt.Errorf("DockerLocalConn does not implement Read()")
+}
+
+func (c *DockerLocalConn) Write(b []byte) (int, error) { return c.writer.Write(b) }
+
+func (c *DockerLocalConn) Close() error {
+	if c.savedState != nil {
+		RestoreTerminal(c.savedState)
+		c.savedState = nil
+	}
+	return c.writer.Close()
+}
+
+func (c *DockerLocalConn) Flush() error { return nil }
+
+func (c *DockerLocalConn) CloseWrite() error { return nil }
+
+func (c *DockerLocalConn) CloseRead() error { return nil }
+
+func (c *DockerLocalConn) GetOptions() *DockerConnOptions { return nil }
+
+func (c *DockerLocalConn) SetOptionRawTerminal() {
+	if state, err := SetRawTerminal(); err != nil {
+		if os.Getenv("DEBUG") != "" {
+			log.Printf("Can't set the terminal in raw mode: %s", err)
+		}
+	} else {
+		c.savedState = state
+	}
+}
+
+var UnknownDockerProto = fmt.Errorf("Only TCP is actually supported by Docker at the moment")
+
+func dialDocker(proto string, addr string) (DockerConn, error) {
+	conn, err := net.Dial(proto, addr)
+	if err != nil {
+		return nil, err
+	}
+	switch i := conn.(type) {
+	case *net.TCPConn:
+		return NewDockerTCPConn(i, true), nil
+	}
+	return nil, UnknownDockerProto
+}
+
+func newDockerFromConn(conn net.Conn, client bool) (DockerConn, error) {
+	switch i := conn.(type) {
+	case *net.TCPConn:
+		return NewDockerTCPConn(i, client), nil
+	}
+	return nil, UnknownDockerProto
+}
+
+func newDockerServerConn(conn net.Conn) (DockerConn, error) {
+	return newDockerFromConn(conn, false)
+}
+
 type Service interface {
 	Name() string
 	Help() string
@@ -26,11 +110,11 @@ type Cmd func(io.ReadCloser, io.Writer, ...string) error
 type CmdMethod func(Service, io.ReadCloser, io.Writer, ...string) error
 
 // FIXME: For reverse compatibility
-func call(service Service, stdin io.ReadCloser, stdout io.Writer, args ...string) error {
+func call(service Service, stdin io.ReadCloser, stdout DockerConn, args ...string) error {
 	return LocalCall(service, stdin, stdout, args...)
 }
 
-func LocalCall(service Service, stdin io.ReadCloser, stdout io.Writer, args ...string) error {
+func LocalCall(service Service, stdin io.ReadCloser, stdout DockerConn, args ...string) error {
 	if len(args) == 0 {
 		args = []string{"help"}
 	}
@@ -49,7 +133,7 @@ func LocalCall(service Service, stdin io.ReadCloser, stdout io.Writer, args ...s
 	if method != nil {
 		return method(stdin, stdout, flags.Args()[1:]...)
 	}
-	return errors.New("No such command: " + cmd)
+	return fmt.Errorf("No such command: %s", cmd)
 }
 
 func getMethod(service Service, name string) Cmd {
@@ -59,7 +143,7 @@ func getMethod(service Service, name string) Cmd {
 				stdout.Write([]byte(service.Help()))
 			} else {
 				if method := getMethod(service, args[0]); method == nil {
-					return errors.New("No such command: " + args[0])
+					return fmt.Errorf("No such command: %s", args[0])
 				} else {
 					method(stdin, stdout, "--help")
 				}

rcli/utils.go

@@ -0,0 +1,27 @@
+package rcli
+
+import (
+	"github.com/dotcloud/docker/term"
+	"os"
+	"os/signal"
+)
+
+//FIXME: move these function to utils.go (in rcli to avoid import loop)
+func SetRawTerminal() (*term.State, error) {
+	oldState, err := term.MakeRaw(int(os.Stdin.Fd()))
+	if err != nil {
+		return nil, err
+	}
+	c := make(chan os.Signal, 1)
+	signal.Notify(c, os.Interrupt)
+	go func() {
+		_ = <-c
+		term.Restore(int(os.Stdin.Fd()), oldState)
+		os.Exit(0)
+	}()
+	return oldState, err
+}
+
+func RestoreTerminal(state *term.State) {
+	term.Restore(int(os.Stdin.Fd()), state)
+}

runtime.go

@@ -7,9 +7,10 @@ import (
 	"io"
 	"io/ioutil"
 	"os"
+	"os/exec"
 	"path"
 	"sort"
-	"sync"
+	"strings"
 	"time"
 )
 
@@ -132,11 +133,27 @@ func (runtime *Runtime) Register(container *Container) error {
 	if err := validateId(container.Id); err != nil {
 		return err
 	}
+
+	// FIXME: if the container is supposed to be running but is not, auto restart it?
+	//        if so, then we need to restart monitor and init a new lock
+	// If the container is supposed to be running, make sure of it
+	if container.State.Running {
+		if output, err := exec.Command("lxc-info", "-n", container.Id).CombinedOutput(); err != nil {
+			return err
+		} else {
+			if !strings.Contains(string(output), "RUNNING") {
+				Debugf("Container %s was supposed to be running be is not.", container.Id)
+				container.State.setStopped(-127)
+				if err := container.ToDisk(); err != nil {
+					return err
+				}
+			}
+		}
+	}
+	container.State.initLock()
+
 	container.runtime = runtime
-	// Setup state lock (formerly in newState()
-	lock := new(sync.Mutex)
-	container.State.stateChangeLock = lock
-	container.State.stateChangeCond = sync.NewCond(lock)
+
 	// Attach to stdout and stderr
 	container.stderr = newWriteBroadcaster()
 	container.stdout = newWriteBroadcaster()
@@ -250,7 +267,10 @@ func NewRuntimeFromDirectory(root string) (*Runtime, error) {
 	if err != nil {
 		return nil, fmt.Errorf("Couldn't create Tag store: %s", err)
 	}
-	netManager, err := newNetworkManager(networkBridgeIface)
+	if NetworkBridgeIface == "" {
+		NetworkBridgeIface = DefaultNetworkBridge
+	}
+	netManager, err := newNetworkManager(NetworkBridgeIface)
 	if err != nil {
 		return nil, err
 	}
@@ -259,7 +279,6 @@ func NewRuntimeFromDirectory(root string) (*Runtime, error) {
 		// If the auth file does not exist, keep going
 		return nil, err
 	}
-
 	runtime := &Runtime{
 		root:           root,
 		repository:     runtimeRepo,

runtime_test.go

@@ -1,6 +1,7 @@
 package docker
 
 import (
+	"github.com/dotcloud/docker/rcli"
 	"io"
 	"io/ioutil"
 	"os"
@@ -8,6 +9,7 @@ import (
 	"os/user"
 	"sync"
 	"testing"
+	"time"
 )
 
 // FIXME: this is no longer needed
@@ -21,10 +23,10 @@ func nuke(runtime *Runtime) error {
 	var wg sync.WaitGroup
 	for _, container := range runtime.List() {
 		wg.Add(1)
-		go func() {
-			container.Kill()
-			wg.Add(-1)
-		}()
+		go func(c *Container) {
+			c.Kill()
+			wg.Done()
+		}(container)
 	}
 	wg.Wait()
 	return os.RemoveAll(runtime.root)
@@ -76,7 +78,7 @@ func init() {
 		runtime: runtime,
 	}
 	// Retrieve the Image
-	if err := srv.CmdPull(os.Stdin, os.Stdout, unitTestImageName); err != nil {
+	if err := srv.CmdPull(os.Stdin, rcli.NewDockerLocalConn(os.Stdout), unitTestImageName); err != nil {
 		panic(err)
 	}
 }
@@ -90,7 +92,6 @@ func newTestRuntime() (*Runtime, error) {
 		return nil, err
 	}
 	if err := CopyDirectory(unitTestStoreBase, root); err != nil {
-		panic(err)
 		return nil, err
 	}
 
@@ -289,13 +290,48 @@ func TestRestore(t *testing.T) {
 		t.Fatal(err)
 	}
 	defer runtime1.Destroy(container1)
-	if len(runtime1.List()) != 1 {
-		t.Errorf("Expected 1 container, %v found", len(runtime1.List()))
+
+	// Create a second container meant to be killed
+	container2, err := runtime1.Create(&Config{
+		Image:     GetTestImage(runtime1).Id,
+		Cmd:       []string{"/bin/cat"},
+		OpenStdin: true,
+	},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer runtime1.Destroy(container2)
+
+	// Start the container non blocking
+	if err := container2.Start(); err != nil {
+		t.Fatal(err)
+	}
+
+	if !container2.State.Running {
+		t.Fatalf("Container %v should appear as running but isn't", container2.Id)
+	}
+
+	// Simulate a crash/manual quit of dockerd: process dies, states stays 'Running'
+	cStdin, _ := container2.StdinPipe()
+	cStdin.Close()
+	if err := container2.WaitTimeout(2 * time.Second); err != nil {
+		t.Fatal(err)
+	}
+	container2.State.Running = true
+	container2.ToDisk()
+
+	if len(runtime1.List()) != 2 {
+		t.Errorf("Expected 2 container, %v found", len(runtime1.List()))
 	}
 	if err := container1.Run(); err != nil {
 		t.Fatal(err)
 	}
 
+	if !container2.State.Running {
+		t.Fatalf("Container %v should appear as running but isn't", container2.Id)
+	}
+
 	// Here are are simulating a docker restart - that is, reloading all containers
 	// from scratch
 	runtime2, err := NewRuntimeFromDirectory(root)
@@ -303,14 +339,25 @@ func TestRestore(t *testing.T) {
 		t.Fatal(err)
 	}
 	defer nuke(runtime2)
-	if len(runtime2.List()) != 1 {
-		t.Errorf("Expected 1 container, %v found", len(runtime2.List()))
+	if len(runtime2.List()) != 2 {
+		t.Errorf("Expected 2 container, %v found", len(runtime2.List()))
 	}
-	container2 := runtime2.Get(container1.Id)
-	if container2 == nil {
+	runningCount := 0
+	for _, c := range runtime2.List() {
+		if c.State.Running {
+			t.Errorf("Running container found: %v (%v)", c.Id, c.Path)
+			runningCount++
+		}
+	}
+	if runningCount != 0 {
+		t.Fatalf("Expected 0 container alive, %d found", runningCount)
+	}
+	container3 := runtime2.Get(container1.Id)
+	if container3 == nil {
 		t.Fatal("Unable to Get container")
 	}
-	if err := container2.Run(); err != nil {
+	if err := container3.Run(); err != nil {
 		t.Fatal(err)
 	}
+	container2.State.Running = false
 }

state.go

@@ -11,9 +11,7 @@ type State struct {
 	Pid       int
 	ExitCode  int
 	StartedAt time.Time
-
-	stateChangeLock *sync.Mutex
-	stateChangeCond *sync.Cond
+	l         *sync.Mutex
 }
 
 // String returns a human-readable description of the state
@@ -29,24 +27,22 @@ func (s *State) setRunning(pid int) {
 	s.ExitCode = 0
 	s.Pid = pid
 	s.StartedAt = time.Now()
-	s.broadcast()
 }
 
 func (s *State) setStopped(exitCode int) {
 	s.Running = false
 	s.Pid = 0
 	s.ExitCode = exitCode
-	s.broadcast()
 }
 
-func (s *State) broadcast() {
-	s.stateChangeLock.Lock()
-	s.stateChangeCond.Broadcast()
-	s.stateChangeLock.Unlock()
+func (s *State) initLock() {
+	s.l = &sync.Mutex{}
 }
 
-func (s *State) wait() {
-	s.stateChangeLock.Lock()
-	s.stateChangeCond.Wait()
-	s.stateChangeLock.Unlock()
+func (s *State) lock() {
+	s.l.Lock()
+}
+
+func (s *State) unlock() {
+	s.l.Unlock()
 }

term/termios_linux.go

@@ -15,7 +15,8 @@ void MakeRaw(int fd) {
   ioctl(fd, TCGETS, &t);
 
   t.c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP | INLCR | IGNCR | ICRNL | IXON);
-  t.c_lflag &= ~(ECHO | ECHONL | ICANON | IEXTEN);
+  t.c_oflag &= ~OPOST;
+  t.c_lflag &= ~(ECHO | ECHONL | ICANON | IEXTEN | ISIG);
   t.c_cflag &= ~(CSIZE | PARENB);
   t.c_cflag |= CS8;
 

utils.go

@@ -202,7 +202,7 @@ func (r *bufReader) Read(p []byte) (n int, err error) {
 		}
 		r.wait.Wait()
 	}
-	return
+	panic("unreachable")
 }
 
 func (r *bufReader) Close() error {
@@ -341,3 +341,46 @@ func TruncateId(id string) string {
 	}
 	return id[:shortLen]
 }
+
+// Code c/c from io.Copy() modified to handle escape sequence
+func CopyEscapable(dst io.Writer, src io.ReadCloser) (written int64, err error) {
+	buf := make([]byte, 32*1024)
+	for {
+		nr, er := src.Read(buf)
+		if nr > 0 {
+			// ---- Docker addition
+			// char 16 is C-p
+			if nr == 1 && buf[0] == 16 {
+				nr, er = src.Read(buf)
+				// char 17 is C-q
+				if nr == 1 && buf[0] == 17 {
+					if err := src.Close(); err != nil {
+						return 0, err
+					}
+					return 0, io.EOF
+				}
+			}
+			// ---- End of docker
+			nw, ew := dst.Write(buf[0:nr])
+			if nw > 0 {
+				written += int64(nw)
+			}
+			if ew != nil {
+				err = ew
+				break
+			}
+			if nr != nw {
+				err = io.ErrShortWrite
+				break
+			}
+		}
+		if er == io.EOF {
+			break
+		}
+		if er != nil {
+			err = er
+			break
+		}
+	}
+	return written, err
+}