View Source DockerEngineAPI.Api.Container (docker_engine_api v1.43.0)
API calls for all endpoints tagged Container
.
Summary
Functions
Get an archive of a filesystem resource in a container Get a tar archive of a resource in the filesystem of container id.
Get information about files in a container A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.
Attach to a container Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached. Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything. See the documentation for the `docker attach` command for more details. ### Hijacking This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket. This is the response from the daemon for an attach request: ``` HTTP/1.1 200 OK Content-Type: application/vnd.docker.raw-stream [STREAM] ``` After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server. To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers. For example, the client sends this request to upgrade the connection: ``` POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1 Upgrade: tcp Connection: Upgrade ``` The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream: ``` HTTP/1.1 101 UPGRADED Content-Type: application/vnd.docker.raw-stream Connection: Upgrade Upgrade: tcp [STREAM] ``` ### Stream format When the TTY setting is disabled in `POST /containers/create`, the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload. The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`). It is encoded on the first eight bytes like this: ```go header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} ``` `STREAM_TYPE` can be: - 0: `stdin` (is written on `stdout`) - 1: `stdout` - 2: `stderr` `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian. Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`. The simplest way to implement this protocol is the following: 1. Read 8 bytes. 2. Choose `stdout` or `stderr` depending on the first byte. 3. Extract the frame size from the last four bytes. 4. Read the extracted size and output it on the correct output. 5. Goto 1. ### Stream format when using a TTY When the TTY setting is enabled in `POST /containers/create`, the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.
Attach to a container via a websocket
Get changes on a container’s filesystem Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of: - `0`: Modified ("C") - `1`: Added ("A") - `2`: Deleted ("D")
Create a container
Remove a container
Export a container Export the contents of a container as a tarball.
Inspect a container Return low-level information about a container.
Kill a container Send a POSIX signal to a container, defaulting to killing to the container.
List containers Returns a list of containers. For details on the format, see the inspect endpoint. Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .
Get container logs Get `stdout` and `stderr` logs from a container. Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
Pause a container Use the freezer cgroup to suspend all processes in a container. Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.
Delete stopped containers
Rename a container
Resize a container TTY Resize the TTY for a container.
Restart a container
Start a container
Stop a container
List processes running inside a container On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.
Unpause a container Resume a container which has been paused.
Update a container Change various configuration options of a container without having to recreate it.
Wait for a container Block until a container stops, then returns the exit code.
Extract an archive of files or folders to a directory in a container Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".
Functions
Get an archive of a filesystem resource in a container Get a tar archive of a resource in the filesystem of container id.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- path (String.t): Resource in the container’s filesystem to archive.
- opts (KeywordList): [optional] Optional parameters
Returns
} on success {:error, info} on failure
Get information about files in a container A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- path (String.t): Resource in the container’s filesystem to archive.
- opts (KeywordList): [optional] Optional parameters
Returns
} on success {:error, info} on failure
Attach to a container Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached. Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything. See the documentation for the `docker attach` command for more details. ### Hijacking This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket. This is the response from the daemon for an attach request: ``` HTTP/1.1 200 OK Content-Type: application/vnd.docker.raw-stream [STREAM] ``` After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server. To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers. For example, the client sends this request to upgrade the connection: ``` POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1 Upgrade: tcp Connection: Upgrade ``` The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream: ``` HTTP/1.1 101 UPGRADED Content-Type: application/vnd.docker.raw-stream Connection: Upgrade Upgrade: tcp [STREAM] ``` ### Stream format When the TTY setting is disabled in `POST /containers/create`, the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload. The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`). It is encoded on the first eight bytes like this: ```go header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} ``` `STREAM_TYPE` can be: - 0: `stdin` (is written on `stdout`) - 1: `stdout` - 2: `stderr` `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian. Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`. The simplest way to implement this protocol is the following: 1. Read 8 bytes. 2. Choose `stdout` or `stderr` depending on the first byte. 3. Extract the frame size from the last four bytes. 4. Read the extracted size and output it on the correct output. 5. Goto 1. ### Stream format when using a TTY When the TTY setting is enabled in `POST /containers/create`, the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :detachkeys (String.t): Override the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or ``.
- :logs (boolean()): Replay previous logs from the container. This is useful for attaching to a container that has started and you want to output everything since the container started. If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output.
- :stream (boolean()): Stream attached streams from the time the request was made onwards.
- :stdin (boolean()): Attach to `stdin`
- :stdout (boolean()): Attach to `stdout`
- :stderr (boolean()): Attach to `stderr`
Returns
} on success {:error, info} on failure
Attach to a container via a websocket
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :detachkeys (String.t): Override the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or ``.
- :logs (boolean()): Return logs
- :stream (boolean()): Return stream
- :stdin (boolean()): Attach to `stdin`
- :stdout (boolean()): Attach to `stdout`
- :stderr (boolean()): Attach to `stderr`
Returns
} on success {:error, info} on failure
Get changes on a container’s filesystem Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of: - `0`: Modified ("C") - `1`: Added ("A") - `2`: Deleted ("D")
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
Returns
, ...]} on success {:error, info} on failure
Create a container
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- body (object): Container to create
- opts (KeywordList): [optional] Optional parameters
- :name (String.t): Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.
- :platform (String.t): Platform in the format `os[/arch[/variant]]` used for image lookup. When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status. If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example; WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested
Returns
} on success {:error, info} on failure
Remove a container
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :v (boolean()): Remove anonymous volumes associated with the container.
- :force (boolean()): If the container is running, kill it before removing it.
- :link (boolean()): Remove the specified link associated with the container.
Returns
} on success {:error, info} on failure
Export a container Export the contents of a container as a tarball.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
Returns
} on success {:error, info} on failure
Inspect a container Return low-level information about a container.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :size (boolean()): Return the size of container as fields `SizeRw` and `SizeRootFs`
Returns
} on success {:error, info} on failure
Kill a container Send a POSIX signal to a container, defaulting to killing to the container.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :signal (String.t): Signal to send to the container as an integer or string (e.g. `SIGINT`).
Returns
} on success {:error, info} on failure
List containers Returns a list of containers. For details on the format, see the inspect endpoint. Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- opts (KeywordList): [optional] Optional parameters
- :all (boolean()): Return all containers. By default, only running containers are shown.
- :limit (integer()): Return this number of most recently created containers, including non-running ones.
- :size (boolean()): Return the size of container as fields `SizeRw` and `SizeRootFs`.
- :filters (String.t): Filters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers. Available filters: - `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`) - `before`=(`<container id>` or `<container name>`) - `expose`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`) - `exited=<int>` containers with exit code of `<int>` - `health`=(`starting`|`healthy`|`unhealthy`|`none`) - `id=<ID>` a container's ID - `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only) - `is-task=`(`true`|`false`) - `label=key` or `label="key=value"` of a container label - `name=<name>` a container's name - `network`=(`<network id>` or `<network name>`) - `publish`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`) - `since`=(`<container id>` or `<container name>`) - `status=`(`created`|`restarting`|`running`|`removing`|`paused`|`exited`|`dead`) - `volume`=(`<volume name>` or `<mount point destination>`)
Returns
, ...]} on success {:error, info} on failure
Get container logs Get `stdout` and `stderr` logs from a container. Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :follow (boolean()): Keep connection after returning logs.
- :stdout (boolean()): Return logs from `stdout`
- :stderr (boolean()): Return logs from `stderr`
- :since (integer()): Only return logs since this time, as a UNIX timestamp
- :until (integer()): Only return logs before this time, as a UNIX timestamp
- :timestamps (boolean()): Add timestamps to every log line
- :tail (String.t): Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines.
Returns
} on success {:error, info} on failure
Pause a container Use the freezer cgroup to suspend all processes in a container. Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
Returns
} on success {:error, info} on failure
Delete stopped containers
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- opts (KeywordList): [optional] Optional parameters
- :filters (String.t): Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters: - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels.
Returns
} on success {:error, info} on failure
Rename a container
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- name (String.t): New name for the container
- opts (KeywordList): [optional] Optional parameters
Returns
} on success {:error, info} on failure
Resize a container TTY Resize the TTY for a container.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :h (integer()): Height of the TTY session in characters
- :w (integer()): Width of the TTY session in characters
Returns
} on success {:error, info} on failure
Restart a container
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :signal (String.t): Signal to send to the container as an integer or string (e.g. `SIGINT`).
- :t (integer()): Number of seconds to wait before killing the container
Returns
} on success {:error, info} on failure
Start a container
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :detachkeys (String.t): Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or ``.
Returns
} on success {:error, info} on failure
Stop a container
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :signal (String.t): Signal to send to the container as an integer or string (e.g. `SIGINT`).
- :t (integer()): Number of seconds to wait before killing the container
Returns
} on success {:error, info} on failure
List processes running inside a container On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :ps_args (String.t): The arguments to pass to `ps`. For example, `aux`
Returns
} on success {:error, info} on failure
Unpause a container Resume a container which has been paused.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
Returns
} on success {:error, info} on failure
Update a container Change various configuration options of a container without having to recreate it.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- update (object):
- opts (KeywordList): [optional] Optional parameters
Returns
} on success {:error, info} on failure
Wait for a container Block until a container stops, then returns the exit code.
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- opts (KeywordList): [optional] Optional parameters
- :condition (String.t): Wait until a container state reaches the given condition. Defaults to `not-running` if omitted or empty.
Returns
} on success {:error, info} on failure
put_container_archive(connection, id, path, input_stream, opts \\ [])
View SourceExtract an archive of files or folders to a directory in a container Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".
Parameters
- connection (DockerEngineAPI.Connection): Connection to server
- id (String.t): ID or name of the container
- path (String.t): Path to a directory in the container to extract the archive’s contents into.
- input_stream (binary()): The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.
- opts (KeywordList): [optional] Optional parameters
- :no_overwrite_dir_non_dir (String.t): If `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa.
- :copy_uidgid (String.t): If `1`, `true`, then it will copy UID/GID maps to the dest file or dir
Returns
} on success {:error, info} on failure