cli.rst 50 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455
  1. :title: Command Line Interface
  2. :description: Docker's CLI command description and usage
  3. :keywords: Docker, Docker documentation, CLI, command line
  4. .. _cli:
  5. Command Line Help
  6. -----------------
  7. To list available commands, either run ``docker`` with no parameters or execute
  8. ``docker help``::
  9. $ sudo docker
  10. Usage: docker [OPTIONS] COMMAND [arg...]
  11. -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.
  12. A self-sufficient runtime for linux containers.
  13. ...
  14. .. _cli_options:
  15. Options
  16. -------
  17. Single character commandline options can be combined, so rather than typing
  18. ``docker run -t -i --name test busybox sh``, you can write
  19. ``docker run -ti --name test busybox sh``.
  20. Boolean
  21. ~~~~~~~
  22. Boolean options look like ``-d=false``. The value you see is the
  23. default value which gets set if you do **not** use the boolean
  24. flag. If you do call ``run -d``, that sets the opposite boolean value,
  25. so in this case, ``true``, and so ``docker run -d`` **will** run in
  26. "detached" mode, in the background. Other boolean options are similar
  27. -- specifying them will set the value to the opposite of the default
  28. value.
  29. Multi
  30. ~~~~~
  31. Options like ``-a=[]`` indicate they can be specified multiple times::
  32. docker run -a stdin -a stdout -a stderr -i -t ubuntu /bin/bash
  33. Sometimes this can use a more complex value string, as for ``-v``::
  34. docker run -v /host:/container example/mysql
  35. Strings and Integers
  36. ~~~~~~~~~~~~~~~~~~~~
  37. Options like ``--name=""`` expect a string, and they can only be
  38. specified once. Options like ``-c=0`` expect an integer, and they can
  39. only be specified once.
  40. ----
  41. Commands
  42. --------
  43. .. _cli_daemon:
  44. ``daemon``
  45. ----------
  46. ::
  47. Usage of docker:
  48. -D, --debug=false: Enable debug mode
  49. -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].
  50. -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
  51. --api-enable-cors=false: Enable CORS headers in the remote API
  52. -b, --bridge="": Attach containers to a pre-existing network bridge; use 'none' to disable container networking
  53. -bip="": Use this CIDR notation address for the network bridge's IP, not compatible with -b
  54. -d, --daemon=false: Enable daemon mode
  55. --dns=[]: Force docker to use specific DNS servers
  56. --dns-search=[]: Force Docker to use specific DNS search domains
  57. -g, --graph="/var/lib/docker": Path to use as the root of the docker runtime
  58. --icc=true: Enable inter-container communication
  59. --ip="0.0.0.0": Default IP address to use when binding container ports
  60. --ip-forward=true: Enable net.ipv4.ip_forward
  61. --iptables=true: Enable Docker's addition of iptables rules
  62. -p, --pidfile="/var/run/docker.pid": Path to use for daemon PID file
  63. -r, --restart=true: Restart previously running containers
  64. -s, --storage-driver="": Force the docker runtime to use a specific storage driver
  65. -e, --exec-driver="native": Force the docker runtime to use a specific exec driver
  66. -v, --version=false: Print version information and quit
  67. --tls=false: Use TLS; implied by tls-verify flags
  68. --tlscacert="~/.docker/ca.pem": Trust only remotes providing a certificate signed by the CA given here
  69. --tlscert="~/.docker/cert.pem": Path to TLS certificate file
  70. --tlskey="~/.docker/key.pem": Path to TLS key file
  71. --tlsverify=false: Use TLS and verify the remote (daemon: verify client, client: verify daemon)
  72. --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
  73. The Docker daemon is the persistent process that manages containers. Docker uses the same binary for both the
  74. daemon and client. To run the daemon you provide the ``-d`` flag.
  75. To force Docker to use devicemapper as the storage driver, use ``docker -d -s devicemapper``.
  76. To set the DNS server for all Docker containers, use ``docker -d --dns 8.8.8.8``.
  77. To set the DNS search domain for all Docker containers, use ``docker -d --dns-search example.com``.
  78. To run the daemon with debug output, use ``docker -d -D``.
  79. To use lxc as the execution driver, use ``docker -d -e lxc``.
  80. The docker client will also honor the ``DOCKER_HOST`` environment variable to set
  81. the ``-H`` flag for the client.
  82. ::
  83. docker -H tcp://0.0.0.0:4243 ps
  84. # or
  85. export DOCKER_HOST="tcp://0.0.0.0:4243"
  86. docker ps
  87. # both are equal
  88. To run the daemon with `systemd socket activation <http://0pointer.de/blog/projects/socket-activation.html>`_, use ``docker -d -H fd://``.
  89. Using ``fd://`` will work perfectly for most setups but you can also specify individual sockets too ``docker -d -H fd://3``.
  90. If the specified socket activated files aren't found then docker will exit.
  91. 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/>`_.
  92. Docker supports softlinks for the Docker data directory (``/var/lib/docker``) and for ``/tmp``.
  93. TMPDIR and the data directory can be set like this:
  94. ::
  95. TMPDIR=/mnt/disk2/tmp /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1
  96. # or
  97. export TMPDIR=/mnt/disk2/tmp
  98. /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1
  99. .. _cli_attach:
  100. ``attach``
  101. ----------
  102. ::
  103. Usage: docker attach CONTAINER
  104. Attach to a running container.
  105. --no-stdin=false: Do not attach stdin
  106. --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode)
  107. You can detach from the container again (and leave it running) with
  108. ``CTRL-c`` (for a quiet exit) or ``CTRL-\`` to get a stacktrace of
  109. the Docker client when it quits. When you detach from the container's
  110. process the exit code will be returned to the client.
  111. To stop a container, use ``docker stop``.
  112. To kill the container, use ``docker kill``.
  113. .. _cli_attach_examples:
  114. Examples:
  115. ~~~~~~~~~
  116. .. code-block:: bash
  117. $ ID=$(sudo docker run -d ubuntu /usr/bin/top -b)
  118. $ sudo docker attach $ID
  119. top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05
  120. Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
  121. 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
  122. Mem: 373572k total, 355560k used, 18012k free, 27872k buffers
  123. Swap: 786428k total, 0k used, 786428k free, 221740k cached
  124. PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
  125. 1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top
  126. top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05
  127. Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
  128. 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
  129. Mem: 373572k total, 355244k used, 18328k free, 27872k buffers
  130. Swap: 786428k total, 0k used, 786428k free, 221776k cached
  131. PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
  132. 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top
  133. top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05
  134. Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
  135. 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
  136. Mem: 373572k total, 355780k used, 17792k free, 27880k buffers
  137. Swap: 786428k total, 0k used, 786428k free, 221776k cached
  138. PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
  139. 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top
  140. ^C$
  141. $ sudo docker stop $ID
  142. .. _cli_build:
  143. ``build``
  144. ---------
  145. ::
  146. Usage: docker build [OPTIONS] PATH | URL | -
  147. Build a new container image from the source code at PATH
  148. -t, --tag="": Repository name (and optionally a tag) to be applied
  149. to the resulting image in case of success.
  150. -q, --quiet=false: Suppress the verbose output generated by the containers.
  151. --no-cache: Do not use the cache when building the image.
  152. --rm=true: Remove intermediate containers after a successful build
  153. The files at ``PATH`` or ``URL`` are called the "context" of the build.
  154. The build process may refer to any of the files in the context, for example when
  155. using an :ref:`ADD <dockerfile_add>` instruction.
  156. When a single ``Dockerfile`` is given as ``URL``, then no context is set.
  157. When a Git repository is set as ``URL``, then the repository is used as the context.
  158. The Git repository is cloned with its submodules (`git clone --recursive`).
  159. A fresh git clone occurs in a temporary directory on your local host, and then this
  160. is sent to the Docker daemon as the context.
  161. This way, your local user credentials and vpn's etc can be used to access private repositories
  162. .. _cli_build_examples:
  163. .. seealso:: :ref:`dockerbuilder`.
  164. Examples:
  165. ~~~~~~~~~
  166. .. code-block:: bash
  167. $ sudo docker build .
  168. Uploading context 10240 bytes
  169. Step 1 : FROM busybox
  170. Pulling repository busybox
  171. ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
  172. Step 2 : RUN ls -lh /
  173. ---> Running in 9c9e81692ae9
  174. total 24
  175. drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin
  176. drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev
  177. drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc
  178. drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib
  179. lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib
  180. dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc
  181. lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin
  182. dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys
  183. drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp
  184. drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr
  185. ---> b35f4035db3f
  186. Step 3 : CMD echo Hello World
  187. ---> Running in 02071fceb21b
  188. ---> f52f38b7823e
  189. Successfully built f52f38b7823e
  190. Removing intermediate container 9c9e81692ae9
  191. Removing intermediate container 02071fceb21b
  192. This example specifies that the ``PATH`` is ``.``, and so all the files in
  193. the local directory get tar'd and sent to the Docker daemon. The ``PATH``
  194. specifies where to find the files for the "context" of the build on
  195. the Docker daemon. Remember that the daemon could be running on a
  196. remote machine and that no parsing of the ``Dockerfile`` happens at the
  197. client side (where you're running ``docker build``). That means that
  198. *all* the files at ``PATH`` get sent, not just the ones listed to
  199. :ref:`ADD <dockerfile_add>` in the ``Dockerfile``.
  200. The transfer of context from the local machine to the Docker daemon is
  201. what the ``docker`` client means when you see the "Uploading context"
  202. message.
  203. If you wish to keep the intermediate containers after the build is complete,
  204. you must use ``--rm=false``. This does not affect the build cache.
  205. .. code-block:: bash
  206. $ sudo docker build -t vieux/apache:2.0 .
  207. This will build like the previous example, but it will then tag the
  208. resulting image. The repository name will be ``vieux/apache`` and the
  209. tag will be ``2.0``
  210. .. code-block:: bash
  211. $ sudo docker build - < Dockerfile
  212. This will read a ``Dockerfile`` from *stdin* without context. Due to
  213. the lack of a context, no contents of any local directory will be sent
  214. to the ``docker`` daemon. Since there is no context, a ``Dockerfile``
  215. ``ADD`` only works if it refers to a remote URL.
  216. .. code-block:: bash
  217. $ sudo docker build github.com/creack/docker-firefox
  218. This will clone the GitHub repository and use the cloned repository as
  219. context. The ``Dockerfile`` at the root of the repository is used as
  220. ``Dockerfile``. Note that you can specify an arbitrary Git repository
  221. by using the ``git://`` schema.
  222. .. _cli_commit:
  223. ``commit``
  224. ----------
  225. ::
  226. Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
  227. Create a new image from a container's changes
  228. -m, --message="": Commit message
  229. -a, --author="": Author (eg. "John Hannibal Smith <hannibal@a-team.com>"
  230. --run="": Configuration changes to be applied when the image is launched with `docker run`.
  231. (ex: --run='{"Cmd": ["cat", "/world"], "PortSpecs": ["22"]}')
  232. .. _cli_commit_examples:
  233. Commit an existing container
  234. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  235. .. code-block:: bash
  236. $ sudo docker ps
  237. ID IMAGE COMMAND CREATED STATUS PORTS
  238. c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours
  239. 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours
  240. $ docker commit c3f279d17e0a SvenDowideit/testimage:version3
  241. f5283438590d
  242. $ docker images | head
  243. REPOSITORY TAG ID CREATED VIRTUAL SIZE
  244. SvenDowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB
  245. Change the command that a container runs
  246. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  247. Sometimes you have an application container running just a service and you need
  248. to make a quick change and then change it back.
  249. In this example, we run a container with ``ls`` and then change the image to
  250. run ``ls /etc``.
  251. .. code-block:: bash
  252. $ docker run -t --name test ubuntu ls
  253. bin boot dev etc home lib lib64 media mnt opt proc root run sbin selinux srv sys tmp usr var
  254. $ docker commit --run='{"Cmd": ["ls","/etc"]}' test test2
  255. 933d16de9e70005304c1717b5c6f2f39d6fd50752834c6f34a155c70790011eb
  256. $ docker run -t test2
  257. adduser.conf gshadow login.defs rc0.d
  258. alternatives gshadow- logrotate.d rc1.d
  259. apt host.conf lsb-base rc2.d
  260. ...
  261. Merged configs example
  262. ......................
  263. Say you have a Dockerfile like so:
  264. .. code-block:: bash
  265. ENV MYVAR foobar
  266. RUN apt-get install openssh
  267. EXPOSE 22
  268. CMD ["/usr/sbin/sshd -D"]
  269. ...
  270. 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.
  271. .. code-block:: bash
  272. $ docker build -t me/foo .
  273. $ docker run -t -i me/foo /bin/bash
  274. foo-container$ [make changes in the container]
  275. foo-container$ exit
  276. $ docker commit --run='{"Cmd": ["ls"]}' [container-id] me/bar
  277. ...
  278. The me/bar image will now have port 22 exposed, MYVAR env var set to 'foobar', and its default command will be ["ls"].
  279. 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.
  280. Full --run example
  281. ..................
  282. The ``--run`` JSON hash changes the ``Config`` section when running ``docker inspect CONTAINERID``
  283. or ``config`` when running ``docker inspect IMAGEID``. Existing configuration key-values that are
  284. not overridden in the JSON hash will be merged in.
  285. (Multiline is okay within a single quote ``'``)
  286. .. code-block:: bash
  287. $ sudo docker commit --run='
  288. {
  289. "Entrypoint" : null,
  290. "Privileged" : false,
  291. "User" : "",
  292. "VolumesFrom" : "",
  293. "Cmd" : ["cat", "-e", "/etc/resolv.conf"],
  294. "Dns" : ["8.8.8.8", "8.8.4.4"],
  295. "DnsSearch" : ["example.com"],
  296. "MemorySwap" : 0,
  297. "AttachStdin" : false,
  298. "AttachStderr" : false,
  299. "CpuShares" : 0,
  300. "OpenStdin" : false,
  301. "Volumes" : null,
  302. "Hostname" : "122612f45831",
  303. "PortSpecs" : ["22", "80", "443"],
  304. "Image" : "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
  305. "Tty" : false,
  306. "Env" : [
  307. "HOME=/",
  308. "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  309. ],
  310. "StdinOnce" : false,
  311. "Domainname" : "",
  312. "WorkingDir" : "/",
  313. "NetworkDisabled" : false,
  314. "Memory" : 0,
  315. "AttachStdout" : false
  316. }' $CONTAINER_ID
  317. .. _cli_cp:
  318. ``cp``
  319. ------
  320. ::
  321. Usage: docker cp CONTAINER:PATH HOSTPATH
  322. Copy files/folders from the containers filesystem to the host
  323. path. Paths are relative to the root of the filesystem.
  324. .. code-block:: bash
  325. $ sudo docker cp 7bb0e258aefe:/etc/debian_version .
  326. $ sudo docker cp blue_frog:/etc/hosts .
  327. .. _cli_diff:
  328. ``diff``
  329. --------
  330. ::
  331. Usage: docker diff CONTAINER
  332. List the changed files and directories in a container's filesystem
  333. There are 3 events that are listed in the 'diff':
  334. 1. ```A``` - Add
  335. 2. ```D``` - Delete
  336. 3. ```C``` - Change
  337. For example:
  338. .. code-block:: bash
  339. $ sudo docker diff 7bb0e258aefe
  340. C /dev
  341. A /dev/kmsg
  342. C /etc
  343. A /etc/mtab
  344. A /go
  345. A /go/src
  346. A /go/src/github.com
  347. A /go/src/github.com/dotcloud
  348. A /go/src/github.com/dotcloud/docker
  349. A /go/src/github.com/dotcloud/docker/.git
  350. ....
  351. .. _cli_events:
  352. ``events``
  353. ----------
  354. ::
  355. Usage: docker events
  356. Get real time events from the server
  357. --since="": Show previously created events and then stream.
  358. (either seconds since epoch, or date string as below)
  359. .. _cli_events_example:
  360. Examples
  361. ~~~~~~~~
  362. You'll need two shells for this example.
  363. Shell 1: Listening for events
  364. .............................
  365. .. code-block:: bash
  366. $ sudo docker events
  367. Shell 2: Start and Stop a Container
  368. ...................................
  369. .. code-block:: bash
  370. $ sudo docker start 4386fb97867d
  371. $ sudo docker stop 4386fb97867d
  372. Shell 1: (Again .. now showing events)
  373. ......................................
  374. .. code-block:: bash
  375. [2013-09-03 15:49:26 +0200 CEST] 4386fb97867d: (from 12de384bfb10) start
  376. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
  377. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
  378. Show events in the past from a specified time
  379. .............................................
  380. .. code-block:: bash
  381. $ sudo docker events --since 1378216169
  382. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
  383. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
  384. $ sudo docker events --since '2013-09-03'
  385. [2013-09-03 15:49:26 +0200 CEST] 4386fb97867d: (from 12de384bfb10) start
  386. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
  387. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
  388. $ sudo docker events --since '2013-09-03 15:49:29 +0200 CEST'
  389. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
  390. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
  391. .. _cli_export:
  392. ``export``
  393. ----------
  394. ::
  395. Usage: docker export CONTAINER
  396. Export the contents of a filesystem as a tar archive to STDOUT
  397. For example:
  398. .. code-block:: bash
  399. $ sudo docker export red_panda > latest.tar
  400. .. _cli_history:
  401. ``history``
  402. -----------
  403. ::
  404. Usage: docker history [OPTIONS] IMAGE
  405. Show the history of an image
  406. --no-trunc=false: Don't truncate output
  407. -q, --quiet=false: Only show numeric IDs
  408. To see how the ``docker:latest`` image was built:
  409. .. code-block:: bash
  410. $ docker history docker
  411. IMAGE CREATED CREATED BY SIZE
  412. 3e23a5875458790b7a806f95f7ec0d0b2a5c1659bfc899c89f939f6d5b8f7094 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B
  413. 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
  414. 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
  415. 4b137612be55ca69776c7f30c2d2dd0aa2e7d72059820abf3e25b629f887a084 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB
  416. 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
  417. 511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158 9 months ago 0 B
  418. .. _cli_images:
  419. ``images``
  420. ----------
  421. ::
  422. Usage: docker images [OPTIONS] [NAME]
  423. List images
  424. -a, --all=false: Show all images (by default filter out the intermediate images used to build)
  425. --no-trunc=false: Don't truncate output
  426. -q, --quiet=false: Only show numeric IDs
  427. Listing the most recently created images
  428. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  429. .. code-block:: bash
  430. $ sudo docker images | head
  431. REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
  432. <none> <none> 77af4d6b9913 19 hours ago 1.089 GB
  433. committest latest b6fa739cedf5 19 hours ago 1.089 GB
  434. <none> <none> 78a85c484f71 19 hours ago 1.089 GB
  435. docker latest 30557a29d5ab 20 hours ago 1.089 GB
  436. <none> <none> 0124422dd9f9 20 hours ago 1.089 GB
  437. <none> <none> 18ad6fad3402 22 hours ago 1.082 GB
  438. <none> <none> f9f1e26352f0 23 hours ago 1.089 GB
  439. tryout latest 2629d1fa0b81 23 hours ago 131.5 MB
  440. <none> <none> 5ed6274db6ce 24 hours ago 1.089 GB
  441. Listing the full length image IDs
  442. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  443. .. code-block:: bash
  444. $ sudo docker images --no-trunc | head
  445. REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
  446. <none> <none> 77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB
  447. committest latest b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB
  448. <none> <none> 78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB
  449. docker latest 30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB
  450. <none> <none> 0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB
  451. <none> <none> 18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB
  452. <none> <none> f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB
  453. tryout latest 2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB
  454. <none> <none> 5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB
  455. .. _cli_import:
  456. ``import``
  457. ----------
  458. ::
  459. Usage: docker import URL|- [REPOSITORY[:TAG]]
  460. Create an empty filesystem image and import the contents of the tarball
  461. (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then optionally tag it.
  462. At this time, the URL must start with ``http`` and point to a single
  463. file archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a
  464. root filesystem. If you would like to import from a local directory or
  465. archive, you can use the ``-`` parameter to take the data from *stdin*.
  466. Examples
  467. ~~~~~~~~
  468. Import from a remote location
  469. .............................
  470. This will create a new untagged image.
  471. .. code-block:: bash
  472. $ sudo docker import http://example.com/exampleimage.tgz
  473. Import from a local file
  474. ........................
  475. Import to docker via pipe and *stdin*.
  476. .. code-block:: bash
  477. $ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new
  478. Import from a local directory
  479. .............................
  480. .. code-block:: bash
  481. $ sudo tar -c . | docker import - exampleimagedir
  482. Note the ``sudo`` in this example -- you must preserve the ownership of the
  483. files (especially root ownership) during the archiving with tar. If you are not
  484. root (or the sudo command) when you tar, then the ownerships might not get
  485. preserved.
  486. .. _cli_info:
  487. ``info``
  488. --------
  489. ::
  490. Usage: docker info
  491. Display system-wide information.
  492. .. code-block:: bash
  493. $ sudo docker info
  494. Containers: 292
  495. Images: 194
  496. Debug mode (server): false
  497. Debug mode (client): false
  498. Fds: 22
  499. Goroutines: 67
  500. LXC Version: 0.9.0
  501. EventsListeners: 115
  502. Kernel Version: 3.8.0-33-generic
  503. WARNING: No swap limit support
  504. .. _cli_inspect:
  505. ``inspect``
  506. -----------
  507. ::
  508. Usage: docker inspect CONTAINER|IMAGE [CONTAINER|IMAGE...]
  509. Return low-level information on a container/image
  510. -f, --format="": Format the output using the given go template.
  511. By default, this will render all results in a JSON array. If a format
  512. is specified, the given template will be executed for each result.
  513. Go's `text/template <http://golang.org/pkg/text/template/>`_ package
  514. describes all the details of the format.
  515. Examples
  516. ~~~~~~~~
  517. Get an instance's IP Address
  518. ............................
  519. For the most part, you can pick out any field from the JSON in a
  520. fairly straightforward manner.
  521. .. code-block:: bash
  522. $ sudo docker inspect --format='{{.NetworkSettings.IPAddress}}' $INSTANCE_ID
  523. List All Port Bindings
  524. ......................
  525. One can loop over arrays and maps in the results to produce simple
  526. text output:
  527. .. code-block:: bash
  528. $ sudo docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID
  529. Find a Specific Port Mapping
  530. ............................
  531. The ``.Field`` syntax doesn't work when the field name begins with a
  532. number, but the template language's ``index`` function does. The
  533. ``.NetworkSettings.Ports`` section contains a map of the internal port
  534. mappings to a list of external address/port objects, so to grab just
  535. the numeric public port, you use ``index`` to find the specific port
  536. map, and then ``index`` 0 contains first object inside of that. Then
  537. we ask for the ``HostPort`` field to get the public address.
  538. .. code-block:: bash
  539. $ sudo docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID
  540. Get config
  541. ..........
  542. The ``.Field`` syntax doesn't work when the field contains JSON data,
  543. but the template language's custom ``json`` function does. The ``.config``
  544. section contains complex json object, so to grab it as JSON, you use ``json``
  545. to convert config object into JSON
  546. .. code-block:: bash
  547. $ sudo docker inspect --format='{{json .config}}' $INSTANCE_ID
  548. .. _cli_kill:
  549. ``kill``
  550. --------
  551. ::
  552. Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...]
  553. Kill a running container (send SIGKILL, or specified signal)
  554. -s, --signal="KILL": Signal to send to the container
  555. The main process inside the container will be sent SIGKILL, or any signal specified with option ``--signal``.
  556. Known Issues (kill)
  557. ~~~~~~~~~~~~~~~~~~~
  558. * :issue:`197` indicates that ``docker kill`` may leave directories
  559. behind and make it difficult to remove the container.
  560. * :issue:`3844` lxc 1.0.0 beta3 removed ``lcx-kill`` which is used by Docker versions before 0.8.0;
  561. see the issue for a workaround.
  562. .. _cli_load:
  563. ``load``
  564. --------
  565. ::
  566. Usage: docker load
  567. Load an image from a tar archive on STDIN
  568. -i, --input="": Read from a tar archive file, instead of STDIN
  569. Loads a tarred repository from a file or the standard input stream.
  570. Restores both images and tags.
  571. .. code-block:: bash
  572. $ sudo docker images
  573. REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
  574. $ sudo docker load < busybox.tar
  575. $ sudo docker images
  576. REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
  577. busybox latest 769b9341d937 7 weeks ago 2.489 MB
  578. $ sudo docker load --input fedora.tar
  579. $ sudo docker images
  580. REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
  581. busybox latest 769b9341d937 7 weeks ago 2.489 MB
  582. fedora rawhide 0d20aec6529d 7 weeks ago 387 MB
  583. fedora 20 58394af37342 7 weeks ago 385.5 MB
  584. fedora heisenbug 58394af37342 7 weeks ago 385.5 MB
  585. fedora latest 58394af37342 7 weeks ago 385.5 MB
  586. .. _cli_login:
  587. ``login``
  588. ---------
  589. ::
  590. Usage: docker login [OPTIONS] [SERVER]
  591. Register or Login to the docker registry server
  592. -e, --email="": Email
  593. -p, --password="": Password
  594. -u, --username="": Username
  595. If you want to login to a private registry you can
  596. specify this by adding the server name.
  597. example:
  598. docker login localhost:8080
  599. .. _cli_logs:
  600. ``logs``
  601. --------
  602. ::
  603. Usage: docker logs [OPTIONS] CONTAINER
  604. Fetch the logs of a container
  605. -f, --follow=false: Follow log output
  606. The ``docker logs`` command is a convenience which batch-retrieves whatever
  607. logs are present at the time of execution. This does not guarantee execution
  608. order when combined with a ``docker run`` (i.e. your run may not have generated
  609. any logs at the time you execute ``docker logs``).
  610. The ``docker logs --follow`` command combines ``docker logs`` and ``docker attach``:
  611. it will first return all logs from the beginning and then continue streaming
  612. new output from the container's stdout and stderr.
  613. .. _cli_port:
  614. ``port``
  615. --------
  616. ::
  617. Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT
  618. Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
  619. .. _cli_ps:
  620. ``ps``
  621. ------
  622. ::
  623. Usage: docker ps [OPTIONS]
  624. List containers
  625. -a, --all=false: Show all containers. Only running containers are shown by default.
  626. --before="": Show only container created before Id or Name, include non-running ones.
  627. -l, --latest=false: Show only the latest created container, include non-running ones.
  628. -n=-1: Show n last created containers, include non-running ones.
  629. --no-trunc=false: Don't truncate output
  630. -q, --quiet=false: Only display numeric IDs
  631. -s, --size=false: Display sizes, not to be used with -q
  632. --since="": Show only containers created since Id or Name, include non-running ones.
  633. Running ``docker ps`` showing 2 linked containers.
  634. .. code-block:: bash
  635. $ docker ps
  636. CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
  637. 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds webapp
  638. d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db
  639. fd2645e2e2b5 busybox:latest top 10 days ago Ghost insane_ptolemy
  640. 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``.
  641. ``docker ps`` will show only running containers by default. To see all containers: ``docker ps -a``
  642. .. _cli_pull:
  643. ``pull``
  644. --------
  645. ::
  646. Usage: docker pull NAME[:TAG]
  647. Pull an image or a repository from the registry
  648. .. _cli_push:
  649. ``push``
  650. --------
  651. ::
  652. Usage: docker push NAME[:TAG]
  653. Push an image or a repository to the registry
  654. .. _cli_restart:
  655. ``restart``
  656. -----------
  657. ::
  658. Usage: docker restart [OPTIONS] NAME
  659. Restart a running container
  660. -t, --time=10: Number of seconds to try to stop for before killing the container. Once killed it will then be restarted. Default=10
  661. .. _cli_rm:
  662. ``rm``
  663. ------
  664. ::
  665. Usage: docker rm [OPTIONS] CONTAINER
  666. Remove one or more containers
  667. -l, --link="": Remove the link instead of the actual container
  668. -f, --force=false: Force removal of running container
  669. -v, --volumes=false: Remove the volumes associated to the container
  670. Known Issues (rm)
  671. ~~~~~~~~~~~~~~~~~
  672. * :issue:`197` indicates that ``docker kill`` may leave directories
  673. behind and make it difficult to remove the container.
  674. Examples:
  675. ~~~~~~~~~
  676. .. code-block:: bash
  677. $ sudo docker rm /redis
  678. /redis
  679. This will remove the container referenced under the link ``/redis``.
  680. .. code-block:: bash
  681. $ sudo docker rm --link /webapp/redis
  682. /webapp/redis
  683. This will remove the underlying link between ``/webapp`` and the ``/redis`` containers removing all
  684. network communication.
  685. .. code-block:: bash
  686. $ sudo docker rm `docker ps -a -q`
  687. This command will delete all stopped containers. The command ``docker ps -a -q`` will return all
  688. existing container IDs and pass them to the ``rm`` command which will delete them. Any running
  689. containers will not be deleted.
  690. .. _cli_rmi:
  691. ``rmi``
  692. -------
  693. ::
  694. Usage: docker rmi IMAGE [IMAGE...]
  695. Remove one or more images
  696. -f, --force=false: Force
  697. --no-prune=false: Do not delete untagged parents
  698. Removing tagged images
  699. ~~~~~~~~~~~~~~~~~~~~~~
  700. Images can be removed either by their short or long ID's, or their image names.
  701. If an image has more than one name, each of them needs to be removed before the
  702. image is removed.
  703. .. code-block:: bash
  704. $ sudo docker images
  705. REPOSITORY TAG IMAGE ID CREATED SIZE
  706. test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
  707. test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
  708. test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
  709. $ sudo docker rmi fd484f19954f
  710. Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories
  711. 2013/12/11 05:47:16 Error: failed to remove one or more images
  712. $ sudo docker rmi test1
  713. Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
  714. $ sudo docker rmi test2
  715. Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
  716. $ sudo docker images
  717. REPOSITORY TAG IMAGE ID CREATED SIZE
  718. test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
  719. $ sudo docker rmi test
  720. Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
  721. Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
  722. .. _cli_run:
  723. ``run``
  724. -------
  725. ::
  726. Usage: docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...]
  727. Run a command in a new container
  728. -a, --attach=map[]: Attach to stdin, stdout or stderr
  729. -c, --cpu-shares=0: CPU shares (relative weight)
  730. --cidfile="": Write the container ID to the file
  731. -d, --detach=false: Detached mode: Run container in the background, print new container id
  732. -e, --env=[]: Set environment variables
  733. --env-file="": Read in a line delimited file of ENV variables
  734. -h, --hostname="": Container host name
  735. -i, --interactive=false: Keep stdin open even if not attached
  736. --privileged=false: Give extended privileges to this container
  737. -m, --memory="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
  738. -n, --networking=true: Enable networking for this container
  739. -p, --publish=[]: Map a network port to the container
  740. --rm=false: Automatically remove the container when it exits (incompatible with -d)
  741. -t, --tty=false: Allocate a pseudo-tty
  742. -u, --user="": Username or UID
  743. --dns=[]: Set custom dns servers for the container
  744. --dns-search=[]: Set custom DNS search domains for the container
  745. -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.
  746. --volumes-from="": Mount all volumes from the given container(s)
  747. --entrypoint="": Overwrite the default entrypoint set by the image
  748. -w, --workdir="": Working directory inside the container
  749. --lxc-conf=[]: (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
  750. --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode)
  751. --expose=[]: Expose a port from the container without publishing it to your host
  752. --link="": Add link to another container (name:alias)
  753. --name="": Assign the specified name to the container. If no name is specific docker will generate a random name
  754. -P, --publish-all=false: Publish all exposed ports to the host interfaces
  755. The ``docker run`` command first ``creates`` a writeable container layer over
  756. the specified image, and then ``starts`` it using the specified command. That
  757. is, ``docker run`` is equivalent to the API ``/containers/create`` then
  758. ``/containers/(id)/start``.
  759. 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.
  760. The ``docker run`` command can be used in combination with ``docker commit`` to
  761. :ref:`change the command that a container runs <cli_commit_examples>`.
  762. See :ref:`port_redirection` for more detailed information about the ``--expose``,
  763. ``-p``, ``-P`` and ``--link`` parameters, and :ref:`working_with_links_names` for
  764. specific examples using ``--link``.
  765. Known Issues (run --volumes-from)
  766. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  767. * :issue:`2702`: "lxc-start: Permission denied - failed to mount"
  768. could indicate a permissions problem with AppArmor. Please see the
  769. issue for a workaround.
  770. Examples:
  771. ~~~~~~~~~
  772. .. code-block:: bash
  773. $ sudo docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
  774. This will create a container and print ``test`` to the console. The
  775. ``cidfile`` flag makes Docker attempt to create a new file and write the
  776. container ID to it. If the file exists already, Docker will return an
  777. error. Docker will close this file when ``docker run`` exits.
  778. .. code-block:: bash
  779. $ sudo docker run -t -i --rm ubuntu bash
  780. root@bc338942ef20:/# mount -t tmpfs none /mnt
  781. mount: permission denied
  782. This will *not* work, because by default, most potentially dangerous
  783. kernel capabilities are dropped; including ``cap_sys_admin`` (which is
  784. required to mount filesystems). However, the ``--privileged`` flag will
  785. allow it to run:
  786. .. code-block:: bash
  787. $ sudo docker run --privileged ubuntu bash
  788. root@50e3f57e16e6:/# mount -t tmpfs none /mnt
  789. root@50e3f57e16e6:/# df -h
  790. Filesystem Size Used Avail Use% Mounted on
  791. none 1.9G 0 1.9G 0% /mnt
  792. The ``--privileged`` flag gives *all* capabilities to the container,
  793. and it also lifts all the limitations enforced by the ``device``
  794. cgroup controller. In other words, the container can then do almost
  795. everything that the host can do. This flag exists to allow special
  796. use-cases, like running Docker within Docker.
  797. .. code-block:: bash
  798. $ sudo docker run -w /path/to/dir/ -i -t ubuntu pwd
  799. The ``-w`` lets the command being executed inside directory given,
  800. here ``/path/to/dir/``. If the path does not exists it is created inside the
  801. container.
  802. .. code-block:: bash
  803. $ sudo docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd
  804. The ``-v`` flag mounts the current working directory into the container.
  805. The ``-w`` lets the command being executed inside the current
  806. working directory, by changing into the directory to the value
  807. returned by ``pwd``. So this combination executes the command
  808. using the container, but inside the current working directory.
  809. .. code-block:: bash
  810. $ sudo docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
  811. When the host directory of a bind-mounted volume doesn't exist, Docker
  812. will automatically create this directory on the host for you. In the
  813. example above, Docker will create the ``/doesnt/exist`` folder before
  814. starting your container.
  815. .. code-block:: bash
  816. $ sudo docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v ./static-docker:/usr/bin/docker busybox sh
  817. By bind-mounting the docker unix socket and statically linked docker binary
  818. (such as that provided by https://get.docker.io), you give the container
  819. the full access to create and manipulate the host's docker daemon.
  820. .. code-block:: bash
  821. $ sudo docker run -p 127.0.0.1:80:8080 ubuntu bash
  822. This binds port ``8080`` of the container to port ``80`` on ``127.0.0.1`` of the
  823. host machine. :ref:`port_redirection` explains in detail how to manipulate ports
  824. in Docker.
  825. .. code-block:: bash
  826. $ sudo docker run --expose 80 ubuntu bash
  827. This exposes port ``80`` of the container for use within a link without
  828. publishing the port to the host system's interfaces. :ref:`port_redirection`
  829. explains in detail how to manipulate ports in Docker.
  830. .. code-block:: bash
  831. $ sudo docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
  832. This sets environmental variables in the container. For illustration all three
  833. flags are shown here. Where ``-e``, ``--env`` take an environment variable and
  834. value, or if no "=" is provided, then that variable's current value is passed
  835. through (i.e. $MYVAR1 from the host is set to $MYVAR1 in the container). All
  836. three flags, ``-e``, ``--env`` and ``--env-file`` can be repeated.
  837. Regardless of the order of these three flags, the ``--env-file`` are processed
  838. first, and then ``-e``/``--env`` flags. This way, the ``-e`` or ``--env`` will
  839. override variables as needed.
  840. .. code-block:: bash
  841. $ cat ./env.list
  842. TEST_FOO=BAR
  843. $ sudo docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO
  844. TEST_FOO=This is a test
  845. The ``--env-file`` flag takes a filename as an argument and expects each line
  846. to be in the VAR=VAL format, mimicking the argument passed to ``--env``.
  847. Comment lines need only be prefixed with ``#``
  848. An example of a file passed with ``--env-file``
  849. .. code-block:: bash
  850. $ cat ./env.list
  851. TEST_FOO=BAR
  852. # this is a comment
  853. TEST_APP_DEST_HOST=10.10.0.127
  854. TEST_APP_DEST_PORT=8888
  855. # pass through this variable from the caller
  856. TEST_PASSTHROUGH
  857. $ sudo TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env
  858. HOME=/
  859. PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
  860. HOSTNAME=5198e0745561
  861. TEST_FOO=BAR
  862. TEST_APP_DEST_HOST=10.10.0.127
  863. TEST_APP_DEST_PORT=8888
  864. TEST_PASSTHROUGH=howdy
  865. .. code-block:: bash
  866. $ sudo docker run --name console -t -i ubuntu bash
  867. This will create and run a new container with the container name
  868. being ``console``.
  869. .. code-block:: bash
  870. $ sudo docker run --link /redis:redis --name console ubuntu bash
  871. The ``--link`` flag will link the container named ``/redis`` into the
  872. newly created container with the alias ``redis``. The new container
  873. can access the network and environment of the redis container via
  874. environment variables. The ``--name`` flag will assign the name ``console``
  875. to the newly created container.
  876. .. code-block:: bash
  877. $ sudo docker run --volumes-from 777f7dc92da7,ba8c0c54f0f2:ro -i -t ubuntu pwd
  878. The ``--volumes-from`` flag mounts all the defined volumes from the
  879. referenced containers. Containers can be specified by a comma separated
  880. list or by repetitions of the ``--volumes-from`` argument. The container
  881. ID may be optionally suffixed with ``:ro`` or ``:rw`` to mount the volumes in
  882. read-only or read-write mode, respectively. By default, the volumes are mounted
  883. in the same mode (read write or read only) as the reference container.
  884. The ``-a`` flag tells ``docker run`` to bind to the container's stdin, stdout
  885. or stderr. This makes it possible to manipulate the output and input as needed.
  886. .. code-block:: bash
  887. $ sudo echo "test" | docker run -i -a stdin ubuntu cat -
  888. This pipes data into a container and prints the container's ID by attaching
  889. only to the container's stdin.
  890. .. code-block:: bash
  891. $ sudo docker run -a stderr ubuntu echo test
  892. This isn't going to print anything unless there's an error because we've only
  893. attached to the stderr of the container. The container's logs still store
  894. what's been written to stderr and stdout.
  895. .. code-block:: bash
  896. $ sudo cat somefile | docker run -i -a stdin mybuilder dobuild
  897. This is how piping a file into a container could be done for a build.
  898. The container's ID will be printed after the build is done and the build logs
  899. could be retrieved using ``docker logs``. This is useful if you need to pipe
  900. a file or something else into a container and retrieve the container's ID once
  901. the container has finished running.
  902. A complete example
  903. ..................
  904. .. code-block:: bash
  905. $ sudo docker run -d --name static static-web-files sh
  906. $ sudo docker run -d --expose=8098 --name riak riakserver
  907. $ sudo docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver
  908. $ 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
  909. $ sudo docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log
  910. This example shows 5 containers that might be set up to test a web application change:
  911. 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);
  912. 2. Start a pre-prepared ``riakserver`` image, give the container name ``riak`` and expose port ``8098`` to any containers that link to it;
  913. 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``;
  914. 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;
  915. 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.
  916. .. _cli_save:
  917. ``save``
  918. ---------
  919. ::
  920. Usage: docker save IMAGE
  921. Save an image to a tar archive (streamed to stdout by default)
  922. -o, --output="": Write to an file, instead of STDOUT
  923. Produces a tarred repository to the standard output stream.
  924. Contains all parent layers, and all tags + versions, or specified repo:tag.
  925. .. code-block:: bash
  926. $ sudo docker save busybox > busybox.tar
  927. $ ls -sh b.tar
  928. 2.7M b.tar
  929. $ sudo docker save --output busybox.tar busybox
  930. $ ls -sh b.tar
  931. 2.7M b.tar
  932. $ sudo docker save -o fedora-all.tar fedora
  933. $ sudo docker save -o fedora-latest.tar fedora:latest
  934. .. _cli_search:
  935. ``search``
  936. ----------
  937. ::
  938. Usage: docker search TERM
  939. Search the docker index for images
  940. --no-trunc=false: Don't truncate output
  941. -s, --stars=0: Only displays with at least xxx stars
  942. -t, --trusted=false: Only show trusted builds
  943. .. _cli_start:
  944. ``start``
  945. ---------
  946. ::
  947. Usage: docker start [OPTIONS] CONTAINER
  948. Start a stopped container
  949. -a, --attach=false: Attach container's stdout/stderr and forward all signals to the process
  950. -i, --interactive=false: Attach container's stdin
  951. .. _cli_stop:
  952. ``stop``
  953. --------
  954. ::
  955. Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...]
  956. Stop a running container (Send SIGTERM, and then SIGKILL after grace period)
  957. -t, --time=10: Number of seconds to wait for the container to stop before killing it.
  958. The main process inside the container will receive SIGTERM, and after a grace period, SIGKILL
  959. .. _cli_tag:
  960. ``tag``
  961. -------
  962. ::
  963. Usage: docker tag [OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]
  964. Tag an image into a repository
  965. -f, --force=false: Force
  966. .. _cli_top:
  967. ``top``
  968. -------
  969. ::
  970. Usage: docker top CONTAINER [ps OPTIONS]
  971. Lookup the running processes of a container
  972. .. _cli_version:
  973. ``version``
  974. -----------
  975. Show the version of the Docker client, daemon, and latest released version.
  976. .. _cli_wait:
  977. ``wait``
  978. --------
  979. ::
  980. Usage: docker wait [OPTIONS] NAME
  981. Block until a container stops, then print its exit code.