Merge pull request #8092 from vishh/exec_api_docs

Exec remote API documentation

api/server/server.go

@@ -1088,6 +1088,7 @@ func postContainerExecCreate(eng *engine.Engine, version version.Version, w http
 	return writeJSON(w, http.StatusCreated, out)
 }
 
+// TODO(vishh): Refactor the code to avoid having to specify stream config as part of both create and start.
 func postContainerExecStart(eng *engine.Engine, version version.Version, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
 	if err := parseForm(r); err != nil {
 		return nil
@@ -1144,6 +1145,7 @@ func postContainerExecStart(eng *engine.Engine, version version.Version, w http.
 		return err
 	}
 	w.WriteHeader(http.StatusNoContent)
+
 	return nil
 }
 

daemon/exec.go

@@ -78,7 +78,7 @@ func (d *Daemon) getExecConfig(name string) (*execConfig, error) {
 		return execConfig, nil
 	}
 
-	return nil, fmt.Errorf("No exec '%s' in found in daemon", name)
+	return nil, fmt.Errorf("No such exec instance '%s' found in daemon", name)
 }
 
 func (d *Daemon) unregisterExecCommand(execConfig *execConfig) {

docs/man/docker-exec.1.md

@@ -2,7 +2,7 @@
 % Docker Community
 % SEPT 2014
 # NAME
-docker-exec - Run a command in an active container
+docker-exec - Run a command in a running container
 
 # SYNOPSIS
 **docker exec**
@@ -13,7 +13,7 @@ docker-exec - Run a command in an active container
 
 # DESCRIPTION
 
-Run a process in an existing container. The existing CONTAINER needs to be active.
+Run a process in a running container. 
 
 # Options
 

docs/man/docker.1.md

@@ -106,7 +106,7 @@ unix://[/path/to/socket] to use.
   Get real time events from the server
 
 **docker-exec(1)**
-  Run a command in an active container
+  Run a command in a running container
 
 **docker-export(1)**
   Stream the contents of a container as a tar archive

docs/sources/reference/api/docker_remote_api.md

@@ -43,6 +43,16 @@ You can still call an old version of the API using
 **New!**
 Now has header: `Content-Type: application/x-json-stream`.
 
+`POST /containers/(id)/exec`
+
+**New!**
+Setup an exec command in a running container `id`.
+
+`POST /exec/(id)/start`
+
+**New!**
+Start an exec command.
+
 ## v1.14
 
 ### Full Documentation

docs/sources/reference/api/docker_remote_api_v1.15.md

@@ -1428,6 +1428,110 @@ the root that contains a list of repository and tag names mapped to layer IDs.
 }
 ```
 
+### Exec Create
+
+`POST /containers/(id)/exec`
+
+Sets up an exec instance in a running container `id`
+
+**Example request**:
+
+        POST /containers/e90e34656806/exec HTTP/1.1
+        Content-Type: application/json
+
+        {             
+	     "Detach":false,
+	     "AttachStdin":false,
+	     "AttachStdout":true,
+	     "AttachStderr":true,
+	     "Tty":false,
+	     "Cmd":[
+                     "date"
+             ],
+	     "Container":"e90e34656806",
+        }
+
+**Example response**:
+
+        HTTP/1.1 201 OK
+        Content-Type: application/json
+
+        {
+             "Id":"f90e34656806"
+        }
+
+Json Parameters:
+
+-   **execConfig** ? exec configuration.
+
+Status Codes:
+
+-   **201** – no error
+-   **404** – no such container
+
+### Exec Start
+
+`POST /exec/(id)/start`
+
+Starts a previously set up exec instance `id`. If `detach` is true, this API returns after
+starting the `exec` command. Otherwise, this API sets up an interactive session with the `exec` command.
+
+**Example request**:
+
+        POST /containers/e90e34656806/exec HTTP/1.1
+        Content-Type: application/json
+
+        {
+	     "Detach":false,
+	     "Tty":false,
+        }
+
+**Example response**:
+
+        HTTP/1.1 201 OK
+        Content-Type: application/json
+
+        {{ STREAM }}
+
+Json Parameters:
+
+-   **execConfig** ? exec configuration.
+
+Status Codes:
+
+-   **201** – no error
+-   **404** – no such exec instance
+
+    **Stream details**:
+    Similar to the stream behavior of `POST /container/(id)/attach` API
+
+### Exec Resize
+
+`POST /exec/(id)/resize`
+
+Resizes the tty session used by the exec command `id`.
+This API is valid only if `tty` was specified as part of creating and starting the exec command.
+
+**Example request**:
+
+        POST /containers/e90e34656806/exec HTTP/1.1
+        Content-Type: plain/text
+
+**Example response**:
+
+        HTTP/1.1 201 OK
+        Content-Type: plain/text
+
+Query Parameters:
+
+-   **h** – height of tty session
+-   **w** – width
+
+Status Codes:
+
+-   **201** – no error
+-   **404** – no such exec instance
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

docs/sources/reference/commandline/cli.md

@@ -555,25 +555,24 @@ You'll need two shells for this example.
       -i, --interactive=false    Keep STDIN open even if not attached
       -t, --tty=false            Allocate a pseudo-TTY
 
-The `docker exec` command runs a user specified command as a new process in an existing
+The `docker exec` command runs a new command in a running container.
-user specified container. The container needs to be active.
 
-The `docker exec` command will typically be used after `docker run`.
+The `docker exec` command will typically be used after `docker run` or `docker start`.
 
 ### Examples:
 
     $ sudo docker run --name ubuntu_bash --rm -i -t ubuntu bash
 
-This will create a container named 'ubuntu_bash' and start a bash session.
+This will create a container named `ubuntu_bash` and start a Bash session.
 
     $ sudo docker exec -d ubuntu_bash touch /tmp/execWorks
 
-This will create a new file '/tmp/execWorks' inside the existing and active container
+This will create a new file `/tmp/execWorks` inside the running container
-'ubuntu_bash', in the background.
+`ubuntu_bash`, in the background.
 
     $ sudo docker exec ubuntu_bash -it bash
 
-This will create a new bash session in the container 'ubuntu_bash'.
+This will create a new Bash session in the container `ubuntu_bash`.
 
 ## export