diff --git a/docs/sources/api/docker_remote_api_v1.5.rst b/docs/sources/api/docker_remote_api_v1.5.rst index 2581059b59..9c8fa8c2af 100644 --- a/docs/sources/api/docker_remote_api_v1.5.rst +++ b/docs/sources/api/docker_remote_api_v1.5.rst @@ -28,543 +28,525 @@ List containers .. http:get:: /containers/json - List containers + List containers - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - - **Example response**: + GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":[{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "3176a2479c92", - "Image": "centos:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "fedora:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - } - ] - - :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default - :query limit: Show ``limit`` last created containers, include non-running ones. - :query since: Show only containers created since Id, include non-running ones. - :query before: Show only containers created before Id, include non-running ones. - :query size: 1/True/true or 0/False/false, Show the containers sizes - :statuscode 200: no error - :statuscode 400: bad parameter - :statuscode 500: server error + .. sourcecode:: http + HTTP/1.1 200 OK + Content-Type: application/json + + [ + { + "Id": "8dfafdbc3a40", + "Image": "ubuntu:latest", + "Command": "echo 1", + "Created": 1367854155, + "Status": "Exit 0", + "Ports":[{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], + "SizeRw":12288, + "SizeRootFs":0 + }, + { + "Id": "9cd87474be90", + "Image": "ubuntu:latest", + "Command": "echo 222222", + "Created": 1367854155, + "Status": "Exit 0", + "Ports":[], + "SizeRw":12288, + "SizeRootFs":0 + }, + { + "Id": "3176a2479c92", + "Image": "centos:latest", + "Command": "echo 3333333333333333", + "Created": 1367854154, + "Status": "Exit 0", + "Ports":[], + "SizeRw":12288, + "SizeRootFs":0 + }, + { + "Id": "4cb07b47f9fb", + "Image": "fedora:latest", + "Command": "echo 444444444444444444444444444444444", + "Created": 1367854152, + "Status": "Exit 0", + "Ports":[], + "SizeRw":12288, + "SizeRootFs":0 + } + ] + + :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default + :query limit: Show ``limit`` last created containers, include non-running ones. + :query since: Show only containers created since Id, include non-running ones. + :query before: Show only containers created before Id, include non-running ones. + :query size: 1/True/true or 0/False/false, Show the containers sizes + :statuscode 200: no error + :statuscode 400: bad parameter + :statuscode 500: server error Create a container ****************** .. http:post:: /containers/create - Create a container + Create a container - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /containers/create HTTP/1.1 - Content-Type: application/json + POST /containers/create HTTP/1.1 + Content-Type: application/json - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Privileged": false, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env":null, - "Cmd":[ - "date" - ], - "Dns":null, - "Image":"ubuntu", - "Volumes":{}, - "VolumesFrom":"", - "WorkingDir":"" + { + "Hostname":"", + "User":"", + "Memory":0, + "MemorySwap":0, + "AttachStdin":false, + "AttachStdout":true, + "AttachStderr":true, + "PortSpecs":null, + "Privileged": false, + "Tty":false, + "OpenStdin":false, + "StdinOnce":false, + "Env":null, + "Cmd":[ + "date" + ], + "Dns":null, + "Image":"ubuntu", + "Volumes":{}, + "VolumesFrom":"", + "WorkingDir":"" + } - } - - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 201 OK - Content-Type: application/json + HTTP/1.1 201 OK + Content-Type: application/json - { - "Id":"e90e34656806" - "Warnings":[] - } - - :jsonparam config: the container's configuration - :statuscode 201: no error - :statuscode 404: no such container - :statuscode 406: impossible to attach (container not running) - :statuscode 500: server error + { + "Id":"e90e34656806" + "Warnings":[] + } + :jsonparam config: the container's configuration + :statuscode 201: no error + :statuscode 404: no such container + :statuscode 406: impossible to attach (container not running) + :statuscode 500: server error Inspect a container ******************* .. http:get:: /containers/(id)/json - Return low-level information on the container ``id`` + Return low-level information on the container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /containers/4fa6e0f0c678/json HTTP/1.1 - - **Example response**: + GET /containers/4fa6e0f0c678/json HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json + .. sourcecode:: http - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir":"" + HTTP/1.1 200 OK + Content-Type: application/json - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/dotcloud/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {} - } - - :statuscode 200: no error - :statuscode 404: no such container - :statuscode 500: server error + { + "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", + "Created": "2013-05-07T14:51:42.041847+02:00", + "Path": "date", + "Args": [], + "Config": { + "Hostname": "4fa6e0f0c678", + "User": "", + "Memory": 0, + "MemorySwap": 0, + "AttachStdin": false, + "AttachStdout": true, + "AttachStderr": true, + "PortSpecs": null, + "Tty": false, + "OpenStdin": false, + "StdinOnce": false, + "Env": null, + "Cmd": [ + "date" + ], + "Dns": null, + "Image": "ubuntu", + "Volumes": {}, + "VolumesFrom": "", + "WorkingDir":"" + }, + "State": { + "Running": false, + "Pid": 0, + "ExitCode": 0, + "StartedAt": "2013-05-07T14:51:42.087658+02:01360", + "Ghost": false + }, + "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", + "NetworkSettings": { + "IpAddress": "", + "IpPrefixLen": 0, + "Gateway": "", + "Bridge": "", + "PortMapping": null + }, + "SysInitPath": "/home/kitty/go/src/github.com/dotcloud/docker/bin/docker", + "ResolvConfPath": "/etc/resolv.conf", + "Volumes": {} + } + :statuscode 200: no error + :statuscode 404: no such container + :statuscode 500: server error List processes running inside a container ***************************************** .. http:get:: /containers/(id)/top - List processes running inside the container ``id`` + List processes running inside the container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /containers/4fa6e0f0c678/top HTTP/1.1 + GET /containers/4fa6e0f0c678/top HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "Titles":[ - "USER", - "PID", - "%CPU", - "%MEM", - "VSZ", - "RSS", - "TTY", - "STAT", - "START", - "TIME", - "COMMAND" - ], - "Processes":[ - ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], - ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] - ] - } - - :query ps_args: ps arguments to use (eg. aux) - :statuscode 200: no error - :statuscode 404: no such container - :statuscode 500: server error + { + "Titles":[ + "USER", + "PID", + "%CPU", + "%MEM", + "VSZ", + "RSS", + "TTY", + "STAT", + "START", + "TIME", + "COMMAND" + ], + "Processes":[ + ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], + ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] + ] + } + :query ps_args: ps arguments to use (eg. aux) + :statuscode 200: no error + :statuscode 404: no such container + :statuscode 500: server error Inspect changes on a container's filesystem ******************************************* .. http:get:: /containers/(id)/changes - Inspect changes on container ``id`` 's filesystem + Inspect changes on container ``id`` 's filesystem - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /containers/4fa6e0f0c678/changes HTTP/1.1 + GET /containers/4fa6e0f0c678/changes HTTP/1.1 - - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path":"/dev", - "Kind":0 - }, - { - "Path":"/dev/kmsg", - "Kind":1 - }, - { - "Path":"/test", - "Kind":1 - } - ] + HTTP/1.1 200 OK + Content-Type: application/json - :statuscode 200: no error - :statuscode 404: no such container - :statuscode 500: server error + [ + { + "Path":"/dev", + "Kind":0 + }, + { + "Path":"/dev/kmsg", + "Kind":1 + }, + { + "Path":"/test", + "Kind":1 + } + ] + :statuscode 200: no error + :statuscode 404: no such container + :statuscode 500: server error Export a container ****************** .. http:get:: /containers/(id)/export - Export the contents of container ``id`` + Export the contents of container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /containers/4fa6e0f0c678/export HTTP/1.1 + GET /containers/4fa6e0f0c678/export HTTP/1.1 - - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ STREAM }} + HTTP/1.1 200 OK + Content-Type: application/octet-stream - :statuscode 200: no error - :statuscode 404: no such container - :statuscode 500: server error + {{ STREAM }} + :statuscode 200: no error + :statuscode 404: no such container + :statuscode 500: server error Start a container ***************** .. http:post:: /containers/(id)/start - Start the container ``id`` + Start the container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /containers/(id)/start HTTP/1.1 - Content-Type: application/json + POST /containers/(id)/start HTTP/1.1 + Content-Type: application/json - { - "Binds":["/tmp:/tmp"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}] - } + { + "Binds":["/tmp:/tmp"], + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}] + } - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 204 No Content - Content-Type: text/plain - - :jsonparam hostConfig: the container's host configuration (optional) - :statuscode 204: no error - :statuscode 404: no such container - :statuscode 500: server error + HTTP/1.1 204 No Content + Content-Type: text/plain + :jsonparam hostConfig: the container's host configuration (optional) + :statuscode 204: no error + :statuscode 404: no such container + :statuscode 500: server error Stop a container **************** .. http:post:: /containers/(id)/stop - Stop the container ``id`` + Stop the container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - - **Example response**: + POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 204 OK - - :query t: number of seconds to wait before killing the container - :statuscode 204: no error - :statuscode 404: no such container - :statuscode 500: server error + .. sourcecode:: http + HTTP/1.1 204 OK + + :query t: number of seconds to wait before killing the container + :statuscode 204: no error + :statuscode 404: no such container + :statuscode 500: server error Restart a container ******************* .. http:post:: /containers/(id)/restart - Restart the container ``id`` + Restart the container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - - **Example response**: + POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 204 OK - - :query t: number of seconds to wait before killing the container - :statuscode 204: no error - :statuscode 404: no such container - :statuscode 500: server error + .. sourcecode:: http + HTTP/1.1 204 OK + + :query t: number of seconds to wait before killing the container + :statuscode 204: no error + :statuscode 404: no such container + :statuscode 500: server error Kill a container **************** .. http:post:: /containers/(id)/kill - Kill the container ``id`` + Kill the container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /containers/e90e34656806/kill HTTP/1.1 - - **Example response**: + POST /containers/e90e34656806/kill HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 204 OK - - :statuscode 204: no error - :statuscode 404: no such container - :statuscode 500: server error + .. sourcecode:: http + HTTP/1.1 204 OK + + :statuscode 204: no error + :statuscode 404: no such container + :statuscode 500: server error Attach to a container ********************* .. http:post:: /containers/(id)/attach - Attach to the container ``id`` + Attach to the container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - - **Example response**: + POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream + .. sourcecode:: http - {{ STREAM }} - - :query logs: 1/True/true or 0/False/false, return logs. Default false - :query stream: 1/True/true or 0/False/false, return stream. Default false - :query stdin: 1/True/true or 0/False/false, if stream=true, attach to stdin. Default false - :query stdout: 1/True/true or 0/False/false, if logs=true, return stdout log, if stream=true, attach to stdout. Default false - :query stderr: 1/True/true or 0/False/false, if logs=true, return stderr log, if stream=true, attach to stderr. Default false - :statuscode 200: no error - :statuscode 400: bad parameter - :statuscode 404: no such container - :statuscode 500: server error + HTTP/1.1 200 OK + Content-Type: application/vnd.docker.raw-stream + {{ STREAM }} + + :query logs: 1/True/true or 0/False/false, return logs. Default false + :query stream: 1/True/true or 0/False/false, return stream. Default false + :query stdin: 1/True/true or 0/False/false, if stream=true, attach to stdin. Default false + :query stdout: 1/True/true or 0/False/false, if logs=true, return stdout log, if stream=true, attach to stdout. Default false + :query stderr: 1/True/true or 0/False/false, if logs=true, return stderr log, if stream=true, attach to stderr. Default false + :statuscode 200: no error + :statuscode 400: bad parameter + :statuscode 404: no such container + :statuscode 500: server error Wait a container **************** .. http:post:: /containers/(id)/wait - Block until container ``id`` stops, then returns the exit code + Block until container ``id`` stops, then returns the exit code - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /containers/16253994b7c4/wait HTTP/1.1 - - **Example response**: + POST /containers/16253994b7c4/wait HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json + .. sourcecode:: http - {"StatusCode":0} - - :statuscode 200: no error - :statuscode 404: no such container - :statuscode 500: server error + HTTP/1.1 200 OK + Content-Type: application/json + {"StatusCode":0} + + :statuscode 200: no error + :statuscode 404: no such container + :statuscode 500: server error Remove a container ******************* .. http:delete:: /containers/(id) - Remove the container ``id`` from the filesystem + Remove the container ``id`` from the filesystem - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 + DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 204 OK - - :query v: 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false - :statuscode 204: no error - :statuscode 400: bad parameter - :statuscode 404: no such container - :statuscode 500: server error + HTTP/1.1 204 OK + :query v: 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false + :statuscode 204: no error + :statuscode 400: bad parameter + :statuscode 404: no such container + :statuscode 500: server error Copy files or folders from a container ************************************** .. http:post:: /containers/(id)/copy - Copy files or folders of container ``id`` + Copy files or folders of container ``id`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json + POST /containers/4fa6e0f0c678/copy HTTP/1.1 + Content-Type: application/json - { - "Resource":"test.txt" - } + { + "Resource":"test.txt" + } - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ STREAM }} + HTTP/1.1 200 OK + Content-Type: application/octet-stream - :statuscode 200: no error - :statuscode 404: no such container - :statuscode 500: server error + {{ STREAM }} + :statuscode 200: no error + :statuscode 404: no such container + :statuscode 500: server error 2.2 Images ---------- @@ -574,370 +556,360 @@ List Images .. http:get:: /images/(format) - List images ``format`` could be json or viz (json default) + List images ``format`` could be json or viz (json default) - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /images/json?all=0 HTTP/1.1 + GET /images/json?all=0 HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Repository":"ubuntu", - "Tag":"precise", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - }, - { - "Repository":"ubuntu", - "Tag":"12.04", - "Id":"b750fe79269d", - "Created":1364102658, - "Size":24653, - "VirtualSize":180116135 - } - ] + HTTP/1.1 200 OK + Content-Type: application/json + [ + { + "Repository":"ubuntu", + "Tag":"precise", + "Id":"b750fe79269d", + "Created":1364102658, + "Size":24653, + "VirtualSize":180116135 + }, + { + "Repository":"ubuntu", + "Tag":"12.04", + "Id":"b750fe79269d", + "Created":1364102658, + "Size":24653, + "VirtualSize":180116135 + } + ] - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /images/viz HTTP/1.1 + GET /images/viz HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: text/plain + HTTP/1.1 200 OK + Content-Type: text/plain - digraph docker { - "d82cbacda43a" -> "074be284591f" - "1496068ca813" -> "08306dc45919" - "08306dc45919" -> "0e7893146ac2" - "b750fe79269d" -> "1496068ca813" - base -> "27cf78414709" [style=invis] - "f71189fff3de" -> "9a33b36209ed" - "27cf78414709" -> "b750fe79269d" - "0e7893146ac2" -> "d6434d954665" - "d6434d954665" -> "d82cbacda43a" - base -> "e9aa60c60128" [style=invis] - "074be284591f" -> "f71189fff3de" - "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; - base [style=invisible] - } - - :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default - :statuscode 200: no error - :statuscode 400: bad parameter - :statuscode 500: server error + digraph docker { + "d82cbacda43a" -> "074be284591f" + "1496068ca813" -> "08306dc45919" + "08306dc45919" -> "0e7893146ac2" + "b750fe79269d" -> "1496068ca813" + base -> "27cf78414709" [style=invis] + "f71189fff3de" -> "9a33b36209ed" + "27cf78414709" -> "b750fe79269d" + "0e7893146ac2" -> "d6434d954665" + "d6434d954665" -> "d82cbacda43a" + base -> "e9aa60c60128" [style=invis] + "074be284591f" -> "f71189fff3de" + "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; + "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; + "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"]; + base [style=invisible] + } + :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default + :statuscode 200: no error + :statuscode 400: bad parameter + :statuscode 500: server error Create an image *************** .. http:post:: /images/create - Create an image, either by pull it from the registry or by importing it + Create an image, either by pull it from the registry or by importing it - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /images/create?fromImage=ubuntu HTTP/1.1 + POST /images/create?fromImage=ubuntu HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - {"status":"Pulling..."} - {"status":"Pulling", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... + {"status":"Pulling..."} + {"status":"Pulling", "progress":"1/? (n/a)"} + {"error":"Invalid..."} + ... - When using this endpoint to pull an image from the registry, - the ``X-Registry-Auth`` header can be used to include a - base64-encoded AuthConfig object. - - :query fromImage: name of the image to pull - :query fromSrc: source to import, - means stdin - :query repo: repository - :query tag: tag - :query registry: the registry to pull from - :statuscode 200: no error - :statuscode 500: server error + When using this endpoint to pull an image from the registry, + the ``X-Registry-Auth`` header can be used to include a + base64-encoded AuthConfig object. + :query fromImage: name of the image to pull + :query fromSrc: source to import, - means stdin + :query repo: repository + :query tag: tag + :query registry: the registry to pull from + :statuscode 200: no error + :statuscode 500: server error Insert a file in an image ************************* .. http:post:: /images/(name)/insert - Insert a file from ``url`` in the image ``name`` at ``path`` + Insert a file from ``url`` in the image ``name`` at ``path`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 + POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... - - :statuscode 200: no error - :statuscode 500: server error + {"status":"Inserting..."} + {"status":"Inserting", "progress":"1/? (n/a)"} + {"error":"Invalid..."} + ... + :statuscode 200: no error + :statuscode 500: server error Inspect an image **************** .. http:get:: /images/(name)/json - Return low-level information on the image ``name`` + Return low-level information on the image ``name`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /images/centos/json HTTP/1.1 + GET /images/centos/json HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "parent":"27cf784147099545", - "created":"2013-03-23T22:24:18.818426-07:00", - "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "container_config": - { - "Hostname":"", - "User":"", - "Memory":0, - "MemorySwap":0, - "AttachStdin":false, - "AttachStdout":false, - "AttachStderr":false, - "PortSpecs":null, - "Tty":true, - "OpenStdin":true, - "StdinOnce":false, - "Env":null, - "Cmd": ["/bin/bash"] - ,"Dns":null, - "Image":"centos", - "Volumes":null, - "VolumesFrom":"", - "WorkingDir":"" - }, - "Size": 6824592 - } - - :statuscode 200: no error - :statuscode 404: no such image - :statuscode 500: server error + { + "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", + "parent":"27cf784147099545", + "created":"2013-03-23T22:24:18.818426-07:00", + "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", + "container_config": + { + "Hostname":"", + "User":"", + "Memory":0, + "MemorySwap":0, + "AttachStdin":false, + "AttachStdout":false, + "AttachStderr":false, + "PortSpecs":null, + "Tty":true, + "OpenStdin":true, + "StdinOnce":false, + "Env":null, + "Cmd": ["/bin/bash"] + ,"Dns":null, + "Image":"centos", + "Volumes":null, + "VolumesFrom":"", + "WorkingDir":"" + }, + "Size": 6824592 + } + :statuscode 200: no error + :statuscode 404: no such image + :statuscode 500: server error Get the history of an image *************************** .. http:get:: /images/(name)/history - Return the history of the image ``name`` + Return the history of the image ``name`` - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /images/fedora/history HTTP/1.1 + GET /images/fedora/history HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - [ - { - "Id":"b750fe79269d", - "Created":1364102658, - "CreatedBy":"/bin/bash" - }, - { - "Id":"27cf78414709", - "Created":1364068391, - "CreatedBy":"" - } - ] - - :statuscode 200: no error - :statuscode 404: no such image - :statuscode 500: server error + [ + { + "Id":"b750fe79269d", + "Created":1364102658, + "CreatedBy":"/bin/bash" + }, + { + "Id":"27cf78414709", + "Created":1364068391, + "CreatedBy":"" + } + ] + :statuscode 200: no error + :statuscode 404: no such image + :statuscode 500: server error Push an image on the registry ***************************** .. http:post:: /images/(name)/push - Push the image ``name`` on the registry + Push the image ``name`` on the registry - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /images/test/push HTTP/1.1 + POST /images/test/push HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json - {"status":"Pushing..."} - {"status":"Pushing", "progress":"1/? (n/a)"} - {"error":"Invalid..."} - ... + {"status":"Pushing..."} + {"status":"Pushing", "progress":"1/? (n/a)"} + {"error":"Invalid..."} + ... - The ``X-Registry-Auth`` header can be used to include a - base64-encoded AuthConfig object. - - :query registry: the registry you wan to push, optional - :statuscode 200: no error - :statuscode 404: no such image - :statuscode 500: server error + The ``X-Registry-Auth`` header can be used to include a + base64-encoded AuthConfig object. + :query registry: the registry you wan to push, optional + :statuscode 200: no error + :statuscode 404: no such image + :statuscode 500: server error Tag an image into a repository ****************************** .. http:post:: /images/(name)/tag - Tag the image ``name`` into a repository + Tag the image ``name`` into a repository - **Example request**: + **Example request**: - .. sourcecode:: http - - POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1 + .. sourcecode:: http - **Example response**: + POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 200 OK + .. sourcecode:: http - :query repo: The repository to tag in - :query force: 1/True/true or 0/False/false, default false - :statuscode 200: no error - :statuscode 400: bad parameter - :statuscode 404: no such image - :statuscode 409: conflict - :statuscode 500: server error + HTTP/1.1 200 OK + :query repo: The repository to tag in + :query force: 1/True/true or 0/False/false, default false + :statuscode 200: no error + :statuscode 400: bad parameter + :statuscode 404: no such image + :statuscode 409: conflict + :statuscode 500: server error Remove an image *************** .. http:delete:: /images/(name) - Remove the image ``name`` from the filesystem - - **Example request**: + Remove the image ``name`` from the filesystem - .. sourcecode:: http + **Example request**: - DELETE /images/test HTTP/1.1 + .. sourcecode:: http - **Example response**: + DELETE /images/test HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 200 OK - Content-type: application/json + .. sourcecode:: http - [ - {"Untagged":"3e2f21a89f"}, - {"Deleted":"3e2f21a89f"}, - {"Deleted":"53b4f83ac9"} - ] + HTTP/1.1 200 OK + Content-type: application/json - :statuscode 200: no error - :statuscode 404: no such image - :statuscode 409: conflict - :statuscode 500: server error + [ + {"Untagged":"3e2f21a89f"}, + {"Deleted":"3e2f21a89f"}, + {"Deleted":"53b4f83ac9"} + ] + :statuscode 200: no error + :statuscode 404: no such image + :statuscode 409: conflict + :statuscode 500: server error Search images ************* .. http:get:: /images/search - Search for an image in the docker index - - **Example request**: + Search for an image in the docker index - .. sourcecode:: http + **Example request**: - GET /images/search?term=sshd HTTP/1.1 + .. sourcecode:: http - **Example response**: + GET /images/search?term=sshd HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Name":"cespare/sshd", - "Description":"" - }, - { - "Name":"johnfuller/sshd", - "Description":"" - }, - { - "Name":"dhrp/mongodb-sshd", - "Description":"" - } - ] + .. sourcecode:: http - :query term: term to search - :statuscode 200: no error - :statuscode 500: server error + HTTP/1.1 200 OK + Content-Type: application/json + [ + { + "Name":"cespare/sshd", + "Description":"" + }, + { + "Name":"johnfuller/sshd", + "Description":"" + }, + { + "Name":"dhrp/mongodb-sshd", + "Description":"" + } + ] + + :query term: term to search + :statuscode 200: no error + :statuscode 500: server error 2.3 Misc -------- @@ -947,199 +919,192 @@ Build an image from Dockerfile via stdin .. http:post:: /build - Build an image from Dockerfile via stdin + Build an image from Dockerfile via stdin - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /build HTTP/1.1 + POST /build HTTP/1.1 - {{ STREAM }} + {{ STREAM }} - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK + HTTP/1.1 200 OK - {{ STREAM }} + {{ STREAM }} + The stream must be a tar archive compressed with one of the following algorithms: + identity (no compression), gzip, bzip2, xz. The archive must include a file called + `Dockerfile` at its root. It may include any number of other files, which will be + accessible in the build context (See the ADD build command). - The stream must be a tar archive compressed with one of the following algorithms: - identity (no compression), gzip, bzip2, xz. The archive must include a file called - `Dockerfile` at its root. It may include any number of other files, which will be - accessible in the build context (See the ADD build command). - - The Content-type header should be set to "application/tar". - - :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success - :query q: suppress verbose build output - :query nocache: do not use the cache when building the image - :query rm: remove intermediate containers after a successful build - :statuscode 200: no error - :statuscode 500: server error + The Content-type header should be set to "application/tar". + :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success + :query q: suppress verbose build output + :query nocache: do not use the cache when building the image + :query rm: remove intermediate containers after a successful build + :statuscode 200: no error + :statuscode 500: server error Check auth configuration ************************ .. http:post:: /auth - Get the default username and email + Get the default username and email - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /auth HTTP/1.1 - Content-Type: application/json + POST /auth HTTP/1.1 + Content-Type: application/json - { - "username":"hannibal", - "password:"xxxx", - "email":"hannibal@a-team.com", - "serveraddress":"https://index.docker.io/v1/" - } + { + "username":"hannibal", + "password:"xxxx", + "email":"hannibal@a-team.com", + "serveraddress":"https://index.docker.io/v1/" + } - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - - :statuscode 200: no error - :statuscode 204: no error - :statuscode 500: server error + HTTP/1.1 200 OK + :statuscode 200: no error + :statuscode 204: no error + :statuscode 500: server error Display system-wide information ******************************* .. http:get:: /info - Display system-wide information - - **Example request**: + Display system-wide information - .. sourcecode:: http + **Example request**: - GET /info HTTP/1.1 + .. sourcecode:: http - **Example response**: + GET /info HTTP/1.1 - .. sourcecode:: http + **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json + .. sourcecode:: http - { - "Containers":11, - "Images":16, - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true - } + HTTP/1.1 200 OK + Content-Type: application/json - :statuscode 200: no error - :statuscode 500: server error + { + "Containers":11, + "Images":16, + "Debug":false, + "NFd": 11, + "NGoroutines":21, + "MemoryLimit":true, + "SwapLimit":false, + "IPv4Forwarding":true + } + :statuscode 200: no error + :statuscode 500: server error Show the docker version information *********************************** .. http:get:: /version - Show the docker version information + Show the docker version information - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - GET /version HTTP/1.1 + GET /version HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "Version":"0.2.2", - "GitCommit":"5a2a5cc+CHANGES", - "GoVersion":"go1.0.3" - } - - :statuscode 200: no error - :statuscode 500: server error + { + "Version":"0.2.2", + "GitCommit":"5a2a5cc+CHANGES", + "GoVersion":"go1.0.3" + } + :statuscode 200: no error + :statuscode 500: server error Create a new image from a container's changes ********************************************* .. http:post:: /commit - Create a new image from a container's changes + Create a new image from a container's changes - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 + POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 201 OK - Content-Type: application/vnd.docker.raw-stream + HTTP/1.1 201 OK + Content-Type: application/vnd.docker.raw-stream - {"Id":"596069db4bf5"} - - :query container: source container - :query repo: repository - :query tag: tag - :query m: commit message - :query author: author (eg. "John Hannibal Smith ") - :query run: config automatically applied when the image is run. (ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]}) - :statuscode 201: no error - :statuscode 404: no such container - :statuscode 500: server error + {"Id":"596069db4bf5"} + :query container: source container + :query repo: repository + :query tag: tag + :query m: commit message + :query author: author (eg. "John Hannibal Smith ") + :query run: config automatically applied when the image is run. (ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]}) + :statuscode 201: no error + :statuscode 404: no such container + :statuscode 500: server error Monitor Docker's events *********************** .. http:get:: /events - Get events from docker, either in real time via streaming, or via polling (using `since`) + Get events from docker, either in real time via streaming, or via polling (using `since`) - **Example request**: + **Example request**: - .. sourcecode:: http + .. sourcecode:: http - POST /events?since=1374067924 + POST /events?since=1374067924 - **Example response**: + **Example response**: - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - {"status":"create","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924} - {"status":"start","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924} - {"status":"stop","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067966} - {"status":"destroy","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067970} - - :query since: timestamp used for polling - :statuscode 200: no error - :statuscode 500: server error + {"status":"create","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924} + {"status":"start","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924} + {"status":"stop","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067966} + {"status":"destroy","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067970} + :query since: timestamp used for polling + :statuscode 200: no error + :statuscode 500: server error 3. Going further ================ @@ -1151,14 +1116,13 @@ Here are the steps of 'docker run' : * Create the container * If the status code is 404, it means the image doesn't exists: - * Try to pull it - * Then retry to create the container + * Try to pull it + * Then retry to create the container * Start the container * If you are not in detached mode: - * Attach to the container, using logs=1 (to have stdout and stderr from the container's start) and stream=1 + * Attach to the container, using logs=1 (to have stdout and stderr from the container's start) and stream=1 * If in detached mode or only stdin is attached: - * Display the container's id - + * Display the container's id 3.2 Hijacking ------------- @@ -1172,5 +1136,4 @@ To enable cross origin requests to the remote api add the flag "-api-enable-cors .. code-block:: bash - docker -d -H="192.168.1.9:4243" -api-enable-cors - + docker -d -H="192.168.1.9:4243" -api-enable-cors