1. docker
  2. Commit 5f3812ec97f9a951bceb482fdcd355b6cbc1b113
Browse code

filters, for images: start with untagged/tagged boolean

This is a new feature and flag. (replaces the suggestion of a flag for
--untagged images).
The concept is to have a syntax to filter. This begins with this
filtering for the 'images' subcommand, and at that only filtering for
whether images are untagged.
example like: docker rmi $(docker images -q --filter 'untagged=true')

Docker-DCO-1.1-Signed-off-by: Vincent Batts <vbatts@redhat.com> (github: vbatts)

Vincent Batts authored on 2014/02/27 07:04:11
Showing 6 changed files
api/client/commands.go
History View file @ 5f3812e
... ... 
@@ -26,12 +26,14 @@ import (
26 26 
 	"github.com/dotcloud/docker/dockerversion"
27 27 
 	"github.com/dotcloud/docker/engine"
28 28 
 	"github.com/dotcloud/docker/nat"
29 
+	"github.com/dotcloud/docker/opts"
29 30 
 	"github.com/dotcloud/docker/pkg/signal"
30 31 
 	"github.com/dotcloud/docker/pkg/term"
31 32 
 	"github.com/dotcloud/docker/pkg/units"
32 33 
 	"github.com/dotcloud/docker/registry"
33 34 
 	"github.com/dotcloud/docker/runconfig"
34 35 
 	"github.com/dotcloud/docker/utils"
36 
+	"github.com/dotcloud/docker/utils/filters"
35 37 
 )
