github.com/chenchun/docker@v1.3.2-0.20150629222414-20467faf132b/docs/reference/api/docker_remote_api_v1.19.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "Remote API v1.19"
     4  description = "API Documentation for Docker"
     5  keywords = ["API, Docker, rcli, REST,  documentation"]
     6  [menu.main]
     7  parent = "smn_remoteapi"
     8  weight = 2
     9  +++
    10  <![end-metadata]-->
    11  
    12  # Docker Remote API v1.19
    13  
    14  ## 1. Brief introduction
    15  
    16   - The Remote API has replaced `rcli`.
    17   - The daemon listens on `unix:///var/run/docker.sock` but you can
    18     [Bind Docker to another host/port or a Unix socket](
    19     /articles/basics/#bind-docker-to-another-hostport-or-a-unix-socket).
    20   - The API tends to be REST. However, for some complex commands, like `attach`
    21     or `pull`, the HTTP connection is hijacked to transport `stdout`,
    22     `stdin` and `stderr`.
    23   - When the client API version is newer than the daemon's, these calls return an HTTP
    24     `400 Bad Request` error message.
    25  
    26  # 2. Endpoints
    27  
    28  ## 2.1 Containers
    29  
    30  ### List containers
    31  
    32  `GET /containers/json`
    33  
    34  List containers
    35  
    36  **Example request**:
    37  
    38      GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
    39  
    40  **Example response**:
    41  
    42      HTTP/1.1 200 OK
    43      Content-Type: application/json
    44  
    45      [
    46           {
    47                   "Id": "8dfafdbc3a40",
    48                   "Image": "ubuntu:latest",
    49                   "Command": "echo 1",
    50                   "Created": 1367854155,
    51                   "Status": "Exit 0",
    52                   "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
    53                   "SizeRw": 12288,
    54                   "SizeRootFs": 0
    55           },
    56           {
    57                   "Id": "9cd87474be90",
    58                   "Image": "ubuntu:latest",
    59                   "Command": "echo 222222",
    60                   "Created": 1367854155,
    61                   "Status": "Exit 0",
    62                   "Ports": [],
    63                   "SizeRw": 12288,
    64                   "SizeRootFs": 0
    65           },
    66           {
    67                   "Id": "3176a2479c92",
    68                   "Image": "ubuntu:latest",
    69                   "Command": "echo 3333333333333333",
    70                   "Created": 1367854154,
    71                   "Status": "Exit 0",
    72                   "Ports":[],
    73                   "SizeRw":12288,
    74                   "SizeRootFs":0
    75           },
    76           {
    77                   "Id": "4cb07b47f9fb",
    78                   "Image": "ubuntu:latest",
    79                   "Command": "echo 444444444444444444444444444444444",
    80                   "Created": 1367854152,
    81                   "Status": "Exit 0",
    82                   "Ports": [],
    83                   "SizeRw": 12288,
    84                   "SizeRootFs": 0
    85           }
    86      ]
    87  
    88  Query Parameters:
    89  
    90  -   **all** – 1/True/true or 0/False/false, Show all containers.
    91          Only running containers are shown by default (i.e., this defaults to false)
    92  -   **limit** – Show `limit` last created
    93          containers, include non-running ones.
    94  -   **since** – Show only containers created since Id, include
    95          non-running ones.
    96  -   **before** – Show only containers created before Id, include
    97          non-running ones.
    98  -   **size** – 1/True/true or 0/False/false, Show the containers
    99          sizes
   100  -   **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters:
   101    -   `exited=<int>`; -- containers with exit code of  `<int>` ;
   102    -   `status=`(`restarting`|`running`|`paused`|`exited`)
   103    -   `label=key` or `key=value` of a container label
   104  
   105  Status Codes:
   106  
   107  -   **200** – no error
   108  -   **400** – bad parameter
   109  -   **500** – server error
   110  
   111  ### Create a container
   112  
   113  `POST /containers/create`
   114  
   115  Create a container
   116  
   117  **Example request**:
   118  
   119      POST /containers/create HTTP/1.1
   120      Content-Type: application/json
   121  
   122      {
   123             "Hostname": "",
   124             "Domainname": "",
   125             "User": "",
   126             "AttachStdin": false,
   127             "AttachStdout": true,
   128             "AttachStderr": true,
   129             "Tty": false,
   130             "OpenStdin": false,
   131             "StdinOnce": false,
   132             "Env": null,
   133             "Cmd": [
   134                     "date"
   135             ],
   136             "Entrypoint": "",
   137             "Image": "ubuntu",
   138             "Labels": {
   139                     "com.example.vendor": "Acme",
   140                     "com.example.license": "GPL",
   141                     "com.example.version": "1.0"
   142             },
   143             "Volumes": {
   144                     "/tmp": {}
   145             },
   146             "WorkingDir": "",
   147             "NetworkDisabled": false,
   148             "MacAddress": "12:34:56:78:9a:bc",
   149             "ExposedPorts": {
   150                     "22/tcp": {}
   151             },
   152             "HostConfig": {
   153               "Binds": ["/tmp:/tmp"],
   154               "Links": ["redis3:redis"],
   155               "LxcConf": {"lxc.utsname":"docker"},
   156               "Memory": 0,
   157               "MemorySwap": 0,
   158               "CpuShares": 512,
   159               "CpuPeriod": 100000,
   160               "CpusetCpus": "0,1",
   161               "CpusetMems": "0,1",
   162               "BlkioWeight": 300,
   163               "OomKillDisable": false,
   164               "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
   165               "PublishAllPorts": false,
   166               "Privileged": false,
   167               "ReadonlyRootfs": false,
   168               "Dns": ["8.8.8.8"],
   169               "DnsSearch": [""],
   170               "ExtraHosts": null,
   171               "VolumesFrom": ["parent", "other:ro"],
   172               "CapAdd": ["NET_ADMIN"],
   173               "CapDrop": ["MKNOD"],
   174               "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },
   175               "NetworkMode": "bridge",
   176               "Devices": [],
   177               "Ulimits": [{}],
   178               "LogConfig": { "Type": "json-file", "Config": {} },
   179               "SecurityOpt": [""],
   180               "CgroupParent": ""
   181            }
   182        }
   183  
   184  **Example response**:
   185  
   186        HTTP/1.1 201 Created
   187        Content-Type: application/json
   188  
   189        {
   190             "Id":"e90e34656806"
   191             "Warnings":[]
   192        }
   193  
   194  Json Parameters:
   195  
   196  -   **Hostname** - A string value containing the hostname to use for the
   197        container.
   198  -   **Domainname** - A string value containing the domain name to use
   199        for the container.
   200  -   **User** - A string value specifying the user inside the container.
   201  -   **Memory** - Memory limit in bytes.
   202  -   **MemorySwap**- Total memory limit (memory + swap); set `-1` to disable swap
   203        You must use this with `memory` and make the swap value larger than `memory`.
   204  -   **CpuShares** - An integer value containing the container's CPU Shares
   205        (ie. the relative weight vs other containers).
   206  -   **CpuPeriod** - The length of a CPU period in microseconds.
   207  -   **Cpuset** - Deprecated please don't use. Use `CpusetCpus` instead. 
   208  -   **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use.
   209  -   **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
   210  -   **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000.
   211  -   **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not.
   212  -   **AttachStdin** - Boolean value, attaches to `stdin`.
   213  -   **AttachStdout** - Boolean value, attaches to `stdout`.
   214  -   **AttachStderr** - Boolean value, attaches to `stderr`.
   215  -   **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed.
   216  -   **OpenStdin** - Boolean value, opens stdin,
   217  -   **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
   218  -   **Env** - A list of environment variables in the form of `VAR=value`
   219  -   **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
   220  -   **Cmd** - Command to run specified as a string or an array of strings.
   221  -   **Entrypoint** - Set the entry point for the container as a string or an array
   222        of strings.
   223  -   **Image** - A string specifying the image name to use for the container.
   224  -   **Volumes** – An object mapping mount point paths (strings) inside the
   225        container to empty objects.
   226  -   **WorkingDir** - A string specifying the working directory for commands to
   227        run in.
   228  -   **NetworkDisabled** - Boolean value, when true disables networking for the
   229        container
   230  -   **ExposedPorts** - An object mapping ports to an empty object in the form of:
   231        `"ExposedPorts": { "<port>/<tcp|udp>: {}" }`
   232  -   **HostConfig**
   233      -   **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms:
   234             + `container_path` to create a new volume for the container
   235             + `host_path:container_path` to bind-mount a host path into the container
   236             + `host_path:container_path:ro` to make the bind-mount read-only inside the container.
   237      -   **Links** - A list of links for the container. Each link entry should be
   238            in the form of `container_name:alias`.
   239      -   **LxcConf** - LXC specific configurations. These configurations only
   240            work when using the `lxc` execution driver.
   241      -   **PortBindings** - A map of exposed container ports and the host port they
   242            should map to. A JSON object in the form
   243            `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
   244            Take note that `port` is specified as a string and not an integer value.
   245      -   **PublishAllPorts** - Allocates a random host port for all of a container's
   246            exposed ports. Specified as a boolean value.
   247      -   **Privileged** - Gives the container full access to the host. Specified as
   248            a boolean value.
   249      -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
   250            Specified as a boolean value.
   251      -   **Dns** - A list of DNS servers for the container to use.
   252      -   **DnsSearch** - A list of DNS search domains
   253      -   **ExtraHosts** - A list of hostnames/IP mappings to add to the
   254          container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`.
   255      -   **VolumesFrom** - A list of volumes to inherit from another container.
   256            Specified in the form `<container name>[:<ro|rw>]`
   257      -   **CapAdd** - A list of kernel capabilities to add to the container.
   258      -   **Capdrop** - A list of kernel capabilities to drop from the container.
   259      -   **RestartPolicy** – The behavior to apply when the container exits.  The
   260              value is an object with a `Name` property of either `"always"` to
   261              always restart or `"on-failure"` to restart only when the container
   262              exit code is non-zero.  If `on-failure` is used, `MaximumRetryCount`
   263              controls the number of times to retry before giving up.
   264              The default is not to restart. (optional)
   265              An ever increasing delay (double the previous delay, starting at 100mS)
   266              is added before each restart to prevent flooding the server.
   267      -   **NetworkMode** - Sets the networking mode for the container. Supported
   268            values are: `bridge`, `host`, and `container:<name|id>`
   269      -   **Devices** - A list of devices to add to the container specified as a JSON object in the
   270        form
   271            `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`
   272      -   **Ulimits** - A list of ulimits to set in the container, specified as
   273            `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example:
   274            `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard", 2048 }}`
   275      -   **SecurityOpt**: A list of string values to customize labels for MLS
   276          systems, such as SELinux.
   277      -   **LogConfig** - Log configuration for the container, specified as a JSON object in the form
   278            `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`.
   279            Available types: `json-file`, `syslog`, `journald`, `none`.
   280  	      `syslog` available options are: `address`.
   281      -   **CgroupParent** - Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist.
   282  
   283  Query Parameters:
   284  
   285  -   **name** – Assign the specified name to the container. Must
   286      match `/?[a-zA-Z0-9_-]+`.
   287  
   288  Status Codes:
   289  
   290  -   **201** – no error
   291  -   **404** – no such container
   292  -   **406** – impossible to attach (container not running)
   293  -   **500** – server error
   294  
   295  ### Inspect a container
   296  
   297  `GET /containers/(id)/json`
   298  
   299  Return low-level information on the container `id`
   300  
   301  
   302  **Example request**:
   303  
   304        GET /containers/4fa6e0f0c678/json HTTP/1.1
   305  
   306  **Example response**:
   307  
   308      HTTP/1.1 200 OK
   309      Content-Type: application/json
   310  
   311      {
   312  		"AppArmorProfile": "",
   313  		"Args": [
   314  			"-c",
   315  			"exit 9"
   316  		],
   317  		"Config": {
   318  			"AttachStderr": true,
   319  			"AttachStdin": false,
   320  			"AttachStdout": true,
   321  			"Cmd": [
   322  				"/bin/sh",
   323  				"-c",
   324  				"exit 9"
   325  			],
   326  			"Domainname": "",
   327  			"Entrypoint": null,
   328  			"Env": [
   329  				"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
   330  			],
   331  			"ExposedPorts": null,
   332  			"Hostname": "ba033ac44011",
   333  			"Image": "ubuntu",
   334  			"Labels": {
   335  				"com.example.vendor": "Acme",
   336  				"com.example.license": "GPL",
   337  				"com.example.version": "1.0"
   338  			},
   339  			"MacAddress": "",
   340  			"NetworkDisabled": false,
   341  			"OnBuild": null,
   342  			"OpenStdin": false,
   343  			"PortSpecs": null,
   344  			"StdinOnce": false,
   345  			"Tty": false,
   346  			"User": "",
   347  			"Volumes": null,
   348  			"WorkingDir": ""
   349  		},
   350  		"Created": "2015-01-06T15:47:31.485331387Z",
   351  		"Driver": "devicemapper",
   352  		"ExecDriver": "native-0.2",
   353  		"ExecIDs": null,
   354  		"HostConfig": {
   355  			"Binds": null,
   356  			"BlkioWeight": 0,
   357  			"CapAdd": null,
   358  			"CapDrop": null,
   359  			"ContainerIDFile": "",
   360  			"CpusetCpus": "",
   361  			"CpusetMems": "",
   362  			"CpuShares": 0,
   363  			"CpuPeriod": 100000,
   364  			"Devices": [],
   365  			"Dns": null,
   366  			"DnsSearch": null,
   367  			"ExtraHosts": null,
   368  			"IpcMode": "",
   369  			"Links": null,
   370  			"LxcConf": [],
   371  			"Memory": 0,
   372  			"MemorySwap": 0,
   373  			"OomKillDisable": false,
   374  			"NetworkMode": "bridge",
   375  			"PortBindings": {},
   376  			"Privileged": false,
   377  			"ReadonlyRootfs": false,
   378  			"PublishAllPorts": false,
   379  			"RestartPolicy": {
   380  				"MaximumRetryCount": 2,
   381  				"Name": "on-failure"
   382  			},
   383  			"LogConfig": {
   384  				"Config": null,
   385  				"Type": "json-file"
   386  			},
   387  			"SecurityOpt": null,
   388  			"VolumesFrom": null,
   389  			"Ulimits": [{}]
   390  		},
   391  		"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
   392  		"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
   393  		"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
   394  		"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
   395  		"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
   396  		"MountLabel": "",
   397  		"Name": "/boring_euclid",
   398  		"NetworkSettings": {
   399  			"Bridge": "",
   400  			"Gateway": "",
   401  			"IPAddress": "",
   402  			"IPPrefixLen": 0,
   403  			"MacAddress": "",
   404  			"PortMapping": null,
   405  			"Ports": null
   406  		},
   407  		"Path": "/bin/sh",
   408  		"ProcessLabel": "",
   409  		"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
   410  		"RestartCount": 1,
   411  		"State": {
   412  			"Error": "",
   413  			"ExitCode": 9,
   414  			"FinishedAt": "2015-01-06T15:47:32.080254511Z",
   415  			"OOMKilled": false,
   416  			"Paused": false,
   417  			"Pid": 0,
   418  			"Restarting": false,
   419  			"Running": false,
   420  			"StartedAt": "2015-01-06T15:47:32.072697474Z"
   421  		},
   422  		"Volumes": {},
   423  		"VolumesRW": {}
   424  	}
   425  
   426  Status Codes:
   427  
   428  -   **200** – no error
   429  -   **404** – no such container
   430  -   **500** – server error
   431  
   432  ### List processes running inside a container
   433  
   434  `GET /containers/(id)/top`
   435  
   436  List processes running inside the container `id`
   437  
   438  **Example request**:
   439  
   440      GET /containers/4fa6e0f0c678/top HTTP/1.1
   441  
   442  **Example response**:
   443  
   444      HTTP/1.1 200 OK
   445      Content-Type: application/json
   446  
   447      {
   448           "Titles": [
   449                   "USER",
   450                   "PID",
   451                   "%CPU",
   452                   "%MEM",
   453                   "VSZ",
   454                   "RSS",
   455                   "TTY",
   456                   "STAT",
   457                   "START",
   458                   "TIME",
   459                   "COMMAND"
   460                   ],
   461           "Processes": [
   462                   ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"],
   463                   ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"]
   464           ]
   465      }
   466  
   467  Query Parameters:
   468  
   469  -   **ps_args** – ps arguments to use (e.g., aux)
   470  
   471  Status Codes:
   472  
   473  -   **200** – no error
   474  -   **404** – no such container
   475  -   **500** – server error
   476  
   477  ### Get container logs
   478  
   479  `GET /containers/(id)/logs`
   480  
   481  Get `stdout` and `stderr` logs from the container ``id``
   482  
   483  > **Note**:
   484  > This endpoint works only for containers with `json-file` logging driver.
   485  
   486  **Example request**:
   487  
   488       GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1&timestamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1
   489  
   490  **Example response**:
   491  
   492       HTTP/1.1 101 UPGRADED
   493       Content-Type: application/vnd.docker.raw-stream
   494       Connection: Upgrade
   495       Upgrade: tcp
   496  
   497       {{ STREAM }}
   498  
   499  Query Parameters:
   500  
   501  -   **follow** – 1/True/true or 0/False/false, return stream. Default `false`.
   502  -   **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`.
   503  -   **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`.
   504  -   **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp
   505      will only output log-entries since that timestamp. Default: 0 (unfiltered)
   506  -   **timestamps** – 1/True/true or 0/False/false, print timestamps for
   507          every log line. Default `false`.
   508  -   **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all.
   509  
   510  Status Codes:
   511  
   512  -   **101** – no error, hints proxy about hijacking
   513  -   **200** – no error, no upgrade header found
   514  -   **404** – no such container
   515  -   **500** – server error
   516  
   517  ### Inspect changes on a container's filesystem
   518  
   519  `GET /containers/(id)/changes`
   520  
   521  Inspect changes on container `id`'s filesystem
   522  
   523  **Example request**:
   524  
   525      GET /containers/4fa6e0f0c678/changes HTTP/1.1
   526  
   527  **Example response**:
   528  
   529      HTTP/1.1 200 OK
   530      Content-Type: application/json
   531  
   532      [
   533           {
   534                   "Path": "/dev",
   535                   "Kind": 0
   536           },
   537           {
   538                   "Path": "/dev/kmsg",
   539                   "Kind": 1
   540           },
   541           {
   542                   "Path": "/test",
   543                   "Kind": 1
   544           }
   545      ]
   546  
   547  Values for `Kind`:
   548  
   549  - `0`: Modify
   550  - `1`: Add
   551  - `2`: Delete
   552  
   553  Status Codes:
   554  
   555  -   **200** – no error
   556  -   **404** – no such container
   557  -   **500** – server error
   558  
   559  ### Export a container
   560  
   561  `GET /containers/(id)/export`
   562  
   563  Export the contents of container `id`
   564  
   565  **Example request**:
   566  
   567      GET /containers/4fa6e0f0c678/export HTTP/1.1
   568  
   569  **Example response**:
   570  
   571      HTTP/1.1 200 OK
   572      Content-Type: application/octet-stream
   573  
   574      {{ TAR STREAM }}
   575  
   576  Status Codes:
   577  
   578  -   **200** – no error
   579  -   **404** – no such container
   580  -   **500** – server error
   581  
   582  ### Get container stats based on resource usage
   583  
   584  `GET /containers/(id)/stats`
   585  
   586  This endpoint returns a live stream of a container's resource usage statistics.
   587  
   588  > **Note**: this functionality currently only works when using the *libcontainer* exec-driver.
   589  
   590  **Example request**:
   591  
   592      GET /containers/redis1/stats HTTP/1.1
   593  
   594  **Example response**:
   595  
   596        HTTP/1.1 200 OK
   597        Content-Type: application/json
   598  
   599        {
   600           "read" : "2015-01-08T22:57:31.547920715Z",
   601           "network" : {
   602              "rx_dropped" : 0,
   603              "rx_bytes" : 648,
   604              "rx_errors" : 0,
   605              "tx_packets" : 8,
   606              "tx_dropped" : 0,
   607              "rx_packets" : 8,
   608              "tx_errors" : 0,
   609              "tx_bytes" : 648
   610           },
   611           "memory_stats" : {
   612              "stats" : {
   613                 "total_pgmajfault" : 0,
   614                 "cache" : 0,
   615                 "mapped_file" : 0,
   616                 "total_inactive_file" : 0,
   617                 "pgpgout" : 414,
   618                 "rss" : 6537216,
   619                 "total_mapped_file" : 0,
   620                 "writeback" : 0,
   621                 "unevictable" : 0,
   622                 "pgpgin" : 477,
   623                 "total_unevictable" : 0,
   624                 "pgmajfault" : 0,
   625                 "total_rss" : 6537216,
   626                 "total_rss_huge" : 6291456,
   627                 "total_writeback" : 0,
   628                 "total_inactive_anon" : 0,
   629                 "rss_huge" : 6291456,
   630                 "hierarchical_memory_limit" : 67108864,
   631                 "total_pgfault" : 964,
   632                 "total_active_file" : 0,
   633                 "active_anon" : 6537216,
   634                 "total_active_anon" : 6537216,
   635                 "total_pgpgout" : 414,
   636                 "total_cache" : 0,
   637                 "inactive_anon" : 0,
   638                 "active_file" : 0,
   639                 "pgfault" : 964,
   640                 "inactive_file" : 0,
   641                 "total_pgpgin" : 477
   642              },
   643              "max_usage" : 6651904,
   644              "usage" : 6537216,
   645              "failcnt" : 0,
   646              "limit" : 67108864
   647           },
   648           "blkio_stats" : {},
   649           "cpu_stats" : {
   650              "cpu_usage" : {
   651                 "percpu_usage" : [
   652                    16970827,
   653                    1839451,
   654                    7107380,
   655                    10571290
   656                 ],
   657                 "usage_in_usermode" : 10000000,
   658                 "total_usage" : 36488948,
   659                 "usage_in_kernelmode" : 20000000
   660              },
   661              "system_cpu_usage" : 20091722000000000,
   662              "throttling_data" : {}
   663           }
   664        }
   665  
   666  Query Parameters:
   667  
   668  -   **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`.
   669  
   670  Status Codes:
   671  
   672  -   **200** – no error
   673  -   **404** – no such container
   674  -   **500** – server error
   675  
   676  ### Resize a container TTY
   677  
   678  `POST /containers/(id)/resize?h=<height>&w=<width>`
   679  
   680  Resize the TTY for container with  `id`. You must restart the container for the resize to take effect.
   681  
   682  **Example request**:
   683  
   684        POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1
   685  
   686  **Example response**:
   687  
   688        HTTP/1.1 200 OK
   689        Content-Length: 0
   690        Content-Type: text/plain; charset=utf-8
   691  
   692  Status Codes:
   693  
   694  -   **200** – no error
   695  -   **404** – No such container
   696  -   **500** – Cannot resize container
   697  
   698  ### Start a container
   699  
   700  `POST /containers/(id)/start`
   701  
   702  Start the container `id`
   703  
   704  > **Note**:
   705  > For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body.
   706  > See [create a container](#create-a-container) for details.
   707  
   708  **Example request**:
   709  
   710       POST /containers/(id)/start HTTP/1.1
   711  
   712  **Example response**:
   713  
   714       HTTP/1.1 204 No Content
   715  
   716  Status Codes:
   717  
   718  -   **204** – no error
   719  -   **304** – container already started
   720  -   **404** – no such container
   721  -   **500** – server error
   722  
   723  ### Stop a container
   724  
   725  `POST /containers/(id)/stop`
   726  
   727  Stop the container `id`
   728  
   729  **Example request**:
   730  
   731      POST /containers/e90e34656806/stop?t=5 HTTP/1.1
   732  
   733  **Example response**:
   734  
   735      HTTP/1.1 204 No Content
   736  
   737  Query Parameters:
   738  
   739  -   **t** – number of seconds to wait before killing the container
   740  
   741  Status Codes:
   742  
   743  -   **204** – no error
   744  -   **304** – container already stopped
   745  -   **404** – no such container
   746  -   **500** – server error
   747  
   748  ### Restart a container
   749  
   750  `POST /containers/(id)/restart`
   751  
   752  Restart the container `id`
   753  
   754  **Example request**:
   755  
   756      POST /containers/e90e34656806/restart?t=5 HTTP/1.1
   757  
   758  **Example response**:
   759  
   760      HTTP/1.1 204 No Content
   761  
   762  Query Parameters:
   763  
   764  -   **t** – number of seconds to wait before killing the container
   765  
   766  Status Codes:
   767  
   768  -   **204** – no error
   769  -   **404** – no such container
   770  -   **500** – server error
   771  
   772  ### Kill a container
   773  
   774  `POST /containers/(id)/kill`
   775  
   776  Kill the container `id`
   777  
   778  **Example request**:
   779  
   780      POST /containers/e90e34656806/kill HTTP/1.1
   781  
   782  **Example response**:
   783  
   784      HTTP/1.1 204 No Content
   785  
   786  Query Parameters
   787  
   788  -   **signal** - Signal to send to the container: integer or string like `SIGINT`.
   789          When not set, `SIGKILL` is assumed and the call waits for the container to exit.
   790  
   791  Status Codes:
   792  
   793  -   **204** – no error
   794  -   **404** – no such container
   795  -   **500** – server error
   796  
   797  ### Rename a container
   798  
   799  `POST /containers/(id)/rename`
   800  
   801  Rename the container `id` to a `new_name`
   802  
   803  **Example request**:
   804  
   805      POST /containers/e90e34656806/rename?name=new_name HTTP/1.1
   806  
   807  **Example response**:
   808  
   809      HTTP/1.1 204 No Content
   810  
   811  Query Parameters:
   812  
   813  -   **name** – new name for the container
   814  
   815  Status Codes:
   816  
   817  -   **204** – no error
   818  -   **404** – no such container
   819  -   **409** - conflict name already assigned
   820  -   **500** – server error
   821  
   822  ### Pause a container
   823  
   824  `POST /containers/(id)/pause`
   825  
   826  Pause the container `id`
   827  
   828  **Example request**:
   829  
   830      POST /containers/e90e34656806/pause HTTP/1.1
   831  
   832  **Example response**:
   833  
   834      HTTP/1.1 204 No Content
   835  
   836  Status Codes:
   837  
   838  -   **204** – no error
   839  -   **404** – no such container
   840  -   **500** – server error
   841  
   842  ### Unpause a container
   843  
   844  `POST /containers/(id)/unpause`
   845  
   846  Unpause the container `id`
   847  
   848  **Example request**:
   849  
   850      POST /containers/e90e34656806/unpause HTTP/1.1
   851  
   852  **Example response**:
   853  
   854      HTTP/1.1 204 No Content
   855  
   856  Status Codes:
   857  
   858  -   **204** – no error
   859  -   **404** – no such container
   860  -   **500** – server error
   861  
   862  ### Attach to a container
   863  
   864  `POST /containers/(id)/attach`
   865  
   866  Attach to the container `id`
   867  
   868  **Example request**:
   869  
   870      POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
   871  
   872  **Example response**:
   873  
   874      HTTP/1.1 101 UPGRADED
   875      Content-Type: application/vnd.docker.raw-stream
   876      Connection: Upgrade
   877      Upgrade: tcp
   878  
   879      {{ STREAM }}
   880  
   881  Query Parameters:
   882  
   883  -   **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
   884  -   **stream** – 1/True/true or 0/False/false, return stream.
   885          Default `false`.
   886  -   **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach
   887          to `stdin`. Default `false`.
   888  -   **stdout** – 1/True/true or 0/False/false, if `logs=true`, return
   889          `stdout` log, if `stream=true`, attach to `stdout`. Default `false`.
   890  -   **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
   891          `stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
   892  
   893  Status Codes:
   894  
   895  -   **101** – no error, hints proxy about hijacking
   896  -   **200** – no error, no upgrade header found
   897  -   **400** – bad parameter
   898  -   **404** – no such container
   899  -   **500** – server error
   900  
   901      **Stream details**:
   902  
   903      When using the TTY setting is enabled in
   904      [`POST /containers/create`
   905      ](/reference/api/docker_remote_api_v1.9/#create-a-container "POST /containers/create"),
   906      the stream is the raw data from the process PTY and client's `stdin`.
   907      When the TTY is disabled, then the stream is multiplexed to separate
   908      `stdout` and `stderr`.
   909  
   910      The format is a **Header** and a **Payload** (frame).
   911  
   912      **HEADER**
   913  
   914      The header contains the information which the stream writes (`stdout` or
   915      `stderr`). It also contains the size of the associated frame encoded in the
   916      last four bytes (`uint32`).
   917  
   918      It is encoded on the first eight bytes like this:
   919  
   920          header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
   921  
   922      `STREAM_TYPE` can be:
   923  
   924  -   0: `stdin` (is written on `stdout`)
   925  -   1: `stdout`
   926  -   2: `stderr`
   927  
   928      `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of
   929      the `uint32` size encoded as big endian.
   930  
   931      **PAYLOAD**
   932  
   933      The payload is the raw stream.
   934  
   935      **IMPLEMENTATION**
   936  
   937      The simplest way to implement the Attach protocol is the following:
   938  
   939      1.  Read eight bytes.
   940      2.  Choose `stdout` or `stderr` depending on the first byte.
   941      3.  Extract the frame size from the last four bytes.
   942      4.  Read the extracted size and output it on the correct output.
   943      5.  Goto 1.
   944  
   945  ### Attach to a container (websocket)
   946  
   947  `GET /containers/(id)/attach/ws`
   948  
   949  Attach to the container `id` via websocket
   950  
   951  Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455)
   952  
   953  **Example request**
   954  
   955      GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1
   956  
   957  **Example response**
   958  
   959      {{ STREAM }}
   960  
   961  Query Parameters:
   962  
   963  -   **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
   964  -   **stream** – 1/True/true or 0/False/false, return stream.
   965          Default `false`.
   966  -   **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach
   967          to `stdin`. Default `false`.
   968  -   **stdout** – 1/True/true or 0/False/false, if `logs=true`, return
   969          `stdout` log, if `stream=true`, attach to `stdout`. Default `false`.
   970  -   **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
   971          `stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
   972  
   973  Status Codes:
   974  
   975  -   **200** – no error
   976  -   **400** – bad parameter
   977  -   **404** – no such container
   978  -   **500** – server error
   979  
   980  ### Wait a container
   981  
   982  `POST /containers/(id)/wait`
   983  
   984  Block until container `id` stops, then returns the exit code
   985  
   986  **Example request**:
   987  
   988      POST /containers/16253994b7c4/wait HTTP/1.1
   989  
   990  **Example response**:
   991  
   992      HTTP/1.1 200 OK
   993      Content-Type: application/json
   994  
   995      {"StatusCode": 0}
   996  
   997  Status Codes:
   998  
   999  -   **200** – no error
  1000  -   **404** – no such container
  1001  -   **500** – server error
  1002  
  1003  ### Remove a container
  1004  
  1005  `DELETE /containers/(id)`
  1006  
  1007  Remove the container `id` from the filesystem
  1008  
  1009  **Example request**:
  1010  
  1011      DELETE /containers/16253994b7c4?v=1 HTTP/1.1
  1012  
  1013  **Example response**:
  1014  
  1015      HTTP/1.1 204 No Content
  1016  
  1017  Query Parameters:
  1018  
  1019  -   **v** – 1/True/true or 0/False/false, Remove the volumes
  1020          associated to the container. Default `false`.
  1021  -   **force** - 1/True/true or 0/False/false, Kill then remove the container.
  1022          Default `false`.
  1023  
  1024  Status Codes:
  1025  
  1026  -   **204** – no error
  1027  -   **400** – bad parameter
  1028  -   **404** – no such container
  1029  -   **500** – server error
  1030  
  1031  ### Copy files or folders from a container
  1032  
  1033  `POST /containers/(id)/copy`
  1034  
  1035  Copy files or folders of container `id`
  1036  
  1037  **Example request**:
  1038  
  1039      POST /containers/4fa6e0f0c678/copy HTTP/1.1
  1040      Content-Type: application/json
  1041  
  1042      {
  1043           "Resource": "test.txt"
  1044      }
  1045  
  1046  **Example response**:
  1047  
  1048      HTTP/1.1 200 OK
  1049      Content-Type: application/x-tar
  1050  
  1051      {{ TAR STREAM }}
  1052  
  1053  Status Codes:
  1054  
  1055  -   **200** – no error
  1056  -   **404** – no such container
  1057  -   **500** – server error
  1058  
  1059  ## 2.2 Images
  1060  
  1061  ### List Images
  1062  
  1063  `GET /images/json`
  1064  
  1065  **Example request**:
  1066  
  1067      GET /images/json?all=0 HTTP/1.1
  1068  
  1069  **Example response**:
  1070  
  1071      HTTP/1.1 200 OK
  1072      Content-Type: application/json
  1073  
  1074      [
  1075        {
  1076           "RepoTags": [
  1077             "ubuntu:12.04",
  1078             "ubuntu:precise",
  1079             "ubuntu:latest"
  1080           ],
  1081           "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
  1082           "Created": 1365714795,
  1083           "Size": 131506275,
  1084           "VirtualSize": 131506275
  1085        },
  1086        {
  1087           "RepoTags": [
  1088             "ubuntu:12.10",
  1089             "ubuntu:quantal"
  1090           ],
  1091           "ParentId": "27cf784147099545",
  1092           "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
  1093           "Created": 1364102658,
  1094           "Size": 24653,
  1095           "VirtualSize": 180116135
  1096        }
  1097      ]
  1098  
  1099  **Example request, with digest information**:
  1100  
  1101      GET /images/json?digests=1 HTTP/1.1
  1102  
  1103  **Example response, with digest information**:
  1104  
  1105      HTTP/1.1 200 OK
  1106      Content-Type: application/json
  1107  
  1108      [
  1109        {
  1110          "Created": 1420064636,
  1111          "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125",
  1112          "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2",
  1113          "RepoDigests": [
  1114            "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
  1115          ],
  1116          "RepoTags": [
  1117            "localhost:5000/test/busybox:latest",
  1118            "playdate:latest"
  1119          ],
  1120          "Size": 0,
  1121          "VirtualSize": 2429728
  1122        }
  1123      ]
  1124  
  1125  The response shows a single image `Id` associated with two repositories
  1126  (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use
  1127  either of the `RepoTags` values `localhost:5000/test/busybox:latest` or
  1128  `playdate:latest` to reference the image.
  1129  
  1130  You can also use `RepoDigests` values to reference an image. In this response,
  1131  the array has only one reference and that is to the
  1132  `localhost:5000/test/busybox` repository; the `playdate` repository has no
  1133  digest. You can reference this digest using the value:
  1134  `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...`
  1135  
  1136  See the `docker run` and `docker build` commands for examples of digest and tag
  1137  references on the command line.
  1138  
  1139  Query Parameters:
  1140  
  1141  -   **all** – 1/True/true or 0/False/false, default false
  1142  -   **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:
  1143    -   `dangling=true`
  1144    -   `label=key` or `key=value` of an image label
  1145  
  1146  ### Build image from a Dockerfile
  1147  
  1148  `POST /build`
  1149  
  1150  Build an image from a Dockerfile
  1151  
  1152  **Example request**:
  1153  
  1154      POST /build HTTP/1.1
  1155  
  1156      {{ TAR STREAM }}
  1157  
  1158  **Example response**:
  1159  
  1160      HTTP/1.1 200 OK
  1161      Content-Type: application/json
  1162  
  1163      {"stream": "Step 1..."}
  1164      {"stream": "..."}
  1165      {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}}
  1166  
  1167  The input stream must be a `tar` archive compressed with one of the
  1168  following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`.
  1169  
  1170  The archive must include a build instructions file, typically called
  1171  `Dockerfile` at the archive's root. The `dockerfile` parameter may be
  1172  used to specify a different build instructions file. To do this, its value must be
  1173  the path to the alternate build instructions file to use.
  1174  
  1175  The archive may include any number of other files,
  1176  which are accessible in the build context (See the [*ADD build
  1177  command*](/reference/builder/#dockerbuilder)).
  1178  
  1179  The build is canceled if the client drops the connection by quitting
  1180  or being killed.
  1181  
  1182  Query Parameters:
  1183  
  1184  -   **dockerfile** - Path within the build context to the `Dockerfile`. This is
  1185          ignored if `remote` is specified and points to an external `Dockerfile`.
  1186  -   **t** – Repository name (and optionally a tag) to be applied to
  1187          the resulting image in case of success.
  1188  -   **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
  1189          URI points to a single text file, the file's contents are placed into
  1190          a file called `Dockerfile` and the image is built from that file. If
  1191          the URI points to a tarball, the file is downloaded by the daemon and
  1192          the contents therein used as the context for the build. If the URI
  1193          points to a tarball and the `dockerfile` parameter is also specified,
  1194          there must be a file with the corresponding path inside the tarball.
  1195  -   **q** – Suppress verbose build output.
  1196  -   **nocache** – Do not use the cache when building the image.
  1197  -   **pull** - Attempt to pull the image even if an older image exists locally.
  1198  -   **rm** - Remove intermediate containers after a successful build (default behavior).
  1199  -   **forcerm** - Always remove intermediate containers (includes `rm`).
  1200  -   **memory** - Set memory limit for build.
  1201  -   **memswap** - Total memory (memory + swap), `-1` to disable swap.
  1202  -   **cpushares** - CPU shares (relative weight).
  1203  -   **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`).
  1204  
  1205      Request Headers:
  1206  
  1207  -   **Content-type** – Set to `"application/tar"`.
  1208  -   **X-Registry-Config** – base64-encoded ConfigFile object
  1209  
  1210  Status Codes:
  1211  
  1212  -   **200** – no error
  1213  -   **500** – server error
  1214  
  1215  ### Create an image
  1216  
  1217  `POST /images/create`
  1218  
  1219  Create an image either by pulling it from the registry or by importing it
  1220  
  1221  **Example request**:
  1222  
  1223      POST /images/create?fromImage=ubuntu HTTP/1.1
  1224  
  1225  **Example response**:
  1226  
  1227      HTTP/1.1 200 OK
  1228      Content-Type: application/json
  1229  
  1230      {"status": "Pulling..."}
  1231      {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}}
  1232      {"error": "Invalid..."}
  1233      ...
  1234  
  1235  When using this endpoint to pull an image from the registry, the
  1236  `X-Registry-Auth` header can be used to include
  1237  a base64-encoded AuthConfig object.
  1238  
  1239  Query Parameters:
  1240  
  1241  -   **fromImage** – Name of the image to pull.
  1242  -   **fromSrc** – Source to import.  The value may be a URL from which the image
  1243          can be retrieved or `-` to read the image from the request body.
  1244  -   **repo** – Repository name.
  1245  -   **tag** – Tag.
  1246  -   **registry** – The registry to pull from.
  1247  
  1248      Request Headers:
  1249  
  1250  -   **X-Registry-Auth** – base64-encoded AuthConfig object
  1251  
  1252  Status Codes:
  1253  
  1254  -   **200** – no error
  1255  -   **500** – server error
  1256  
  1257  
  1258  
  1259  ### Inspect an image
  1260  
  1261  `GET /images/(name)/json`
  1262  
  1263  Return low-level information on the image `name`
  1264  
  1265  **Example request**:
  1266  
  1267      GET /images/ubuntu/json HTTP/1.1
  1268  
  1269  **Example response**:
  1270  
  1271      HTTP/1.1 200 OK
  1272      Content-Type: application/json
  1273  
  1274      {
  1275           "Created": "2013-03-23T22:24:18.818426-07:00",
  1276           "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
  1277           "ContainerConfig":
  1278                   {
  1279                           "Hostname": "",
  1280                           "User": "",
  1281                           "AttachStdin": false,
  1282                           "AttachStdout": false,
  1283                           "AttachStderr": false,
  1284                           "PortSpecs": null,
  1285                           "Tty": true,
  1286                           "OpenStdin": true,
  1287                           "StdinOnce": false,
  1288                           "Env": null,
  1289                           "Cmd": ["/bin/bash"],
  1290                           "Dns": null,
  1291                           "Image": "ubuntu",
  1292                           "Labels": {
  1293                               "com.example.vendor": "Acme",
  1294                               "com.example.license": "GPL",
  1295                               "com.example.version": "1.0"
  1296                           },
  1297                           "Volumes": null,
  1298                           "VolumesFrom": "",
  1299                           "WorkingDir": ""
  1300                   },
  1301           "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
  1302           "Parent": "27cf784147099545",
  1303           "Size": 6824592
  1304      }
  1305  
  1306  Status Codes:
  1307  
  1308  -   **200** – no error
  1309  -   **404** – no such image
  1310  -   **500** – server error
  1311  
  1312  ### Get the history of an image
  1313  
  1314  `GET /images/(name)/history`
  1315  
  1316  Return the history of the image `name`
  1317  
  1318  **Example request**:
  1319  
  1320      GET /images/ubuntu/history HTTP/1.1
  1321  
  1322  **Example response**:
  1323  
  1324      HTTP/1.1 200 OK
  1325      Content-Type: application/json
  1326  
  1327      [
  1328           {
  1329                   "Id": "b750fe79269d",
  1330                   "Created": 1364102658,
  1331                   "CreatedBy": "/bin/bash"
  1332           },
  1333           {
  1334                   "Id": "27cf78414709",
  1335                   "Created": 1364068391,
  1336                   "CreatedBy": ""
  1337           }
  1338      ]
  1339  
  1340  Status Codes:
  1341  
  1342  -   **200** – no error
  1343  -   **404** – no such image
  1344  -   **500** – server error
  1345  
  1346  ### Push an image on the registry
  1347  
  1348  `POST /images/(name)/push`
  1349  
  1350  Push the image `name` on the registry
  1351  
  1352  **Example request**:
  1353  
  1354      POST /images/test/push HTTP/1.1
  1355  
  1356  **Example response**:
  1357  
  1358      HTTP/1.1 200 OK
  1359      Content-Type: application/json
  1360  
  1361      {"status": "Pushing..."}
  1362      {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}}
  1363      {"error": "Invalid..."}
  1364      ...
  1365  
  1366  If you wish to push an image on to a private registry, that image must already have a tag
  1367  into a repository which references that registry `hostname` and `port`.  This repository name should
  1368  then be used in the URL. This duplicates the command line's flow.
  1369  
  1370  **Example request**:
  1371  
  1372      POST /images/registry.acme.com:5000/test/push HTTP/1.1
  1373  
  1374  
  1375  Query Parameters:
  1376  
  1377  -   **tag** – The tag to associate with the image on the registry. This is optional.
  1378  
  1379  Request Headers:
  1380  
  1381  -   **X-Registry-Auth** – Include a base64-encoded AuthConfig.
  1382          object.
  1383  
  1384  Status Codes:
  1385  
  1386  -   **200** – no error
  1387  -   **404** – no such image
  1388  -   **500** – server error
  1389  
  1390  ### Tag an image into a repository
  1391  
  1392  `POST /images/(name)/tag`
  1393  
  1394  Tag the image `name` into a repository
  1395  
  1396  **Example request**:
  1397  
  1398      POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1
  1399  
  1400  **Example response**:
  1401  
  1402      HTTP/1.1 201 OK
  1403  
  1404  Query Parameters:
  1405  
  1406  -   **repo** – The repository to tag in
  1407  -   **force** – 1/True/true or 0/False/false, default false
  1408  -   **tag** - The new tag name
  1409  
  1410  Status Codes:
  1411  
  1412  -   **201** – no error
  1413  -   **400** – bad parameter
  1414  -   **404** – no such image
  1415  -   **409** – conflict
  1416  -   **500** – server error
  1417  
  1418  ### Remove an image
  1419  
  1420  `DELETE /images/(name)`
  1421  
  1422  Remove the image `name` from the filesystem
  1423  
  1424  **Example request**:
  1425  
  1426      DELETE /images/test HTTP/1.1
  1427  
  1428  **Example response**:
  1429  
  1430      HTTP/1.1 200 OK
  1431      Content-type: application/json
  1432  
  1433      [
  1434       {"Untagged": "3e2f21a89f"},
  1435       {"Deleted": "3e2f21a89f"},
  1436       {"Deleted": "53b4f83ac9"}
  1437      ]
  1438  
  1439  Query Parameters:
  1440  
  1441  -   **force** – 1/True/true or 0/False/false, default false
  1442  -   **noprune** – 1/True/true or 0/False/false, default false
  1443  
  1444  Status Codes:
  1445  
  1446  -   **200** – no error
  1447  -   **404** – no such image
  1448  -   **409** – conflict
  1449  -   **500** – server error
  1450  
  1451  ### Search images
  1452  
  1453  `GET /images/search`
  1454  
  1455  Search for an image on [Docker Hub](https://hub.docker.com). This API
  1456  returns both `is_trusted` and `is_automated` images. Currently, they
  1457  are considered identical. In the future, the `is_trusted` property will
  1458  be deprecated and replaced by the `is_automated` property.
  1459  
  1460  > **Note**:
  1461  > The response keys have changed from API v1.6 to reflect the JSON
  1462  > sent by the registry server to the docker daemon's request.
  1463  
  1464  **Example request**:
  1465  
  1466      GET /images/search?term=sshd HTTP/1.1
  1467  
  1468  **Example response**:
  1469  
  1470      HTTP/1.1 200 OK
  1471      Content-Type: application/json
  1472  
  1473          [
  1474                  {
  1475                      "star_count": 12,
  1476                      "is_official": false,
  1477                      "name": "wma55/u1210sshd",
  1478                      "is_trusted": false,
  1479                      "is_automated": false,
  1480                      "description": "",
  1481                  },
  1482                  {
  1483                      "star_count": 10,
  1484                      "is_official": false,
  1485                      "name": "jdswinbank/sshd",
  1486                      "is_trusted": false,
  1487                      "is_automated": false,
  1488                      "description": "",
  1489                  },
  1490                  {
  1491                      "star_count": 18,
  1492                      "is_official": false,
  1493                      "name": "vgauthier/sshd",
  1494                      "is_trusted": false,
  1495                      "is_automated": false,
  1496                      "description": "",
  1497                  }
  1498          ...
  1499          ]
  1500  
  1501  Query Parameters:
  1502  
  1503  -   **term** – term to search
  1504  
  1505  Status Codes:
  1506  
  1507  -   **200** – no error
  1508  -   **500** – server error
  1509  
  1510  ## 2.3 Misc
  1511  
  1512  ### Check auth configuration
  1513  
  1514  `POST /auth`
  1515  
  1516  Get the default username and email
  1517  
  1518  **Example request**:
  1519  
  1520      POST /auth HTTP/1.1
  1521      Content-Type: application/json
  1522  
  1523      {
  1524           "username":" hannibal",
  1525           "password: "xxxx",
  1526           "email": "hannibal@a-team.com",
  1527           "serveraddress": "https://index.docker.io/v1/"
  1528      }
  1529  
  1530  **Example response**:
  1531  
  1532      HTTP/1.1 200 OK
  1533  
  1534  Status Codes:
  1535  
  1536  -   **200** – no error
  1537  -   **204** – no error
  1538  -   **500** – server error
  1539  
  1540  ### Display system-wide information
  1541  
  1542  `GET /info`
  1543  
  1544  Display system-wide information
  1545  
  1546  **Example request**:
  1547  
  1548      GET /info HTTP/1.1
  1549  
  1550  **Example response**:
  1551  
  1552      HTTP/1.1 200 OK
  1553      Content-Type: application/json
  1554  
  1555      {
  1556          "Containers": 11,
  1557          "CpuCfsPeriod": true,
  1558          "CpuCfsQuota": true,
  1559          "Debug": false,
  1560          "DockerRootDir": "/var/lib/docker",
  1561          "Driver": "btrfs",
  1562          "DriverStatus": [[""]],
  1563          "ExecutionDriver": "native-0.1",
  1564          "ExperimentalBuild": false,
  1565          "HttpProxy": "http://test:test@localhost:8080",
  1566          "HttpsProxy": "https://test:test@localhost:8080",
  1567          "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
  1568          "IPv4Forwarding": true,
  1569          "Images": 16,
  1570          "IndexServerAddress": "https://index.docker.io/v1/",
  1571          "InitPath": "/usr/bin/docker",
  1572          "InitSha1": "",
  1573          "KernelVersion": "3.12.0-1-amd64",
  1574          "Labels": [
  1575              "storage=ssd"
  1576          ],
  1577          "MemTotal": 2099236864,
  1578          "MemoryLimit": true,
  1579          "NCPU": 1,
  1580          "NEventsListener": 0,
  1581          "NFd": 11,
  1582          "NGoroutines": 21,
  1583          "Name": "prod-server-42",
  1584          "NoProxy": "9.81.1.160",
  1585          "OomKillDisable": true,
  1586          "OperatingSystem": "Boot2Docker",
  1587          "RegistryConfig": {
  1588              "IndexConfigs": {
  1589                  "docker.io": {
  1590                      "Mirrors": null,
  1591                      "Name": "docker.io",
  1592                      "Official": true,
  1593                      "Secure": true
  1594                  }
  1595              },
  1596              "InsecureRegistryCIDRs": [
  1597                  "127.0.0.0/8"
  1598              ]
  1599          },
  1600          "SwapLimit": false,
  1601          "SystemTime": "2015-03-10T11:11:23.730591467-07:00"
  1602      }
  1603  
  1604  Status Codes:
  1605  
  1606  -   **200** – no error
  1607  -   **500** – server error
  1608  
  1609  ### Show the docker version information
  1610  
  1611  `GET /version`
  1612  
  1613  Show the docker version information
  1614  
  1615  **Example request**:
  1616  
  1617      GET /version HTTP/1.1
  1618  
  1619  **Example response**:
  1620  
  1621      HTTP/1.1 200 OK
  1622      Content-Type: application/json
  1623  
  1624      {
  1625           "Version": "1.5.0",
  1626           "Os": "linux",
  1627           "KernelVersion": "3.18.5-tinycore64",
  1628           "GoVersion": "go1.4.1",
  1629           "GitCommit": "a8a31ef",
  1630           "Arch": "amd64",
  1631           "ApiVersion": "1.19"
  1632      }
  1633  
  1634  Status Codes:
  1635  
  1636  -   **200** – no error
  1637  -   **500** – server error
  1638  
  1639  ### Ping the docker server
  1640  
  1641  `GET /_ping`
  1642  
  1643  Ping the docker server
  1644  
  1645  **Example request**:
  1646  
  1647      GET /_ping HTTP/1.1
  1648  
  1649  **Example response**:
  1650  
  1651      HTTP/1.1 200 OK
  1652      Content-Type: text/plain
  1653  
  1654      OK
  1655  
  1656  Status Codes:
  1657  
  1658  -   **200** - no error
  1659  -   **500** - server error
  1660  
  1661  ### Create a new image from a container's changes
  1662  
  1663  `POST /commit`
  1664  
  1665  Create a new image from a container's changes
  1666  
  1667  **Example request**:
  1668  
  1669      POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
  1670      Content-Type: application/json
  1671  
  1672      {
  1673           "Hostname": "",
  1674           "Domainname": "",
  1675           "User": "",
  1676           "AttachStdin": false,
  1677           "AttachStdout": true,
  1678           "AttachStderr": true,
  1679           "PortSpecs": null,
  1680           "Tty": false,
  1681           "OpenStdin": false,
  1682           "StdinOnce": false,
  1683           "Env": null,
  1684           "Cmd": [
  1685                   "date"
  1686           ],
  1687           "Volumes": {
  1688                   "/tmp": {}
  1689           },
  1690           "Labels": {
  1691                   "key1": "value1",
  1692                   "key2": "value2"
  1693            },
  1694           "WorkingDir": "",
  1695           "NetworkDisabled": false,
  1696           "ExposedPorts": {
  1697                   "22/tcp": {}
  1698           }
  1699      }
  1700  
  1701  **Example response**:
  1702  
  1703      HTTP/1.1 201 Created
  1704      Content-Type: application/vnd.docker.raw-stream
  1705  
  1706      {"Id": "596069db4bf5"}
  1707  
  1708  Json Parameters:
  1709  
  1710  -  **config** - the container's configuration
  1711  
  1712  Query Parameters:
  1713  
  1714  -   **container** – source container
  1715  -   **repo** – repository
  1716  -   **tag** – tag
  1717  -   **comment** – commit message
  1718  -   **author** – author (e.g., "John Hannibal Smith
  1719      <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
  1720  
  1721  Status Codes:
  1722  
  1723  -   **201** – no error
  1724  -   **404** – no such container
  1725  -   **500** – server error
  1726  
  1727  ### Monitor Docker's events
  1728  
  1729  `GET /events`
  1730  
  1731  Get container events from docker, either in real time via streaming, or via
  1732  polling (using since).
  1733  
  1734  Docker containers report the following events:
  1735  
  1736      attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause
  1737  
  1738  and Docker images report:
  1739  
  1740      untag, delete
  1741  
  1742  **Example request**:
  1743  
  1744      GET /events?since=1374067924
  1745  
  1746  **Example response**:
  1747  
  1748      HTTP/1.1 200 OK
  1749      Content-Type: application/json
  1750  
  1751      {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924}
  1752      {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924}
  1753      {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966}
  1754      {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970}
  1755  
  1756  Query Parameters:
  1757  
  1758  -   **since** – Timestamp used for polling
  1759  -   **until** – Timestamp used for polling
  1760  -   **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters:
  1761    -   `event=<string>`; -- event to filter
  1762    -   `image=<string>`; -- image to filter
  1763    -   `container=<string>`; -- container to filter
  1764  
  1765  Status Codes:
  1766  
  1767  -   **200** – no error
  1768  -   **500** – server error
  1769  
  1770  ### Get a tarball containing all images in a repository
  1771  
  1772  `GET /images/(name)/get`
  1773  
  1774  Get a tarball containing all images and metadata for the repository specified
  1775  by `name`.
  1776  
  1777  If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image
  1778  (and its parents) are returned. If `name` is an image ID, similarly only that
  1779  image (and its parents) are returned, but with the exclusion of the
  1780  'repositories' file in the tarball, as there were no image names referenced.
  1781  
  1782  See the [image tarball format](#image-tarball-format) for more details.
  1783  
  1784  **Example request**
  1785  
  1786      GET /images/ubuntu/get
  1787  
  1788  **Example response**:
  1789  
  1790      HTTP/1.1 200 OK
  1791      Content-Type: application/x-tar
  1792  
  1793      Binary data stream
  1794  
  1795  Status Codes:
  1796  
  1797  -   **200** – no error
  1798  -   **500** – server error
  1799  
  1800  ### Get a tarball containing all images.
  1801  
  1802  `GET /images/get`
  1803  
  1804  Get a tarball containing all images and metadata for one or more repositories.
  1805  
  1806  For each value of the `names` parameter: if it is a specific name and tag (e.g.
  1807  `ubuntu:latest`), then only that image (and its parents) are returned; if it is
  1808  an image ID, similarly only that image (and its parents) are returned and there
  1809  would be no names referenced in the 'repositories' file for this image ID.
  1810  
  1811  See the [image tarball format](#image-tarball-format) for more details.
  1812  
  1813  **Example request**
  1814  
  1815      GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox
  1816  
  1817  **Example response**:
  1818  
  1819      HTTP/1.1 200 OK
  1820      Content-Type: application/x-tar
  1821  
  1822      Binary data stream
  1823  
  1824  Status Codes:
  1825  
  1826  -   **200** – no error
  1827  -   **500** – server error
  1828  
  1829  ### Load a tarball with a set of images and tags into docker
  1830  
  1831  `POST /images/load`
  1832  
  1833  Load a set of images and tags into a Docker repository.
  1834  See the [image tarball format](#image-tarball-format) for more details.
  1835  
  1836  **Example request**
  1837  
  1838      POST /images/load
  1839  
  1840      Tarball in body
  1841  
  1842  **Example response**:
  1843  
  1844      HTTP/1.1 200 OK
  1845  
  1846  Status Codes:
  1847  
  1848  -   **200** – no error
  1849  -   **500** – server error
  1850  
  1851  ### Image tarball format
  1852  
  1853  An image tarball contains one directory per image layer (named using its long ID),
  1854  each containing these files:
  1855  
  1856  - `VERSION`: currently `1.0` - the file format version
  1857  - `json`: detailed layer information, similar to `docker inspect layer_id`
  1858  - `layer.tar`: A tarfile containing the filesystem changes in this layer
  1859  
  1860  The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories
  1861  for storing attribute changes and deletions.
  1862  
  1863  If the tarball defines a repository, the tarball should also include a `repositories` file at
  1864  the root that contains a list of repository and tag names mapped to layer IDs.
  1865  
  1866  ```
  1867  {"hello-world":
  1868      {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
  1869  }
  1870  ```
  1871  
  1872  ### Exec Create
  1873  
  1874  `POST /containers/(id)/exec`
  1875  
  1876  Sets up an exec instance in a running container `id`
  1877  
  1878  **Example request**:
  1879  
  1880      POST /containers/e90e34656806/exec HTTP/1.1
  1881      Content-Type: application/json
  1882  
  1883        {
  1884         "AttachStdin": false,
  1885         "AttachStdout": true,
  1886         "AttachStderr": true,
  1887         "Tty": false,
  1888         "Cmd": [
  1889                       "date"
  1890               ],
  1891        }
  1892  
  1893  **Example response**:
  1894  
  1895      HTTP/1.1 201 OK
  1896      Content-Type: application/json
  1897  
  1898      {
  1899           "Id": "f90e34656806"
  1900           "Warnings":[]
  1901      }
  1902  
  1903  Json Parameters:
  1904  
  1905  -   **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command.
  1906  -   **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command.
  1907  -   **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command.
  1908  -   **Tty** - Boolean value to allocate a pseudo-TTY.
  1909  -   **Cmd** - Command to run specified as a string or an array of strings.
  1910  
  1911  
  1912  Status Codes:
  1913  
  1914  -   **201** – no error
  1915  -   **404** – no such container
  1916  
  1917  ### Exec Start
  1918  
  1919  `POST /exec/(id)/start`
  1920  
  1921  Starts a previously set up `exec` instance `id`. If `detach` is true, this API
  1922  returns after starting the `exec` command. Otherwise, this API sets up an
  1923  interactive session with the `exec` command.
  1924  
  1925  **Example request**:
  1926  
  1927      POST /exec/e90e34656806/start HTTP/1.1
  1928      Content-Type: application/json
  1929  
  1930      {
  1931       "Detach": false,
  1932       "Tty": false,
  1933      }
  1934  
  1935  **Example response**:
  1936  
  1937      HTTP/1.1 201 OK
  1938      Content-Type: application/json
  1939  
  1940      {{ STREAM }}
  1941  
  1942  Json Parameters:
  1943  
  1944  -   **Detach** - Detach from the `exec` command.
  1945  -   **Tty** - Boolean value to allocate a pseudo-TTY.
  1946  
  1947  Status Codes:
  1948  
  1949  -   **201** – no error
  1950  -   **404** – no such exec instance
  1951  
  1952      **Stream details**:
  1953      Similar to the stream behavior of `POST /container/(id)/attach` API
  1954  
  1955  ### Exec Resize
  1956  
  1957  `POST /exec/(id)/resize`
  1958  
  1959  Resizes the `tty` session used by the `exec` command `id`.
  1960  This API is valid only if `tty` was specified as part of creating and starting the `exec` command.
  1961  
  1962  **Example request**:
  1963  
  1964      POST /exec/e90e34656806/resize HTTP/1.1
  1965      Content-Type: text/plain
  1966  
  1967  **Example response**:
  1968  
  1969      HTTP/1.1 201 OK
  1970      Content-Type: text/plain
  1971  
  1972  Query Parameters:
  1973  
  1974  -   **h** – height of `tty` session
  1975  -   **w** – width
  1976  
  1977  Status Codes:
  1978  
  1979  -   **201** – no error
  1980  -   **404** – no such exec instance
  1981  
  1982  ### Exec Inspect
  1983  
  1984  `GET /exec/(id)/json`
  1985  
  1986  Return low-level information about the `exec` command `id`.
  1987  
  1988  **Example request**:
  1989  
  1990      GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1
  1991  
  1992  **Example response**:
  1993  
  1994      HTTP/1.1 200 OK
  1995      Content-Type: plain/text
  1996  
  1997      {
  1998        "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39",
  1999        "Running" : false,
  2000        "ExitCode" : 2,
  2001        "ProcessConfig" : {
  2002          "privileged" : false,
  2003          "user" : "",
  2004          "tty" : false,
  2005          "entrypoint" : "sh",
  2006          "arguments" : [
  2007            "-c",
  2008            "exit 2"
  2009          ]
  2010        },
  2011        "OpenStdin" : false,
  2012        "OpenStderr" : false,
  2013        "OpenStdout" : false,
  2014        "Container" : {
  2015          "State" : {
  2016            "Running" : true,
  2017            "Paused" : false,
  2018            "Restarting" : false,
  2019            "OOMKilled" : false,
  2020            "Pid" : 3650,
  2021            "ExitCode" : 0,
  2022            "Error" : "",
  2023            "StartedAt" : "2014-11-17T22:26:03.717657531Z",
  2024            "FinishedAt" : "0001-01-01T00:00:00Z"
  2025          },
  2026          "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c",
  2027          "Created" : "2014-11-17T22:26:03.626304998Z",
  2028          "Path" : "date",
  2029          "Args" : [],
  2030          "Config" : {
  2031            "Hostname" : "8f177a186b97",
  2032            "Domainname" : "",
  2033            "User" : "",
  2034            "AttachStdin" : false,
  2035            "AttachStdout" : false,
  2036            "AttachStderr" : false,
  2037            "PortSpecs": null,
  2038            "ExposedPorts" : null,
  2039            "Tty" : false,
  2040            "OpenStdin" : false,
  2041            "StdinOnce" : false,
  2042            "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ],
  2043            "Cmd" : [
  2044              "date"
  2045            ],
  2046            "Image" : "ubuntu",
  2047            "Volumes" : null,
  2048            "WorkingDir" : "",
  2049            "Entrypoint" : null,
  2050            "NetworkDisabled" : false,
  2051            "MacAddress" : "",
  2052            "OnBuild" : null,
  2053            "SecurityOpt" : null
  2054          },
  2055          "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5",
  2056          "NetworkSettings" : {
  2057            "IPAddress" : "172.17.0.2",
  2058            "IPPrefixLen" : 16,
  2059            "MacAddress" : "02:42:ac:11:00:02",
  2060            "Gateway" : "172.17.42.1",
  2061            "Bridge" : "docker0",
  2062            "PortMapping" : null,
  2063            "Ports" : {}
  2064          },
  2065          "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf",
  2066          "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname",
  2067          "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts",
  2068          "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
  2069          "Name" : "/test",
  2070          "Driver" : "aufs",
  2071          "ExecDriver" : "native-0.2",
  2072          "MountLabel" : "",
  2073          "ProcessLabel" : "",
  2074          "AppArmorProfile" : "",
  2075          "RestartCount" : 0,
  2076          "Volumes" : {},
  2077          "VolumesRW" : {}
  2078        }
  2079      }
  2080  
  2081  Status Codes:
  2082  
  2083  -   **200** – no error
  2084  -   **404** – no such exec instance
  2085  -   **500** - server error
  2086  
  2087  # 3. Going further
  2088  
  2089  ## 3.1 Inside `docker run`
  2090  
  2091  As an example, the `docker run` command line makes the following API calls:
  2092  
  2093  - Create the container
  2094  
  2095  - If the status code is 404, it means the image doesn't exist:
  2096      - Try to pull it.
  2097      - Then, retry to create the container.
  2098  
  2099  - Start the container.
  2100  
  2101  - If you are not in detached mode:
  2102  - Attach to the container, using `logs=1` (to have `stdout` and
  2103        `stderr` from the container's start) and `stream=1`
  2104  
  2105  - If in detached mode or only `stdin` is attached, display the container's id.
  2106  
  2107  ## 3.2 Hijacking
  2108  
  2109  In this version of the API, `/attach`, uses hijacking to transport `stdin`,
  2110  `stdout`, and `stderr` on the same socket.
  2111  
  2112  To hint potential proxies about connection hijacking, Docker client sends
  2113  connection upgrade headers similarly to websocket.
  2114  
  2115      Upgrade: tcp
  2116      Connection: Upgrade
  2117  
  2118  When Docker daemon detects the `Upgrade` header, it switches its status code
  2119  from **200 OK** to **101 UPGRADED** and resends the same headers.
  2120  
  2121  
  2122  ## 3.3 CORS Requests
  2123  
  2124  To set cross origin requests to the remote api please give values to 
  2125  `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all,
  2126  default or blank means CORS disabled
  2127  
  2128      $ docker -d -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"