36 38
37 39 
 func (cli *DockerCli) CmdHelp(args ...string) error {
... ... 
@@ -1145,6 +1147,9 @@ func (cli *DockerCli) CmdImages(args ...string) error {
1145 1145 
 	flViz := cmd.Bool([]string{"#v", "#viz", "#-viz"}, false, "Output graph in graphviz format")
1146 1146 
 	flTree := cmd.Bool([]string{"#t", "#tree", "#-tree"}, false, "Output graph in tree format")
1147 1147
1148 
+	var flFilter opts.ListOpts
1149 
+	cmd.Var(&flFilter, []string{"f", "-filter"}, "Provide filter values (i.e. 'tagged=false')")
1150 
+
1148 1151 
 	if err := cmd.Parse(args); err != nil {
1149 1152 
 		return nil
1150 1153 
 	}
... ... 
@@ -1153,11 +1158,41 @@ func (cli *DockerCli) CmdImages(args ...string) error {
1153 1153 
 		return nil
1154 1154 
 	}
1155 1155
1156 
-	filter := cmd.Arg(0)
1156 
+	// Consolidate all filter flags, and sanity check them early.
1157 
+	// They'll get process in the daemon/server.
1158 
+	imageFilters := map[string]string{}
1159 
+	for _, f := range flFilter.GetAll() {
1160 
+		var err error
1161 
+		imageFilters, err = filters.ParseFlag(f, imageFilters)
1162 
+		if err != nil {
1163 
+			return err
1164 
+		}
1165 
+	}
1166 
+	/*
1167 
+	  var (
1168 
+	    untagged bool
1169 
+	  )
1170 
+	  for k,v := range imageFilters {
1171 
+	  }
1172 
+	*/
1173 
+
1174 
+	// seeing -all untagged images is redundant, and no point in seeing a visualization of that
1175 
+	/*
1176 
+		if *flUntagged && (*all || *flViz || *flTree) {
1177 
+			fmt.Fprintln(cli.err, "Notice: --untagged is not to be used with --all, --tree or --viz")
1178 
+			*flUntagged = false
1179 
+		}
1180 
+	*/
1181 
+
1182 
+	matchName := cmd.Arg(0)
1157 1183
1158 1184 
 	// FIXME: --viz and --tree are deprecated. Remove them in a future version.
1159 1185 
 	if *flViz || *flTree {
1160 
-		body, _, err := readBody(cli.call("GET", "/images/json?all=1", nil, false))
1186 
+		v := url.Values{
1187 
+			"all":     []string{"1"},
1188 
+			"filters": []string{filters.ToParam(imageFilters)},
1189 
+		}
1190 
+		body, _, err := readBody(cli.call("GET", "/images/json?"+v.Encode(), nil, false))
1161 1191 
 		if err != nil {
1162 1192 
 			return err
1163 1193 
 		}
... ... 
@@ -1187,13 +1222,13 @@ func (cli *DockerCli) CmdImages(args ...string) error {
1187 1187 
 				}
1188 1188 
 			}
1189 1189
1190 
-			if filter != "" {
1191 
-				if filter == image.Get("Id") || filter == utils.TruncateID(image.Get("Id")) {
1190 
+			if matchName != "" {
1191 
+				if matchName == image.Get("Id") || matchName == utils.TruncateID(image.Get("Id")) {
1192 1192 
 					startImage = image
1193 1193 
 				}
1194 1194
1195 1195 
 				for _, repotag := range image.GetList("RepoTags") {
1196 
-					if repotag == filter {
1196 
+					if repotag == matchName {
1197 1197 
 						startImage = image
1198 1198 
 					}
1199 1199 
 				}
... ... 
@@ -1211,16 +1246,19 @@ func (cli *DockerCli) CmdImages(args ...string) error {
1211 1211 
 			root := engine.NewTable("Created", 1)
1212 1212 
 			root.Add(startImage)
1213 1213 
 			cli.WalkTree(*noTrunc, root, byParent, "", printNode)
1214 
-		} else if filter == "" {
1214 
+		} else if matchName == "" {
1215 1215 
 			cli.WalkTree(*noTrunc, roots, byParent, "", printNode)
1216 1216 
 		}
1217 1217 
 		if *flViz {
1218 1218 
 			fmt.Fprintf(cli.out, " base [style=invisible]\n}\n")
1219 1219 
 		}
1220 1220 
 	} else {
1221 
-		v := url.Values{}
1221 
+		v := url.Values{
1222 
+			"filters": []string{filters.ToParam(imageFilters)},
1223 
+		}
1222 1224 
 		if cmd.NArg() == 1 {
1223 
-			v.Set("filter", filter)
1225 
+			// FIXME rename this parameter, to not be confused with the filters flag
1226 
+			v.Set("filter", matchName)
1224 1227 
 		}
1225 1228 
 		if *all {
1226 1229 
 			v.Set("all", "1")
api/server/server.go
History View file @ 5f3812e
... ... 
@@ -188,6 +188,8 @@ func getImagesJSON(eng *engine.Engine, version version.Version, w http.ResponseW
188 188 
 		job  = eng.Job("images")
189 189 
 	)
190 190
191 
+	job.Setenv("filters", r.Form.Get("filters"))
192 
+	// FIXME rename this parameter, to not be confused with the filters flag
191 193 
 	job.Setenv("filter", r.Form.Get("filter"))
192 194 
 	job.Setenv("all", r.Form.Get("all"))
193 195
docs/sources/reference/commandline/cli.rst
History View file @ 5f3812e
194 196 
new file mode 100644
... ... 
@@ -0,0 +1,1499 @@
0 
+:title: Command Line Interface
1 
+:description: Docker's CLI command description and usage
2 
+:keywords: Docker, Docker documentation, CLI, command line
3 
+
4 
+.. _cli:
5 
+
6 
+Command Line Help
7 
+-----------------
8 
+
9 
+To list available commands, either run ``docker`` with no parameters or execute
10 
+``docker help``::
11 
+
12 
+  $ sudo docker
13 
+    Usage: docker [OPTIONS] COMMAND [arg...]
14 
+      -H=[unix:///var/run/docker.sock]: tcp://[host]:port to bind/connect to or unix://[/path/to/socket] to use. When host=[127.0.0.1] is omitted for tcp or path=[/var/run/docker.sock] is omitted for unix sockets, default values are used.
15 
+
16 
+    A self-sufficient runtime for linux containers.
17 
+
18 
+    ...
19 
+
20 
+.. _cli_options:
21 
+
22 
+Options
23 
+-------
24 
+
25 
+Single character commandline options can be combined, so rather than typing
26 
+``docker run -t -i --name test busybox sh``, you can write
27 
+``docker run -ti --name test busybox sh``.
28 
+
29 
+Boolean
30 
+~~~~~~~
31 
+
32 
+Boolean options look like ``-d=false``. The value you see is the
33 
+default value which gets set if you do **not** use the boolean
34 
+flag. If you do call ``run -d``, that sets the opposite boolean value,
35 
+so in this case, ``true``, and so ``docker run -d`` **will** run in
36 
+"detached" mode, in the background. Other boolean options are similar
37 
+-- specifying them will set the value to the opposite of the default
38 
+value.
39 
+
40 
+Multi
41 
+~~~~~
42 
+
43 
+Options like ``-a=[]`` indicate they can be specified multiple times::
44 
+
45 
+  docker run -a stdin -a stdout -a stderr -i -t ubuntu /bin/bash
46 
+
47 
+Sometimes this can use a more complex value string, as for ``-v``::
48 
+
49 
+  docker run -v /host:/container example/mysql
50 
+
51 
+Strings and Integers
52 
+~~~~~~~~~~~~~~~~~~~~
53 
+
54 
+Options like ``--name=""`` expect a string, and they can only be
55 
+specified once. Options like ``-c=0`` expect an integer, and they can
56 
+only be specified once.
57 
+
58 
+----
59 
+
60 
+Commands
61 
+--------
62 
+
63 
+.. _cli_daemon:
64 
+
65 
+``daemon``
66 
+----------
67 
+
68 
+::
69 
+
70 
+    Usage of docker:
71 
+      -D, --debug=false: Enable debug mode
72 
+      -H, --host=[]: Multiple tcp://host:port or unix://path/to/socket to bind in daemon mode, single connection otherwise. systemd socket activation can be used with fd://[socketfd].
73 
+      -G, --group="docker": Group to assign the unix socket specified by -H when running in daemon mode; use '' (the empty string) to disable setting of a group
74 
+      --api-enable-cors=false: Enable CORS headers in the remote API
75 
+      -b, --bridge="": Attach containers to a pre-existing network bridge; use 'none' to disable container networking
76 
+      --bip="": Use this CIDR notation address for the network bridge's IP, not compatible with -b
77 
+      -d, --daemon=false: Enable daemon mode
78 
+      --dns=[]: Force docker to use specific DNS servers
79 
+      --dns-search=[]: Force Docker to use specific DNS search domains
80 
+      -g, --graph="/var/lib/docker": Path to use as the root of the docker runtime
81 
+      --icc=true: Enable inter-container communication
82 
+      --ip="0.0.0.0": Default IP address to use when binding container ports
83 
+      --ip-forward=true: Enable net.ipv4.ip_forward
84 
+      --iptables=true: Enable Docker's addition of iptables rules
85 
+      -p, --pidfile="/var/run/docker.pid": Path to use for daemon PID file
86 
+      -r, --restart=true: Restart previously running containers
87 
+      -s, --storage-driver="": Force the docker runtime to use a specific storage driver
88 
+      -e, --exec-driver="native": Force the docker runtime to use a specific exec driver
89 
+      -v, --version=false: Print version information and quit
90 
+      --tls=false: Use TLS; implied by tls-verify flags
91 
+      --tlscacert="~/.docker/ca.pem": Trust only remotes providing a certificate signed by the CA given here
92 
+      --tlscert="~/.docker/cert.pem": Path to TLS certificate file
93 
+      --tlskey="~/.docker/key.pem": Path to TLS key file
94 
+      --tlsverify=false: Use TLS and verify the remote (daemon: verify client, client: verify daemon)
95 
+      --mtu=0: Set the containers network MTU; if no value is provided: default to the default route MTU or 1500 if no default route is available
96 
+
97 
+The Docker daemon is the persistent process that manages containers.  Docker uses the same binary for both the
98 
+daemon and client.  To run the daemon you provide the ``-d`` flag.
99 
+
100 
+To force Docker to use devicemapper as the storage driver, use ``docker -d -s devicemapper``.
101 
+
102 
+To set the DNS server for all Docker containers, use ``docker -d --dns 8.8.8.8``.
103 
+
104 
+To set the DNS search domain for all Docker containers, use ``docker -d --dns-search example.com``.
105 
+
106 
+To run the daemon with debug output, use ``docker -d -D``.
107 
+
108 
+To use lxc as the execution driver, use ``docker -d -e lxc``.
109 
+
110 
+The docker client will also honor the ``DOCKER_HOST`` environment variable to set
111 
+the ``-H`` flag for the client.
112 
+
113 
+::
114 
+
115 
+        docker -H tcp://0.0.0.0:4243 ps
116 
+        # or
117 
+        export DOCKER_HOST="tcp://0.0.0.0:4243"
118 
+        docker ps
119 
+        # both are equal
120 
+
121 
+To run the daemon with `systemd socket activation <http://0pointer.de/blog/projects/socket-activation.html>`_, use ``docker -d -H fd://``.
122 
+Using ``fd://`` will work perfectly for most setups but you can also specify individual sockets too ``docker -d -H fd://3``.
123 
+If the specified socket activated files aren't found then docker will exit.
124 
+You can find examples of using systemd socket activation with docker and systemd in the `docker source tree <https://github.com/dotcloud/docker/blob/master/contrib/init/systemd/socket-activation/>`_.
125 
+
126 
+Docker supports softlinks for the Docker data directory (``/var/lib/docker``) and for ``/tmp``.
127 
+TMPDIR and the data directory can be set like this:
128 
+
129 
+::
130 
+
131 
+    TMPDIR=/mnt/disk2/tmp /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1
132 
+    # or
133 
+    export TMPDIR=/mnt/disk2/tmp
134 
+    /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1
135 
+
136 
+.. _cli_attach:
137 
+
138 
+``attach``
139 
+----------
140 
+
141 
+::
142 
+
143 
+    Usage: docker attach CONTAINER
144 
+
145 
+    Attach to a running container.
146 
+
147 
+      --no-stdin=false: Do not attach stdin
148 
+      --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode)
149 
+
150 
+You can detach from the container again (and leave it running) with
151 
+``CTRL-c`` (for a quiet exit) or ``CTRL-\`` to get a stacktrace of
152 
+the Docker client when it quits.  When you detach from the container's
153 
+process the exit code will be returned to the client.
154 
+
155 
+To stop a container, use ``docker stop``.
156 
+
157 
+To kill the container, use ``docker kill``.
158 
+
159 
+.. _cli_attach_examples:
160 
+
161 
+Examples:
162 
+~~~~~~~~~
163 
+
164 
+.. code-block:: bash
165 
+
166 
+     $ ID=$(sudo docker run -d ubuntu /usr/bin/top -b)
167 
+     $ sudo docker attach $ID
168 
+     top - 02:05:52 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
169 
+     Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
170 
+     Cpu(s):  0.1%us,  0.2%sy,  0.0%ni, 99.7%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
171 
+     Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
172 
+     Swap:   786428k total,        0k used,   786428k free,   221740k cached
173 
+
174 
+     PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
175 
+      1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
176 
+
177 
+      top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
178 
+      Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
179 
+      Cpu(s):  0.0%us,  0.2%sy,  0.0%ni, 99.8%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
180 
+      Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
181 
+      Swap:   786428k total,        0k used,   786428k free,   221776k cached
182 
+
183 
+        PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
184 
+	    1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
185 
+
186 
+
187 
+      top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
188 
+      Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
189 
+      Cpu(s):  0.2%us,  0.3%sy,  0.0%ni, 99.5%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
190 
+      Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
191 
+      Swap:   786428k total,        0k used,   786428k free,   221776k cached
192 
+
193 
+      PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
194 
+           1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
195 
+     ^C$
196 
+     $ sudo docker stop $ID
197 
+
198 
+.. _cli_build:
199 
+
200 
+``build``
201 
+---------
202 
+
203 
+::
204 
+
205 
+    Usage: docker build [OPTIONS] PATH | URL | -
206 
+    Build a new container image from the source code at PATH
207 
+      -t, --tag="": Repository name (and optionally a tag) to be applied
208 
+             to the resulting image in case of success.
209 
+      -q, --quiet=false: Suppress the verbose output generated by the containers.
210 
+      --no-cache: Do not use the cache when building the image.
211 
+      --rm=true: Remove intermediate containers after a successful build
212 
+
213 
+The files at ``PATH`` or ``URL`` are called the "context" of the build.
214 
+The build process may refer to any of the files in the context, for example when
215 
+using an :ref:`ADD <dockerfile_add>` instruction.
216 
+When a single ``Dockerfile`` is given as ``URL``, then no context is set.
217 
+
218 
+When a Git repository is set as ``URL``, then the repository is used as the context.
219 
+The Git repository is cloned with its submodules (`git clone --recursive`).
220 
+A fresh git clone occurs in a temporary directory on your local host, and then this
221 
+is sent to the Docker daemon as the context.
222 
+This way, your local user credentials and vpn's etc can be used to access private repositories
223 
+
224 
+.. _cli_build_examples:
225 
+
226 
+.. seealso:: :ref:`dockerbuilder`.
227 
+
228 
+Examples:
229 
+~~~~~~~~~
230 
+
231 
+.. code-block:: bash
232 
+
233 
+    $ sudo docker build .
234 
+    Uploading context 10240 bytes
235 
+    Step 1 : FROM busybox
236 
+    Pulling repository busybox
237 
+     ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
238 
+    Step 2 : RUN ls -lh /
239 
+     ---> Running in 9c9e81692ae9
240 
+    total 24
241 
+    drwxr-xr-x    2 root     root        4.0K Mar 12  2013 bin
242 
+    drwxr-xr-x    5 root     root        4.0K Oct 19 00:19 dev
243 
+    drwxr-xr-x    2 root     root        4.0K Oct 19 00:19 etc
244 
+    drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 lib
245 
+    lrwxrwxrwx    1 root     root           3 Mar 12  2013 lib64 -> lib
246 
+    dr-xr-xr-x  116 root     root           0 Nov 15 23:34 proc
247 
+    lrwxrwxrwx    1 root     root           3 Mar 12  2013 sbin -> bin
248 
+    dr-xr-xr-x   13 root     root           0 Nov 15 23:34 sys
249 
+    drwxr-xr-x    2 root     root        4.0K Mar 12  2013 tmp
250 
+    drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 usr
251 
+     ---> b35f4035db3f
252 
+    Step 3 : CMD echo Hello World
253 
+     ---> Running in 02071fceb21b
254 
+     ---> f52f38b7823e
255 
+    Successfully built f52f38b7823e
256 
+    Removing intermediate container 9c9e81692ae9
257 
+    Removing intermediate container 02071fceb21b
258 
+
259 
+
260 
+This example specifies that the ``PATH`` is ``.``, and so all the files in
261 
+the local directory get tar'd and sent to the Docker daemon.  The ``PATH``
262 
+specifies where to find the files for the "context" of the build on
263 
+the Docker daemon. Remember that the daemon could be running on a
264 
+remote machine and that no parsing of the ``Dockerfile`` happens at the
265 
+client side (where you're running ``docker build``). That means that
266 
+*all* the files at ``PATH`` get sent, not just the ones listed to
267 
+:ref:`ADD <dockerfile_add>` in the ``Dockerfile``.
268 
+
269 
+The transfer of context from the local machine to the Docker daemon is
270 
+what the ``docker`` client means when you see the "Uploading context"
271 
+message.
272 
+
273 
+If you wish to keep the intermediate containers after the build is complete,
274 
+you must use ``--rm=false``. This does not affect the build cache.
275 
+
276 
+
277 
+.. code-block:: bash
278 
+
279 
+   $ sudo docker build -t vieux/apache:2.0 .
280 
+
281 
+This will build like the previous example, but it will then tag the
282 
+resulting image. The repository name will be ``vieux/apache`` and the
283 
+tag will be ``2.0``
284 
+
285 
+
286 
+.. code-block:: bash
287 
+
288 
+    $ sudo docker build - < Dockerfile
289 
+
290 
+This will read a ``Dockerfile`` from *stdin* without context. Due to
291 
+the lack of a context, no contents of any local directory will be sent
292 
+to the ``docker`` daemon.  Since there is no context, a ``Dockerfile``
293 
+``ADD`` only works if it refers to a remote URL.
294 
+
295 
+.. code-block:: bash
296 
+
297 
+    $ sudo docker build github.com/creack/docker-firefox
298 
+
299 
+This will clone the GitHub repository and use the cloned repository as
300 
+context. The ``Dockerfile`` at the root of the repository is used as
301 
+``Dockerfile``.  Note that you can specify an arbitrary Git repository
302 
+by using the ``git://`` schema.
303 
+
304 
+
305 
+.. _cli_commit:
306 
+
307 
+``commit``
308 
+----------
309 
+
310 
+::
311 
+
312 
+    Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
313 
+
314 
+    Create a new image from a container's changes
315 
+
316 
+      -m, --message="": Commit message
317 
+      -a, --author="": Author (eg. "John Hannibal Smith <hannibal@a-team.com>"
318 
+      --run="": Configuration changes to be applied when the image is launched with `docker run`.
319 
+               (ex: --run='{"Cmd": ["cat", "/world"], "PortSpecs": ["22"]}')
320 
+
321 
+.. _cli_commit_examples:
322 
+
323 
+Commit an existing container
324 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
325 
+
326 
+.. code-block:: bash
327 
+
328 
+	$ sudo docker ps
329 
+	ID                  IMAGE               COMMAND             CREATED             STATUS              PORTS
330 
+	c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
331 
+	197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
332 
+	$ docker commit c3f279d17e0a  SvenDowideit/testimage:version3
333 
+	f5283438590d
334 
+	$ docker images | head
335 
+	REPOSITORY                        TAG                 ID                  CREATED             VIRTUAL SIZE
336 
+	SvenDowideit/testimage            version3            f5283438590d        16 seconds ago      335.7 MB
337 
+
338 
+Change the command that a container runs
339 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
340 
+
341 
+Sometimes you have an application container running just a service and you need
342 
+to make a quick change and then change it back.
343 
+
344 
+In this example, we run a container with ``ls`` and then change the image to
345 
+run ``ls /etc``.
346 
+
347 
+.. code-block:: bash
348 
+
349 
+        $ docker run -t --name test ubuntu ls
350 
+        bin  boot  dev  etc  home  lib  lib64  media  mnt  opt  proc  root  run  sbin  selinux  srv  sys  tmp  usr  var
351 
+        $ docker commit --run='{"Cmd": ["ls","/etc"]}' test test2
352 
+        933d16de9e70005304c1717b5c6f2f39d6fd50752834c6f34a155c70790011eb
353 
+        $ docker run -t test2
354 
+        adduser.conf            gshadow          login.defs           rc0.d
355 
+        alternatives            gshadow-         logrotate.d          rc1.d
356 
+        apt                     host.conf        lsb-base             rc2.d
357 
+        ...
358 
+
359 
+Merged configs example
360 
+......................
361 
+
362 
+Say you have a Dockerfile like so:
363 
+
364 
+.. code-block:: bash
365 
+
366 
+        ENV MYVAR foobar
367 
+        RUN apt-get install openssh
368 
+        EXPOSE 22
369 
+        CMD ["/usr/sbin/sshd -D"]
370 
+        ...
371 
+
372 
+If you run that, make some changes, and then commit, Docker will merge the environment variable and exposed port configuration settings with any that you specify in the --run= option. This is a change from Docker 0.8.0 and prior where no attempt was made to preserve any existing configuration on commit.
373 
+
374 
+.. code-block:: bash
375 
+
376 
+        $ docker build -t me/foo .
377 
+        $ docker run -t -i me/foo /bin/bash
378 
+        foo-container$ [make changes in the container]
379 
+        foo-container$ exit
380 
+        $ docker commit --run='{"Cmd": ["ls"]}' [container-id] me/bar
381 
+        ...
382 
+
383 
+The me/bar image will now have port 22 exposed, MYVAR env var set to 'foobar', and its default command will be ["ls"].
384 
+
385 
+Note that this is currently a shallow merge. So, for example, if you had specified a new port spec in the --run= config above, that would have clobbered the 'EXPOSE 22' setting from the parent container.
386 
+
387 
+Full --run example
388 
+..................
389 
+
390 
+The ``--run`` JSON hash changes the ``Config`` section when running ``docker inspect CONTAINERID``
391 
+or ``config`` when running ``docker inspect IMAGEID``. Existing configuration key-values that are
392 
+not overridden in the JSON hash will be merged in.
393 
+
394 
+(Multiline is okay within a single quote ``'``)
395 
+
396 
+.. code-block:: bash
397 
+
398 
+  $ sudo docker commit --run='
399 
+  {
400 
+      "Entrypoint" : null,
401 
+      "Privileged" : false,
402 
+      "User" : "",
403 
+      "VolumesFrom" : "",
404 
+      "Cmd" : ["cat", "-e", "/etc/resolv.conf"],
405 
+      "Dns" : ["8.8.8.8", "8.8.4.4"],
406 
+      "DnsSearch" : ["example.com"],
407 
+      "MemorySwap" : 0,
408 
+      "AttachStdin" : false,
409 
+      "AttachStderr" : false,
410 
+      "CpuShares" : 0,
411 
+      "OpenStdin" : false,
412 
+      "Volumes" : null,
413 
+      "Hostname" : "122612f45831",
414 
+      "PortSpecs" : ["22", "80", "443"],
415 
+      "Image" : "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
416 
+      "Tty" : false,
417 
+      "Env" : [
418 
+         "HOME=/",
419 
+         "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
420 
+      ],
421 
+      "StdinOnce" : false,
422 
+      "Domainname" : "",
423 
+      "WorkingDir" : "/",
424 
+      "NetworkDisabled" : false,
425 
+      "Memory" : 0,
426 
+      "AttachStdout" : false
427 
+  }' $CONTAINER_ID
428 
+
429 
+.. _cli_cp:
430 
+
431 
+``cp``
432 
+------
433 
+
434 
+::
435 
+
436 
+    Usage: docker cp CONTAINER:PATH HOSTPATH
437 
+
438 
+    Copy files/folders from the containers filesystem to the host
439 
+    path.  Paths are relative to the root of the filesystem.
440 
+
441 
+.. code-block:: bash
442 
+
443 
+    $ sudo docker cp 7bb0e258aefe:/etc/debian_version .
444 
+    $ sudo docker cp blue_frog:/etc/hosts .
445 
+
446 
+.. _cli_diff:
447 
+
448 
+``diff``
449 
+--------
450 
+
451 
+::
452 
+
453 
+    Usage: docker diff CONTAINER
454 
+
455 
+    List the changed files and directories in a container's filesystem
456 
+
457 
+There are 3 events that are listed in the 'diff':
458 
+
459 
+1. ```A``` - Add
460 
+2. ```D``` - Delete
461 
+3. ```C``` - Change
462 
+
463 
+For example:
464 
+
465 
+.. code-block:: bash
466 
+
467 
+	$ sudo docker diff 7bb0e258aefe
468 
+
469 
+	C /dev
470 
+	A /dev/kmsg
471 
+	C /etc
472 
+	A /etc/mtab
473 
+	A /go
474 
+	A /go/src
475 
+	A /go/src/github.com
476 
+	A /go/src/github.com/dotcloud
477 
+	A /go/src/github.com/dotcloud/docker
478 
+	A /go/src/github.com/dotcloud/docker/.git
479 
+	....
480 
+
481 
+.. _cli_events:
482 
+
483 
+``events``
484 
+----------
485 
+
486 
+::
487 
+
488 
+    Usage: docker events
489 
+
490 
+    Get real time events from the server
491 
+
492 
+    --since="": Show previously created events and then stream.
493 
+               (either seconds since epoch, or date string as below)
494 
+
495 
+.. _cli_events_example:
496 
+
497 
+Examples
498 
+~~~~~~~~
499 
+
500 
+You'll need two shells for this example.
501 
+
502 
+Shell 1: Listening for events
503 
+.............................
504 
+
505 
+.. code-block:: bash
506 
+
507 
+    $ sudo docker events
508 
+
509 
+Shell 2: Start and Stop a Container
510 
+...................................
511 
+
512 
+.. code-block:: bash
513 
+
514 
+    $ sudo docker start 4386fb97867d
515 
+    $ sudo docker stop 4386fb97867d
516 
+
517 
+Shell 1: (Again .. now showing events)
518 
+......................................
519 
+
520 
+.. code-block:: bash
521 
+
522 
+    [2013-09-03 15:49:26 +0200 CEST] 4386fb97867d: (from 12de384bfb10) start
523 
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
524 
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
525 
+
526 
+Show events in the past from a specified time
527 
+.............................................
528 
+
529 
+.. code-block:: bash
530 
+
531 
+    $ sudo docker events --since 1378216169
532 
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
533 
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
534 
+
535 
+    $ sudo docker events --since '2013-09-03'
536 
+    [2013-09-03 15:49:26 +0200 CEST] 4386fb97867d: (from 12de384bfb10) start
537 
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
538 
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
539 
+
540 
+    $ sudo docker events --since '2013-09-03 15:49:29 +0200 CEST'
541 
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
542 
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
543 
+
544 
+.. _cli_export:
545 
+
546 
+``export``
547 
+----------
548 
+
549 
+::
550 
+
551 
+    Usage: docker export CONTAINER
552 
+
553 
+    Export the contents of a filesystem as a tar archive to STDOUT
554 
+
555 
+For example:
556 
+
557 
+.. code-block:: bash
558 
+
559 
+    $ sudo docker export red_panda > latest.tar
560 
+
561 
+.. _cli_history:
562 
+
563 
+``history``
564 
+-----------
565 
+
566 
+::
567 
+
568 
+    Usage: docker history [OPTIONS] IMAGE
569 
+
570 
+    Show the history of an image
571 
+
572 
+      --no-trunc=false: Don't truncate output
573 
+      -q, --quiet=false: Only show numeric IDs
574 
+
575 
+To see how the ``docker:latest`` image was built:
576 
+
577 
+.. code-block:: bash
578 
+
579 
+	$ docker history docker
580 
+        IMAGE                                                              CREATED             CREATED BY                                                                                                                                                 SIZE
581 
+        3e23a5875458790b7a806f95f7ec0d0b2a5c1659bfc899c89f939f6d5b8f7094   8 days ago          /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8                                                                                                                       0 B
582 
+        8578938dd17054dce7993d21de79e96a037400e8d28e15e7290fea4f65128a36   8 days ago          /bin/sh -c dpkg-reconfigure locales &&    locale-gen C.UTF-8 &&    /usr/sbin/update-locale LANG=C.UTF-8                                                    1.245 MB
583 
+        be51b77efb42f67a5e96437b3e102f81e0a1399038f77bf28cea0ed23a65cf60   8 days ago          /bin/sh -c apt-get update && apt-get install -y    git    libxml2-dev    python    build-essential    make    gcc    python-dev    locales    python-pip   338.3 MB
584 
+        4b137612be55ca69776c7f30c2d2dd0aa2e7d72059820abf3e25b629f887a084   6 weeks ago         /bin/sh -c #(nop) ADD jessie.tar.xz in /                                                                                                                   121 MB
585 
+        750d58736b4b6cc0f9a9abe8f258cef269e3e9dceced1146503522be9f985ada   6 weeks ago         /bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -t jessie.tar.xz jessie http://http.debian.net/debian             0 B
586 
+        511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158   9 months ago                                                                                                                                                                   0 B
587 
+
588 
+.. _cli_images:
589 
+
590 
+``images``
591 
+----------
592 
+
593 
+::
594 
+
595 
+    Usage: docker images [OPTIONS] [NAME]
596 
+
597 
+    List images
598 
+
599 
+      -a, --all=false: Show all images (by default filter out the intermediate images used to build)
600 
+      --no-trunc=false: Don't truncate output
601 
+      -q, --quiet=false: Only show numeric IDs
602 
+      -t, --tree=false: Output graph in tree format
603 
+      -u, --untagged show only untagged images
604 
+      -v, --viz=false: Output graph in graphviz format
605 
+
606 
+Listing the most recently created images
607 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
608 
+
609 
+.. code-block:: bash
610 
+
611 
+	$ sudo docker images | head
612 
+	REPOSITORY                    TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
613 
+	<none>                        <none>              77af4d6b9913        19 hours ago        1.089 GB
614 
+	committest                    latest              b6fa739cedf5        19 hours ago        1.089 GB
615 
+	<none>                        <none>              78a85c484f71        19 hours ago        1.089 GB
616 
+	docker                        latest              30557a29d5ab        20 hours ago        1.089 GB
617 
+	<none>                        <none>              0124422dd9f9        20 hours ago        1.089 GB
618 
+	<none>                        <none>              18ad6fad3402        22 hours ago        1.082 GB
619 
+	<none>                        <none>              f9f1e26352f0        23 hours ago        1.089 GB
620 
+	tryout                        latest              2629d1fa0b81        23 hours ago        131.5 MB
621 
+	<none>                        <none>              5ed6274db6ce        24 hours ago        1.089 GB
622 
+
623 
+Listing the full length image IDs
624 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
625 
+
626 
+.. code-block:: bash
627 
+
628 
+	$ sudo docker images --no-trunc | head
629 
+	REPOSITORY                    TAG                 IMAGE ID                                                           CREATED             VIRTUAL SIZE
630 
+	<none>                        <none>              77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182   19 hours ago        1.089 GB
631 
+	committest                    latest              b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f   19 hours ago        1.089 GB
632 
+	<none>                        <none>              78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921   19 hours ago        1.089 GB
633 
+	docker                        latest              30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4   20 hours ago        1.089 GB
634 
+	<none>                        <none>              0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5   20 hours ago        1.089 GB
635 
+	<none>                        <none>              18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b   22 hours ago        1.082 GB
636 
+	<none>                        <none>              f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a   23 hours ago        1.089 GB
637 
+	tryout                        latest              2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074   23 hours ago        131.5 MB
638 
+	<none>                        <none>              5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df   24 hours ago        1.089 GB
639 
+
640 
+Displaying images visually
641 
+~~~~~~~~~~~~~~~~~~~~~~~~~~
642 
+
643 
+.. code-block:: bash
644 
+
645 
+    $ sudo docker images --viz | dot -Tpng -o docker.png
646 
+
647 
+.. image:: docker_images.gif
648 
+   :alt: Example inheritance graph of Docker images.
649 
+
650 
+
651 
+Displaying image hierarchy
652 
+~~~~~~~~~~~~~~~~~~~~~~~~~~
653 
+
654 
+.. code-block:: bash
655 
+
656 
+    $ sudo docker images --tree
657 
+
658 
+    ├─8dbd9e392a96 Size: 131.5 MB (virtual 131.5 MB) Tags: ubuntu:12.04,ubuntu:latest,ubuntu:precise
659 
+    └─27cf78414709 Size: 180.1 MB (virtual 180.1 MB)
660 
+      └─b750fe79269d Size: 24.65 kB (virtual 180.1 MB) Tags: ubuntu:12.10,ubuntu:quantal
661 
+        ├─f98de3b610d5 Size: 12.29 kB (virtual 180.1 MB)
662 
+        │ └─7da80deb7dbf Size: 16.38 kB (virtual 180.1 MB)
663 
+        │   └─65ed2fee0a34 Size: 20.66 kB (virtual 180.2 MB)
664 
+        │     └─a2b9ea53dddc Size: 819.7 MB (virtual 999.8 MB)
665 
+        │       └─a29b932eaba8 Size: 28.67 kB (virtual 999.9 MB)
666 
+        │         └─e270a44f124d Size: 12.29 kB (virtual 999.9 MB) Tags: progrium/buildstep:latest
667 
+        └─17e74ac162d8 Size: 53.93 kB (virtual 180.2 MB)
668 
+          └─339a3f56b760 Size: 24.65 kB (virtual 180.2 MB)
669 
+            └─904fcc40e34d Size: 96.7 MB (virtual 276.9 MB)
670 
+              └─b1b0235328dd Size: 363.3 MB (virtual 640.2 MB)
671 
+                └─7cb05d1acb3b Size: 20.48 kB (virtual 640.2 MB)
672 
+                  └─47bf6f34832d Size: 20.48 kB (virtual 640.2 MB)
673 
+                    └─f165104e82ed Size: 12.29 kB (virtual 640.2 MB)
674 
+                      └─d9cf85a47b7e Size: 1.911 MB (virtual 642.2 MB)
675 
+                        └─3ee562df86ca Size: 17.07 kB (virtual 642.2 MB)
676 
+                          └─b05fc2d00e4a Size: 24.96 kB (virtual 642.2 MB)
677 
+                            └─c96a99614930 Size: 12.29 kB (virtual 642.2 MB)
678 
+                              └─a6a357a48c49 Size: 12.29 kB (virtual 642.2 MB) Tags: ndj/mongodb:latest
679 
+
680 
+Displaying untagged (orphan) images
681 
+~~~~~~~~~~~~~~~~~~~~~~~~~~
682 
+
683 
+.. code-block:: bash
684 
+
685 
+    $ sudo docker images --untagged
686 
+
687 
+    REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
688 
+    <none>              <none>              8abc22fbb042        4 weeks ago         0 B
689 
+    <none>              <none>              48e5f45168b9        4 weeks ago         2.489 MB
690 
+    <none>              <none>              bf747efa0e2f        4 weeks ago         0 B
691 
+    <none>              <none>              980fe10e5736        12 weeks ago        101.4 MB
692 
+    <none>              <none>              dea752e4e117        12 weeks ago        101.4 MB
693 
+    <none>              <none>              511136ea3c5a        8 months ago        0 B
694 
+
695 
+This will display untagged images, that are the leaves of the images tree (not
696 
+intermediary layers). These images occur when a new build of an image takes the
697 
+repo:tag away from the IMAGE ID, leaving it untagged. A warning will be issued
698 
+if trying to remove an image when a container is presently using it.
699 
+By having this flag it allows for batch cleanup.
700 
+
701 
+
702 
+.. code-block:: bash
703 
+
704 
+    $ sudo docker images --untagged -q
705 
+
706 
+    8abc22fbb042
707 
+    48e5f45168b9
708 
+    bf747efa0e2f
709 
+    980fe10e5736
710 
+    dea752e4e117
711 
+    511136ea3c5a
712 
+
713 
+
714 
+Ready for use by `docker rmi ...`, like:
715 
+
716 
+.. code-block:: bash
717 
+
718 
+    $ sudo docker rmi $(sudo docker images --untagged -q)
719 
+
720 
+    8abc22fbb042
721 
+    48e5f45168b9
722 
+    bf747efa0e2f
723 
+    980fe10e5736
724 
+    dea752e4e117
725 
+    511136ea3c5a
726 
+
727 
+NOTE: Docker will warn you if any containers exist that are using these untagged images.
728 
+
729 
+.. _cli_import:
730 
+
731 
+``import``
732 
+----------
733 
+
734 
+::
735 
+
736 
+    Usage: docker import URL|- [REPOSITORY[:TAG]]
737 
+
738 
+    Create an empty filesystem image and import the contents of the tarball
739 
+    (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then optionally tag it.
740 
+
741 
+At this time, the URL must start with ``http`` and point to a single
742 
+file archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a
743 
+root filesystem. If you would like to import from a local directory or
744 
+archive, you can use the ``-`` parameter to take the data from *stdin*.
745 
+
746 
+Examples
747 
+~~~~~~~~
748 
+
749 
+Import from a remote location
750 
+.............................
751 
+
752 
+This will create a new untagged image.
753 
+
754 
+.. code-block:: bash
755 
+
756 
+    $ sudo docker import http://example.com/exampleimage.tgz
757 
+
758 
+Import from a local file
759 
+........................
760 
+
761 
+Import to docker via pipe and *stdin*.
762 
+
763 
+.. code-block:: bash
764 
+
765 
+    $ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new
766 
+
767 
+Import from a local directory
768 
+.............................
769 
+
770 
+.. code-block:: bash
771 
+
772 
+    $ sudo tar -c . | docker import - exampleimagedir
773 
+
774 
+Note the ``sudo`` in this example -- you must preserve the ownership of the
775 
+files (especially root ownership) during the archiving with tar. If you are not
776 
+root (or the sudo command) when you tar, then the ownerships might not get
777 
+preserved.
778 
+
779 
+.. _cli_info:
780 
+
781 
+``info``
782 
+--------
783 
+
784 
+::
785 
+
786 
+    Usage: docker info
787 
+
788 
+    Display system-wide information.
789 
+
790 
+.. code-block:: bash
791 
+
792 
+	$ sudo docker info
793 
+	Containers: 292
794 
+	Images: 194
795 
+	Debug mode (server): false
796 
+	Debug mode (client): false
797 
+	Fds: 22
798 
+	Goroutines: 67
799 
+	LXC Version: 0.9.0
800 
+	EventsListeners: 115
801 
+	Kernel Version: 3.8.0-33-generic
802 
+	WARNING: No swap limit support
803 
+
804 
+
805 
+.. _cli_insert:
806 
+
807 
+``insert``
808 
+----------
809 
+
810 
+::
811 
+
812 
+    Usage: docker insert IMAGE URL PATH
813 
+
814 
+    Insert a file from URL in the IMAGE at PATH
815 
+
816 
+Use the specified ``IMAGE`` as the parent for a new image which adds a
817 
+:ref:`layer <layer_def>` containing the new file. The ``insert`` command does
818 
+not modify the original image, and the new image has the contents of the parent
819 
+image, plus the new file.
820 
+
821 
+
822 
+Examples
823 
+~~~~~~~~
824 
+
825 
+Insert file from GitHub
826 
+.......................
827 
+
828 
+.. code-block:: bash
829 
+
830 
+    $ sudo docker insert 8283e18b24bc https://raw.github.com/metalivedev/django/master/postinstall /tmp/postinstall.sh
831 
+    06fd35556d7b
832 
+
833 
+.. _cli_inspect:
834 
+
835 
+``inspect``
836 
+-----------
837 
+
838 
+::
839 
+
840 
+    Usage: docker inspect CONTAINER|IMAGE [CONTAINER|IMAGE...]
841 
+
842 
+    Return low-level information on a container/image
843 
+
844 
+      -f, --format="": Format the output using the given go template.
845 
+
846 
+By default, this will render all results in a JSON array.  If a format
847 
+is specified, the given template will be executed for each result.
848 
+
849 
+Go's `text/template <http://golang.org/pkg/text/template/>`_ package
850 
+describes all the details of the format.
851 
+
852 
+Examples
853 
+~~~~~~~~
854 
+
855 
+Get an instance's IP Address
856 
+............................
857 
+
858 
+For the most part, you can pick out any field from the JSON in a
859 
+fairly straightforward manner.
860 
+
861 
+.. code-block:: bash
862 
+
863 
+    $ sudo docker inspect --format='{{.NetworkSettings.IPAddress}}' $INSTANCE_ID
864 
+
865 
+List All Port Bindings
866 
+......................
867 
+
868 
+One can loop over arrays and maps in the results to produce simple
869 
+text output:
870 
+
871 
+.. code-block:: bash
872 
+
873 
+    $ sudo docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID
874 
+
875 
+Find a Specific Port Mapping
876 
+............................
877 
+
878 
+The ``.Field`` syntax doesn't work when the field name begins with a
879 
+number, but the template language's ``index`` function does.  The
880 
+``.NetworkSettings.Ports`` section contains a map of the internal port
881 
+mappings to a list of external address/port objects, so to grab just
882 
+the numeric public port, you use ``index`` to find the specific port
883 
+map, and then ``index`` 0 contains first object inside of that.  Then
884 
+we ask for the ``HostPort`` field to get the public address.
885 
+
886 
+.. code-block:: bash
887 
+
888 
+    $ sudo docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID
889 
+
890 
+Get config
891 
+..........
892 
+
893 
+The ``.Field`` syntax doesn't work when the field contains JSON data,
894 
+but the template language's custom ``json`` function does. The ``.config``
895 
+section contains complex json object, so to grab it as JSON, you use ``json``
896 
+to convert config object into JSON
897 
+
898 
+.. code-block:: bash
899 
+
900 
+    $ sudo docker inspect --format='{{json .config}}' $INSTANCE_ID
901 
+
902 
+
903 
+.. _cli_kill:
904 
+
905 
+``kill``
906 
+--------
907 
+
908 
+::
909 
+
910 
+    Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...]
911 
+
912 
+    Kill a running container (send SIGKILL, or specified signal)
913 
+
914 
+      -s, --signal="KILL": Signal to send to the container
915 
+
916 
+The main process inside the container will be sent SIGKILL, or any signal specified with option ``--signal``.
917 
+
918 
+Known Issues (kill)
919 
+~~~~~~~~~~~~~~~~~~~
920 
+
921 
+* :issue:`197` indicates that ``docker kill`` may leave directories
922 
+  behind and make it difficult to remove the container.
923 
+* :issue:`3844` lxc 1.0.0 beta3 removed ``lcx-kill`` which is used by Docker versions before 0.8.0;
924 
+  see the issue for a workaround.
925 
+
926 
+.. _cli_load:
927 
+
928 
+``load``
929 
+--------
930 
+
931 
+::
932 
+
933 
+    Usage: docker load
934 
+
935 
+    Load an image from a tar archive on STDIN
936 
+
937 
+      -i, --input="": Read from a tar archive file, instead of STDIN
938 
+
939 
+Loads a tarred repository from a file or the standard input stream.
940 
+Restores both images and tags.
941 
+
942 
+.. code-block:: bash
943 
+
944 
+   $ sudo docker images
945 
+   REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
946 
+   $ sudo docker load < busybox.tar
947 
+   $ sudo docker images
948 
+   REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
949 
+   busybox             latest              769b9341d937        7 weeks ago         2.489 MB
950 
+   $ sudo docker load --input fedora.tar
951 
+   $ sudo docker images
952 
+   REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
953 
+   busybox             latest              769b9341d937        7 weeks ago         2.489 MB
954 
+   fedora              rawhide             0d20aec6529d        7 weeks ago         387 MB
955 
+   fedora              20                  58394af37342        7 weeks ago         385.5 MB
956 
+   fedora              heisenbug           58394af37342        7 weeks ago         385.5 MB
957 
+   fedora              latest              58394af37342        7 weeks ago         385.5 MB
958 
+
959 
+
960 
+.. _cli_login:
961 
+
962 
+``login``
963 
+---------
964 
+
965 
+::
966 
+
967 
+    Usage: docker login [OPTIONS] [SERVER]
968 
+
969 
+    Register or Login to the docker registry server
970 
+
971 
+    -e, --email="": Email
972 
+    -p, --password="": Password
973 
+    -u, --username="": Username
974 
+
975 
+    If you want to login to a private registry you can
976 
+    specify this by adding the server name.
977 
+
978 
+    example:
979 
+    docker login localhost:8080
980 
+
981 
+
982 
+.. _cli_logs:
983 
+
984 
+``logs``
985 
+--------
986 
+
987 
+::
988 
+
989 
+    Usage: docker logs [OPTIONS] CONTAINER
990 
+
991 
+    Fetch the logs of a container
992 
+
993 
+    -f, --follow=false: Follow log output
994 
+
995 
+The ``docker logs`` command is a convenience which batch-retrieves whatever
996 
+logs are present at the time of execution. This does not guarantee execution
997 
+order when combined with a ``docker run`` (i.e. your run may not have generated
998 
+any logs at the time you execute ``docker logs``).
999 
+
1000 
+The ``docker logs --follow`` command combines ``docker logs`` and ``docker attach``:
1001 
+it will first return all logs from the beginning and then continue streaming
1002 
+new output from the container's stdout and stderr.
1003 
+
1004 
+
1005 
+.. _cli_port:
1006 
+
1007 
+``port``
1008 
+--------
1009 
+
1010 
+::
1011 
+
1012 
+    Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT
1013 
+
1014 
+    Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
1015 
+
1016 
+
1017 
+.. _cli_ps:
1018 
+
1019 
+``ps``
1020 
+------
1021 
+
1022 
+::
1023 
+
1024 
+    Usage: docker ps [OPTIONS]
1025 
+
1026 
+    List containers
1027 
+
1028 
+      -a, --all=false: Show all containers. Only running containers are shown by default.
1029 
+      --before="": Show only container created before Id or Name, include non-running ones.
1030 
+      -l, --latest=false: Show only the latest created container, include non-running ones.
1031 
+      -n=-1: Show n last created containers, include non-running ones.
1032 
+      --no-trunc=false: Don't truncate output
1033 
+      -q, --quiet=false: Only display numeric IDs
1034 
+      -s, --size=false: Display sizes, not to be used with -q
1035 
+      --since="": Show only containers created since Id or Name, include non-running ones.
1036 
+
1037 
+
1038 
+Running ``docker ps`` showing 2 linked containers.
1039 
+
1040 
+.. code-block:: bash
1041 
+
1042 
+    $ docker ps
1043 
+    CONTAINER ID        IMAGE                        COMMAND                CREATED              STATUS              PORTS               NAMES
1044 
+    4c01db0b339c        ubuntu:12.04                 bash                   17 seconds ago       Up 16 seconds                           webapp
1045 
+    d7886598dbe2        crosbymichael/redis:latest   /redis-server --dir    33 minutes ago       Up 33 minutes       6379/tcp            redis,webapp/db
1046 
+    fd2645e2e2b5        busybox:latest               top                    10 days ago          Ghost                                   insane_ptolemy
1047 
+
1048 
+The last container is marked as a ``Ghost`` container. It is a container that was running when the docker daemon was restarted (upgraded, or ``-H`` settings changed). The container is still running, but as this docker daemon process is not able to manage it, you can't attach to it. To bring them out of ``Ghost`` Status, you need to use ``docker kill`` or ``docker restart``.
1049 
+
1050 
+``docker ps`` will show only running containers by default.  To see all containers: ``docker ps -a``
1051 
+
1052 
+.. _cli_pull:
1053 
+
1054 
+``pull``
1055 
+--------
1056 
+
1057 
+::
1058 
+
1059 
+    Usage: docker pull NAME
1060 
+
1061 
+    Pull an image or a repository from the registry
1062 
+
1063 
+      -t, --tag="": Download tagged image in repository
1064 
+
1065 
+
1066 
+.. _cli_push:
1067 
+
1068 
+``push``
1069 
+--------
1070 
+
1071 
+::
1072 
+
1073 
+    Usage: docker push NAME
1074 
+
1075 
+    Push an image or a repository to the registry
1076 
+
1077 
+
1078 
+.. _cli_restart:
1079 
+
1080 
+``restart``
1081 
+-----------
1082 
+
1083 
+::
1084 
+
1085 
+    Usage: docker restart [OPTIONS] NAME
1086 
+
1087 
+    Restart a running container
1088 
+
1089 
+       -t, --time=10: Number of seconds to try to stop for before killing the container. Once killed it will then be restarted. Default=10
1090 
+
1091 
+.. _cli_rm:
1092 
+
1093 
+``rm``
1094 
+------
1095 
+
1096 
+::
1097 
+
1098 
+    Usage: docker rm [OPTIONS] CONTAINER
1099 
+
1100 
+    Remove one or more containers
1101 
+        -l, --link="": Remove the link instead of the actual container
1102 
+        -f, --force=false: Force removal of running container
1103 
+        -v, --volumes=false: Remove the volumes associated to the container
1104 
+
1105 
+Known Issues (rm)
1106 
+~~~~~~~~~~~~~~~~~
1107 
+
1108 
+* :issue:`197` indicates that ``docker kill`` may leave directories
1109 
+  behind and make it difficult to remove the container.
1110 
+
1111 
+
1112 
+Examples:
1113 
+~~~~~~~~~
1114 
+
1115 
+.. code-block:: bash
1116 
+
1117 
+    $ sudo docker rm /redis
1118 
+    /redis
1119 
+
1120 
+
1121 
+This will remove the container referenced under the link ``/redis``.
1122 
+
1123 
+
1124 
+.. code-block:: bash
1125 
+
1126 
+    $ sudo docker rm --link /webapp/redis
1127 
+    /webapp/redis
1128 
+
1129 
+
1130 
+This will remove the underlying link between ``/webapp`` and the ``/redis`` containers removing all
1131 
+network communication.
1132 
+
1133 
+.. code-block:: bash
1134 
+
1135 
+    $ sudo docker rm `docker ps -a -q`
1136 
+
1137 
+
1138 
+This command will delete all stopped containers. The command ``docker ps -a -q`` will return all
1139 
+existing container IDs and pass them to the ``rm`` command which will delete them. Any running
1140 
+containers will not be deleted.
1141 
+
1142 
+.. _cli_rmi:
1143 
+
1144 
+``rmi``
1145 
+-------
1146 
+
1147 
+::
1148 
+
1149 
+    Usage: docker rmi IMAGE [IMAGE...]
1150 
+
1151 
+    Remove one or more images
1152 
+
1153 
+      -f, --force=false: Force
1154 
+      --no-prune=false: Do not delete untagged parents
1155 
+
1156 
+Removing tagged images
1157 
+~~~~~~~~~~~~~~~~~~~~~~
1158 
+
1159 
+Images can be removed either by their short or long ID's, or their image names.
1160 
+If an image has more than one name, each of them needs to be removed before the
1161 
+image is removed.
1162 
+
1163 
+.. code-block:: bash
1164 
+
1165 
+    $ sudo docker images
1166 
+    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
1167 
+    test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
1168 
+    test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
1169 
+    test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
1170 
+
1171 
+    $ sudo docker rmi fd484f19954f
1172 
+    Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories
1173 
+    2013/12/11 05:47:16 Error: failed to remove one or more images
1174 
+
1175 
+    $ sudo docker rmi test1
1176 
+    Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
1177 
+    $ sudo docker rmi test2
1178 
+    Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
1179 
+
1180 
+    $ sudo docker images
1181 
+    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
1182 
+    test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
1183 
+    $ sudo docker rmi test
1184 
+    Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
1185 
+    Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
1186 
+
1187 
+
1188 
+.. _cli_run:
1189 
+
1190 
+``run``
1191 
+-------
1192 
+
1193 
+::
1194 
+
1195 
+    Usage: docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...]
1196 
+
1197 
+    Run a command in a new container
1198 
+
1199 
+      -a, --attach=map[]: Attach to stdin, stdout or stderr
1200 
+      -c, --cpu-shares=0: CPU shares (relative weight)
1201 
+      --cidfile="": Write the container ID to the file
1202 
+      -d, --detach=false: Detached mode: Run container in the background, print new container id
1203 
+      -e, --env=[]: Set environment variables
1204 
+      -h, --hostname="": Container host name
1205 
+      -i, --interactive=false: Keep stdin open even if not attached
1206 
+      --privileged=false: Give extended privileges to this container
1207 
+      -m, --memory="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
1208 
+      -n, --networking=true: Enable networking for this container
1209 
+      -p, --publish=[]: Map a network port to the container
1210 
+      --rm=false: Automatically remove the container when it exits (incompatible with -d)
1211 
+      -t, --tty=false: Allocate a pseudo-tty
1212 
+      -u, --user="": Username or UID
1213 
+      --dns=[]: Set custom dns servers for the container
1214 
+      --dns-search=[]: Set custom DNS search domains for the container
1215 
+      -v, --volume=[]: Create a bind mount to a directory or file with: [host-path]:[container-path]:[rw|ro]. If a directory "container-path" is missing, then docker creates a new volume.
1216 
+      --volumes-from="": Mount all volumes from the given container(s)
1217 
+      --entrypoint="": Overwrite the default entrypoint set by the image
1218 
+      -w, --workdir="": Working directory inside the container
1219 
+      --lxc-conf=[]: (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
1220 
+      --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode)
1221 
+      --expose=[]: Expose a port from the container without publishing it to your host
1222 
+      --link="": Add link to another container (name:alias)
1223 
+      --name="": Assign the specified name to the container. If no name is specific docker will generate a random name
1224 
+      -P, --publish-all=false: Publish all exposed ports to the host interfaces
1225 
+
1226 
+The ``docker run`` command first ``creates`` a writeable container layer over
1227 
+the specified image, and then ``starts`` it using the specified command. That
1228 
+is, ``docker run`` is equivalent to the API ``/containers/create`` then
1229 
+``/containers/(id)/start``.
1230 
+Once the container is stopped it still exists and can be started back up.  See ``docker ps -a`` to view a list of all containers.
1231 
+
1232 
+The ``docker run`` command can be used in combination with ``docker commit`` to
1233 
+:ref:`change the command that a container runs <cli_commit_examples>`.
1234 
+
1235 
+See :ref:`port_redirection` for more detailed information about the ``--expose``,
1236 
+``-p``, ``-P`` and ``--link`` parameters, and :ref:`working_with_links_names` for
1237 
+specific examples using ``--link``.
1238 
+
1239 
+Known Issues (run --volumes-from)
1240 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1241 
+
1242 
+* :issue:`2702`: "lxc-start: Permission denied - failed to mount"
1243 
+  could indicate a permissions problem with AppArmor. Please see the
1244 
+  issue for a workaround.
1245 
+
1246 
+Examples:
1247 
+~~~~~~~~~
1248 
+
1249 
+.. code-block:: bash
1250 
+
1251 
+    $ sudo docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
1252 
+
1253 
+This will create a container and print ``test`` to the console. The
1254 
+``cidfile`` flag makes Docker attempt to create a new file and write the
1255 
+container ID to it. If the file exists already, Docker will return an
1256 
+error. Docker will close this file when ``docker run`` exits.
1257 
+
1258 
+.. code-block:: bash
1259 
+
1260 
+   $ sudo docker run -t -i --rm ubuntu bash
1261 
+   root@bc338942ef20:/# mount -t tmpfs none /mnt
1262 
+   mount: permission denied
1263 
+
1264 
+
1265 
+This will *not* work, because by default, most potentially dangerous
1266 
+kernel capabilities are dropped; including ``cap_sys_admin`` (which is
1267 
+required to mount filesystems). However, the ``--privileged`` flag will
1268 
+allow it to run:
1269 
+
1270 
+.. code-block:: bash
1271 
+
1272 
+   $ sudo docker run --privileged ubuntu bash
1273 
+   root@50e3f57e16e6:/# mount -t tmpfs none /mnt
1274 
+   root@50e3f57e16e6:/# df -h
1275 
+   Filesystem      Size  Used Avail Use% Mounted on
1276 
+   none            1.9G     0  1.9G   0% /mnt
1277 
+
1278 
+
1279 
+The ``--privileged`` flag gives *all* capabilities to the container,
1280 
+and it also lifts all the limitations enforced by the ``device``
1281 
+cgroup controller. In other words, the container can then do almost
1282 
+everything that the host can do. This flag exists to allow special
1283 
+use-cases, like running Docker within Docker.
1284 
+
1285 
+.. code-block:: bash
1286 
+
1287 
+   $ sudo docker  run -w /path/to/dir/ -i -t  ubuntu pwd
1288 
+
1289 
+The ``-w`` lets the command being executed inside directory given,
1290 
+here ``/path/to/dir/``. If the path does not exists it is created inside the
1291 
+container.
1292 
+
1293 
+.. code-block:: bash
1294 
+
1295 
+   $ sudo docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
1296 
+
1297 
+The ``-v`` flag mounts the current working directory into the container.
1298 
+The ``-w`` lets the command being executed inside the current
1299 
+working directory, by changing into the directory to the value
1300 
+returned by ``pwd``. So this combination executes the command
1301 
+using the container, but inside the current working directory.
1302 
+
1303 
+.. code-block:: bash
1304 
+
1305 
+    $ sudo docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
1306 
+
1307 
+When the host directory of a bind-mounted volume doesn't exist, Docker
1308 
+will automatically create this directory on the host for you. In the
1309 
+example above, Docker will create the ``/doesnt/exist`` folder before
1310 
+starting your container.
1311 
+
1312 
+.. code-block:: bash
1313 
+
1314 
+   $ sudo docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v ./static-docker:/usr/bin/docker busybox sh
1315 
+
1316 
+By bind-mounting the docker unix socket and statically linked docker binary
1317 
+(such as that provided by https://get.docker.io), you give the container
1318 
+the full access to create and manipulate the host's docker daemon.
1319 
+
1320 
+.. code-block:: bash
1321 
+
1322 
+    $ sudo docker run -p 127.0.0.1:80:8080 ubuntu bash
1323 
+
1324 
+This binds port ``8080`` of the container to port ``80`` on ``127.0.0.1`` of the
1325 
+host machine. :ref:`port_redirection` explains in detail how to manipulate ports
1326 
+in Docker.
1327 
+
1328 
+.. code-block:: bash
1329 
+
1330 
+    $ sudo docker run --expose 80 ubuntu bash
1331 
+
1332 
+This exposes port ``80`` of the container for use within a link without
1333 
+publishing the port to the host system's interfaces. :ref:`port_redirection`
1334 
+explains in detail how to manipulate ports in Docker.
1335 
+
1336 
+.. code-block:: bash
1337 
+
1338 
+    $ sudo docker run --name console -t -i ubuntu bash
1339 
+
1340 
+This will create and run a new container with the container name
1341 
+being ``console``.
1342 
+
1343 
+.. code-block:: bash
1344 
+
1345 
+    $ sudo docker run --link /redis:redis --name console ubuntu bash
1346 
+
1347 
+The ``--link`` flag will link the container named ``/redis`` into the
1348 
+newly created container with the alias ``redis``.  The new container
1349 
+can access the network and environment of the redis container via
1350 
+environment variables.  The ``--name`` flag will assign the name ``console``
1351 
+to the newly created container.
1352 
+
1353 
+.. code-block:: bash
1354 
+
1355 
+   $ sudo docker run --volumes-from 777f7dc92da7,ba8c0c54f0f2:ro -i -t ubuntu pwd
1356 
+
1357 
+The ``--volumes-from`` flag mounts all the defined volumes from the
1358 
+referenced containers. Containers can be specified by a comma separated
1359 
+list or by repetitions of the ``--volumes-from`` argument. The container
1360 
+ID may be optionally suffixed with ``:ro`` or ``:rw`` to mount the volumes in
1361 
+read-only or read-write mode, respectively. By default, the volumes are mounted
1362 
+in the same mode (read write or read only) as the reference container.
1363 
+
1364 
+A complete example
1365 
+..................
1366 
+
1367 
+.. code-block:: bash
1368 
+
1369 
+   $ sudo docker run -d --name static static-web-files sh
1370 
+   $ sudo docker run -d --expose=8098 --name riak riakserver
1371 
+   $ sudo docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver
1372 
+   $ sudo docker run -d -p 1443:443 --dns=dns.dev.org --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver
1373 
+   $ sudo docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log
1374 
+
1375 
+This example shows 5 containers that might be set up to test a web application change:
1376 
+
1377 
+1. Start a pre-prepared volume image ``static-web-files`` (in the background) that has CSS, image and static HTML in it, (with a ``VOLUME`` instruction in the ``Dockerfile`` to allow the web server to use those files);
1378 
+2. Start a pre-prepared ``riakserver`` image, give the container name ``riak`` and expose port ``8098`` to any containers that link to it;
1379 
+3. Start the ``appserver`` image, restricting its memory usage to 100MB, setting two environment variables ``DEVELOPMENT`` and ``BRANCH`` and bind-mounting the current directory (``$(pwd)``) in the container in read-only mode as ``/app/bin``;
1380 
+4. Start the ``webserver``, mapping port ``443`` in the container to port ``1443`` on the Docker server, setting the DNS server to ``dns.dev.org`` and DNS search domain to ``dev.org``, creating a volume to put the log files into (so we can access it from another container), then importing the files from the volume exposed by the ``static`` container, and linking to all exposed ports from ``riak`` and ``app``. Lastly, we set the hostname to ``web.sven.dev.org`` so its consistent with the pre-generated SSL certificate;
1381 
+5. Finally, we create a container that runs ``tail -f access.log`` using the logs volume from the ``web`` container, setting the workdir to ``/var/log/httpd``. The ``--rm`` option means that when the container exits, the container's layer is removed.
1382 
+
1383 
+
1384 
+.. _cli_save:
1385 
+
1386 
+``save``
1387 
+---------
1388 
+
1389 
+::
1390 
+
1391 
+    Usage: docker save IMAGE
1392 
+
1393 
+    Save an image to a tar archive (streamed to stdout by default)
1394 
+
1395 
+      -o, --output="": Write to an file, instead of STDOUT
1396 
+
1397 
+
1398 
+Produces a tarred repository to the standard output stream.
1399 
+Contains all parent layers, and all tags + versions, or specified repo:tag.
1400 
+
1401 
+.. code-block:: bash
1402 
+
1403 
+   $ sudo docker save busybox > busybox.tar
1404 
+   $ ls -sh b.tar
1405 
+   2.7M b.tar
1406 
+   $ sudo docker save --output busybox.tar busybox
1407 
+   $ ls -sh b.tar
1408 
+   2.7M b.tar
1409 
+   $ sudo docker save -o fedora-all.tar fedora
1410 
+   $ sudo docker save -o fedora-latest.tar fedora:latest
1411 
+
1412 
+
1413 
+.. _cli_search:
1414 
+
1415 
+``search``
1416 
+----------
1417 
+
1418 
+::
1419 
+
1420 
+    Usage: docker search TERM
1421 
+
1422 
+    Search the docker index for images
1423 
+
1424 
+     --no-trunc=false: Don't truncate output
1425 
+     -s, --stars=0: Only displays with at least xxx stars
1426 
+     -t, --trusted=false: Only show trusted builds
1427 
+
1428 
+.. _cli_start:
1429 
+
1430 
+``start``
1431 
+---------
1432 
+
1433 
+::
1434 
+
1435 
+    Usage: docker start [OPTIONS] CONTAINER
1436 
+
1437 
+    Start a stopped container
1438 
+
1439 
+      -a, --attach=false: Attach container's stdout/stderr and forward all signals to the process
1440 
+      -i, --interactive=false: Attach container's stdin
1441 
+
1442 
+.. _cli_stop:
1443 
+
1444 
+``stop``
1445 
+--------
1446 
+
1447 
+::
1448 
+
1449 
+    Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...]
1450 
+
1451 
+    Stop a running container (Send SIGTERM, and then SIGKILL after grace period)
1452 
+
1453 
+      -t, --time=10: Number of seconds to wait for the container to stop before killing it.
1454 
+
1455 
+The main process inside the container will receive SIGTERM, and after a grace period, SIGKILL
1456 
+
1457 
+.. _cli_tag:
1458 
+
1459 
+``tag``
1460 
+-------
1461 
+
1462 
+::
1463 
+
1464 
+    Usage: docker tag [OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]
1465 
+
1466 
+    Tag an image into a repository
1467 
+
1468 
+      -f, --force=false: Force
1469 
+
1470 
+.. _cli_top:
1471 
+
1472 
+``top``
1473 
+-------
1474 
+
1475 
+::
1476 
+
1477 
+    Usage: docker top CONTAINER [ps OPTIONS]
1478 
+
1479 
+    Lookup the running processes of a container
1480 
+
1481 
+.. _cli_version:
1482 
+
1483 
+``version``
1484 
+-----------
1485 
+
1486 
+Show the version of the Docker client, daemon, and latest released version.
1487 
+
1488 
+
1489 
+.. _cli_wait:
1490 
+
1491 
+``wait``
1492 
+--------
1493 
+
1494 
+::
1495 
+
1496 
+    Usage: docker wait [OPTIONS] NAME
1497 
+
1498 
+    Block until a container stops, then print its exit code.
server/server.go
History View file @ 5f3812e
... ... 
@@ -55,6 +55,7 @@ import (
55 55 
 	"github.com/dotcloud/docker/registry"
56 56 
 	"github.com/dotcloud/docker/runconfig"
57 57 
 	"github.com/dotcloud/docker/utils"
58 
+	"github.com/dotcloud/docker/utils/filters"
58 59 
 )
59 60
60 61 
 func (srv *Server) handlerWrap(h engine.Handler) engine.Handler {
... ... 
@@ -694,10 +695,23 @@ func (srv *Server) ImagesViz(job *engine.Job) engine.Status {
694 694
695 695 
 func (srv *Server) Images(job *engine.Job) engine.Status {
696 696 
 	var (
697 
-		allImages map[string]*image.Image
698 
-		err       error
697 
+		allImages   map[string]*image.Image
698 
+		err         error
699 
+		filt_tagged = true
699 700 
 	)
700 
-	if job.GetenvBool("all") {
701 
+
702 
+	imageFilters, err := filters.ParseFlag(job.Getenv("filters"), nil)
703 
+	if err != nil {
704 
+		return job.Error(err)
705 
+	}
706 
+	if i, ok := imageFilters["untagged"]; ok && strings.ToLower(i) == "true" {
707 
+		filt_tagged = false
708 
+	}
709 
+	if i, ok := imageFilters["tagged"]; ok && strings.ToLower(i) == "false" {
710 
+		filt_tagged = false
711 
+	}
712 
+
713 
+	if job.GetenvBool("all") && !filt_tagged {
701 714 
 		allImages, err = srv.daemon.Graph().Map()
702 715 
 	} else {
703 716 
 		allImages, err = srv.daemon.Graph().Heads()
... ... 
@@ -721,17 +735,22 @@ func (srv *Server) Images(job *engine.Job) engine.Status {
721 721 
 			}
722 722
723 723 
 			if out, exists := lookup[id]; exists {
724 
-				out.SetList("RepoTags", append(out.GetList("RepoTags"), fmt.Sprintf("%s:%s", name, tag)))
724 
+				if filt_tagged {
725 
+					out.SetList("RepoTags", append(out.GetList("RepoTags"), fmt.Sprintf("%s:%s", name, tag)))
726 
+				}
725 727 
 			} else {
726 
-				out := &engine.Env{}
728 
+				// get the boolean list for if only the untagged images are requested
727 729 
 				delete(allImages, id)
728 
-				out.Set("ParentId", image.Parent)
729 
-				out.SetList("RepoTags", []string{fmt.Sprintf("%s:%s", name, tag)})
730 
-				out.Set("Id", image.ID)
731 
-				out.SetInt64("Created", image.Created.Unix())
732 
-				out.SetInt64("Size", image.Size)
733 
-				out.SetInt64("VirtualSize", image.GetParentsSize(0)+image.Size)
734 
-				lookup[id] = out
730 
+				if filt_tagged {
731 
+					out := &engine.Env{}
732 
+					out.Set("ParentId", image.Parent)
733 
+					out.SetList("RepoTags", []string{fmt.Sprintf("%s:%s", name, tag)})
734 
+					out.Set("Id", image.ID)
735 
+					out.SetInt64("Created", image.Created.Unix())
736 
+					out.SetInt64("Size", image.Size)
737 
+					out.SetInt64("VirtualSize", image.GetParentsSize(0)+image.Size)
738 
+					lookup[id] = out
739 
+				}
735 740 
 			}
736 741
737 742 
 		}
utils/filters/filter.go
History View file @ 5f3812e
738 743 
new file mode 100644
... ... 
@@ -0,0 +1,53 @@
0 
+package filters
1 
+
2 
+import (
3 
+	"errors"
4 
+	"fmt"
5 
+	"io"
6 
+)
7 
+
8 
+var DefaultFilterProcs = FilterProcSet{}
9 
+
10 
+func Register(name string, fp FilterProc) error {
11 
+	return DefaultFilterProcs.Register(name, fp)
12 
+}
13 
+
14 
+var ErrorFilterExists = errors.New("filter already exists and ")
15 
+var ErrorFilterExistsConflict = errors.New("filter already exists and FilterProc are different")
16 
+
17 
+type FilterProcSet map[string]FilterProc
18 
+
19 
+func (fs FilterProcSet) Process(context string) {
20 
+}
21 
+
22 
+func (fs FilterProcSet) Register(name string, fp FilterProc) error {
23 
+	if v, ok := fs[name]; ok {
24 
+		if v == fp {
25 
+			return ErrorFilterExists
26 
+		} else {
27 
+			return ErrorFilterExistsConflict
28 
+		}
29 
+	}
30 
+	fs[name] = fp
31 
+	return nil
32 
+}
33 
+
34 
+type FilterProc interface {
35 
+	Process(context, key, value string, output io.Writer) error
36 
+}
37 
+
38 
+type UnknownFilterProc struct{}
39 
+
40 
+func (ufp UnknownFilterProc) Process(context, key, value string, output io.Writer) error {
41 
+	if output != nil {
42 
+		fmt.Fprintf(output, "do not know how to process [%s : %s]", key, value)
43 
+	}
44 
+	return nil
45 
+}
46 
+
47 
+type Filter interface {
48 
+	Scope() string
49 
+	Target() string
50 
+	Expressions() []string
51 
+	Match(interface{}) bool
52 
+}
utils/filters/parse.go
History View file @ 5f3812e
0 53 
new file mode 100644
... ... 
@@ -0,0 +1,47 @@
0 
+package filters
1 
+
2 
+import (
3 
+	"errors"
4 
+	"strings"
5 
+)
6 
+
7 
+/*
8 
+Parse the argument to the filter flag. Like
9 
+
10 
+  `docker ps -f 'created=today;image.name=ubuntu*'`
11 
+
12 
+Filters delimited by ';', and expected to be 'name=value'
13 
+
14 
+If prev map is provided, then it is appended to, and returned. By default a new
15 
+map is created.
16 
+*/
17 
+func ParseFlag(arg string, prev map[string]string) (map[string]string, error) {
18 
+	var filters map[string]string
19 
+	if prev != nil {
20 
+		filters = prev
21 
+	} else {
22 
+		filters = map[string]string{}
23 
+	}
24 
+  if len(arg) == 0 {
25 
+    return filters, nil
26 
+  }
27 
+
28 
+	for _, chunk := range strings.Split(arg, ";") {
29 
+		if !strings.Contains(chunk, "=") {
30 
+			return filters, ErrorBadFormat
31 
+		}
32 
+		f := strings.SplitN(chunk, "=", 2)
33 
+		filters[f[0]] = f[1]
34 
+	}
35 
+	return filters, nil
36 
+}
37 
+
38 
+var ErrorBadFormat = errors.New("bad format of filter (expected name=value)")
39 
+
40 
+func ToParam(f map[string]string) string {
41 
+	fs := []string{}
42 
+	for k, v := range f {
43 
+		fs = append(fs, k+"="+v)
44 
+	}
45 
+	return strings.Join(fs, ";")
46 
+}