toolshed/docker-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #105 from andrewhsu/backport-doc-fixes

Browse Source 
[17.06] backport various docs fixes
This commit is contained in:
Andrew Hsu
2017-07-13 11:54:25 -07:00
committed by GitHub
parent b538302e2c 149c1a0435
commit ab734f59cc
14 changed files with 215 additions and 268 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/cli/docs/extend/plugins_authorization.md
+1 -1
View File
@@ -27,7 +27,7 @@ same is true for callers using Docker's Engine API to contact the daemon. If you
require greater access control, you can create authorization plugins and add
them to your Docker daemon configuration. Using an authorization plugin, a
Docker administrator can configure granular access policies for managing access
to Docker daemon.
to the Docker daemon.
Anyone with the appropriate skills can develop an authorization plugin. These
skills, at their most basic, are knowledge of Docker, understanding of REST, and
components/cli/docs/reference/builder.md
+19 -12
View File
@@ -30,13 +30,13 @@ Practices](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-pr
## Usage
The [`docker build`](commandline/build.md) command builds an image from
a `Dockerfile` and a *context*. The build's context is the files at a specified
location `PATH` or `URL`. The `PATH` is a directory on your local filesystem.
The `URL` is a Git repository location.
a `Dockerfile` and a *context*. The build's context is the set of files at a
specified location `PATH` or `URL`. The `PATH` is a directory on your local
filesystem. The `URL` is a Git repository location.
A context is processed recursively. So, a `PATH` includes any subdirectories and
the `URL` includes the repository and its submodules. A simple build command
that uses the current directory as context:
the `URL` includes the repository and its submodules. This example shows a
build command that uses the current directory as context:
$ docker build .
Sending build context to Docker daemon 6.51 MB
@@ -1306,11 +1306,18 @@ Keep the following things in mind about volumes in the `Dockerfile`.
## USER
USER daemon
USER <user>[:<group>]
or
USER <UID>[:<GID>]
The `USER` instruction sets the user name (or UID) and optionally the user
group (or GID) to use when running the image and for any `RUN`, `CMD` and
`ENTRYPOINT` instructions that follow it in the `Dockerfile`.
> **Warning**:
> When the user does doesn't have a primary group then the image (or the next
> instructions) will be run with the `root` group.
The `USER` instruction sets the user name or UID to use when running the image
and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the
`Dockerfile`.
## WORKDIR
@@ -1321,9 +1328,9 @@ The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`,
If the `WORKDIR` doesn't exist, it will be created even if it's not used in any
subsequent `Dockerfile` instruction.
It can be used multiple times in the one `Dockerfile`. If a relative path
is provided, it will be relative to the path of the previous `WORKDIR`
instruction. For example:
The `WORKDIR` instruction can be used multiple times in a `Dockerfile`. If a
relative path is provided, it will be relative to the path of the previous
`WORKDIR` instruction. For example:
WORKDIR /a
WORKDIR b
components/cli/docs/reference/commandline/attach.md
+1 -1
View File
@@ -40,7 +40,7 @@ interactively, as though the commands were running directly in your terminal.
> not be interacting with the terminal at that time.
You can attach to the same contained process multiple times simultaneously,
even as a different user with the appropriate permissions.
from different sessions on the Docker host.
To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the
container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to
components/cli/docs/reference/commandline/build.md
+6 -6
View File
@@ -63,11 +63,11 @@ Options:
## Description
Builds Docker images from a Dockerfile and a "context". A build's context is
the files located in the specified `PATH` or `URL`. The build process can refer
to any of the files in the context. For example, your build can use an
[*ADD*](../builder.md#add) instruction to reference a file in the
context.
The `docker build` command builds Docker images from a Dockerfile and a
"context". A build's context is the set of files located in the specified
`PATH` or `URL`. The build process can refer to any of the files in the
context. For example, your build can use a [*COPY*](../builder.md#copy)
instruction to reference a file in the context.
The `URL` parameter can refer to three kinds of resources: Git repositories,
pre-packaged tarball contexts and plain text files.
@@ -88,7 +88,7 @@ user credentials, VPN's, and so forth.
Git URLs accept context configuration in their fragment section, separated by a
colon `:`. The first part represents the reference that Git will check out,
this can be either a branch, a tag, or a remote reference. The second part
and can be either a branch, a tag, or a remote reference. The second part
represents a subdirectory inside the repository that will be used as a build
context.
components/cli/docs/reference/commandline/cli.md
+2
View File
@@ -216,6 +216,7 @@ attach`, `docker exec`, `docker run` or `docker start` command.
Following is a sample `config.json` file:
```json
{% raw %}
{
"HttpHeaders": {
"MyHeader": "MyValue"
@@ -236,6 +237,7 @@ Following is a sample `config.json` file:
"unicorn.example.com": "vcbait"
}
}
{% endraw %}
```
### Notary
components/cli/docs/reference/commandline/dockerd.md
+18 -152
View File
@@ -969,14 +969,14 @@ $ sudo dockerd \
The currently supported cluster store options are:
| Option | Description |
|-----------------------|-------------|
| `discovery.heartbeat` | Specifies the heartbeat timer in seconds which is used by the daemon as a `keepalive` mechanism to make sure discovery module treats the node as alive in the cluster. If not configured, the default value is 20 seconds. |
| Option | Description |
|:----------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `discovery.heartbeat` | Specifies the heartbeat timer in seconds which is used by the daemon as a `keepalive` mechanism to make sure discovery module treats the node as alive in the cluster. If not configured, the default value is 20 seconds. |
| `discovery.ttl` | Specifies the TTL (time-to-live) in seconds which is used by the discovery module to timeout a node if a valid heartbeat is not received within the configured ttl value. If not configured, the default value is 60 seconds. |
| `kv.cacertfile` | Specifies the path to a local file with PEM encoded CA certificates to trust. |
| `kv.certfile` | Specifies the path to a local file with a PEM encoded certificate. This certificate is used as the client cert for communication with the Key/Value store. |
| `kv.keyfile` | Specifies the path to a local file with a PEM encoded private key. This private key is used as the client key for communication with the Key/Value store. |
| `kv.path` | Specifies the path in the Key/Value store. If not configured, the default value is 'docker/nodes'. |
| `kv.cacertfile` | Specifies the path to a local file with PEM encoded CA certificates to trust. |
| `kv.certfile` | Specifies the path to a local file with a PEM encoded certificate. This certificate is used as the client cert for communication with the Key/Value store. |
| `kv.keyfile` | Specifies the path to a local file with a PEM encoded private key. This private key is used as the client key for communication with the Key/Value store. |
| `kv.path` | Specifies the path in the Key/Value store. If not configured, the default value is 'docker/nodes'. |
#### Access authorization
@@ -1005,152 +1005,18 @@ plugin](../../extend/plugins_authorization.md) section in the Docker extend sect
#### Daemon user namespace options
The Linux kernel [user namespace support](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) provides additional security by enabling
a process, and therefore a container, to have a unique range of user and
group IDs which are outside the traditional user and group range utilized by
the host system. Potentially the most important security improvement is that,
by default, container processes running as the `root` user will have expected
administrative privilege (with some restrictions) inside the container but will
effectively be mapped to an unprivileged `uid` on the host.
The Linux kernel
[user namespace support](http://man7.org/linux/man-pages/man7/user_namespaces.7.html)
provides additional security by enabling a process, and therefore a container,
to have a unique range of user and group IDs which are outside the traditional
user and group range utilized by the host system. Potentially the most important
security improvement is that, by default, container processes running as the
`root` user will have expected administrative privilege (with some restrictions)
inside the container but will effectively be mapped to an unprivileged `uid` on
the host.
When user namespace support is enabled, Docker creates a single daemon-wide mapping
for all containers running on the same engine instance. The mappings will
utilize the existing subordinate user and group ID feature available on all modern
Linux distributions.
The [`/etc/subuid`](http://man7.org/linux/man-pages/man5/subuid.5.html) and
[`/etc/subgid`](http://man7.org/linux/man-pages/man5/subgid.5.html) files will be
read for the user, and optional group, specified to the `--userns-remap`
parameter. If you do not wish to specify your own user and/or group, you can
provide `default` as the value to this flag, and a user will be created on your behalf
and provided subordinate uid and gid ranges. This default user will be named
`dockremap`, and entries will be created for it in `/etc/passwd` and
`/etc/group` using your distro's standard user and group creation tools.
> **Note**: The single mapping per-daemon restriction is in place for now
> because Docker shares image layers from its local cache across all
> containers running on the engine instance. Since file ownership must be
> the same for all containers sharing the same layer content, the decision
> was made to map the file ownership on `docker pull` to the daemon's user and
> group mappings so that there is no delay for running containers once the
> content is downloaded. This design preserves the same performance for `docker
> pull`, `docker push`, and container startup as users expect with
> user namespaces disabled.
##### Start the daemon with user namespaces enabled
To enable user namespace support, start the daemon with the
`--userns-remap` flag, which accepts values in the following formats:
- uid
- uid:gid
- username
- username:groupname
If numeric IDs are provided, translation back to valid user or group names
will occur so that the subordinate uid and gid information can be read, given
these resources are name-based, not id-based. If the numeric ID information
provided does not exist as entries in `/etc/passwd` or `/etc/group`, daemon
startup will fail with an error message.
**Example: starting with default Docker user management:**
```bash
$ sudo dockerd --userns-remap=default
```
When `default` is provided, Docker will create - or find the existing - user and group
named `dockremap`. If the user is created, and the Linux distribution has
appropriate support, the `/etc/subuid` and `/etc/subgid` files will be populated
with a contiguous 65536 length range of subordinate user and group IDs, starting
at an offset based on prior entries in those files. For example, Ubuntu will
create the following range, based on an existing user named `user1` already owning
the first 65536 range:
```bash
$ cat /etc/subuid
user1:100000:65536
dockremap:165536:65536
```
If you have a preferred/self-managed user with subordinate ID mappings already
configured, you can provide that username or uid to the `--userns-remap` flag.
If you have a group that doesn't match the username, you may provide the `gid`
or group name as well; otherwise the username will be used as the group name
when querying the system for the subordinate group ID range.
The output of `docker info` can be used to determine if the daemon is running
with user namespaces enabled or not. If the daemon is configured with user
namespaces, the Security Options entry in the response will list "userns" as
one of the enabled security features.
##### Behavior differences when user namespaces are enabled
When you start the Docker daemon with `--userns-remap`, Docker segregates the graph directory
where the images are stored by adding an extra directory with a name corresponding to the
remapped UID and GID. For example, if the remapped UID and GID begin with `165536`, all
images and containers running with that remap setting are located in `/var/lib/docker/165536.165536`
instead of `/var/lib/docker/`.
In addition, the files and directories within the new directory, which correspond to
images and container layers, are also owned by the new UID and GID. To set the ownership
correctly, you need to re-pull the images and restart the containers after starting the
daemon with `--userns-remap`.
##### Detailed information on `subuid`/`subgid` ranges
Given potential advanced use of the subordinate ID ranges by power users, the
following paragraphs define how the Docker daemon currently uses the range entries
found within the subordinate range files.
The simplest case is that only one contiguous range is defined for the
provided user or group. In this case, Docker will use that entire contiguous
range for the mapping of host uids and gids to the container process. This
means that the first ID in the range will be the remapped root user, and the
IDs above that initial ID will map host ID 1 through the end of the range.
From the example `/etc/subuid` content shown above, the remapped root
user would be uid 165536.
If the system administrator has set up multiple ranges for a single user or
group, the Docker daemon will read all the available ranges and use the
following algorithm to create the mapping ranges:
1. The range segments found for the particular user will be sorted by *start ID* ascending.
2. Map segments will be created from each range in increasing value with a length matching the length of each segment. Therefore the range segment with the lowest numeric starting value will be equal to the remapped root, and continue up through host uid/gid equal to the range segment length. As an example, if the lowest segment starts at ID 1000 and has a length of 100, then a map of 1000 -> 0 (the remapped root) up through 1100 -> 100 will be created from this segment. If the next segment starts at ID 10000, then the next map will start with mapping 10000 -> 101 up to the length of this second segment. This will continue until no more segments are found in the subordinate files for this user.
3. If more than five range segments exist for a single user, only the first five will be utilized, matching the kernel's limitation of only five entries in `/proc/self/uid_map` and `proc/self/gid_map`.
##### Disable user namespace for a container
If you enable user namespaces on the daemon, all containers are started
with user namespaces enabled. In some situations you might want to disable
this feature for a container, for example, to start a privileged container (see
[user namespace known restrictions](#user-namespace-known-restrictions)).
To enable those advanced features for a specific container use `--userns=host`
in the `run/exec/create` command.
This option will completely disable user namespace mapping for the container's user.
##### User namespace known restrictions
The following standard Docker features are currently incompatible when
running a Docker daemon with user namespaces enabled:
- sharing PID or NET namespaces with the host (`--pid=host` or `--net=host`)
- Using `--privileged` mode flag on `docker run` (unless also specifying `--userns=host`)
In general, user namespaces are an advanced feature and will require
coordination with other capabilities. For example, if volumes are mounted from
the host, file ownership will have to be pre-arranged if the user or
administrator wishes the containers to have expected access to the volume
contents. Note that when using external volume or graph driver plugins, those
external software programs must be made aware of user and group mapping ranges
if they are to work seamlessly with user namespace support.
Finally, while the `root` user inside a user namespaced container process has
many of the expected admin privileges that go along with being the superuser, the
Linux kernel has restrictions based on internal knowledge that this is a user namespaced
process. The most notable restriction that we are aware of at this time is the
inability to use `mknod`. Permission will be denied for device creation even as
container `root` inside a user namespace.
For details about how to use this feature, as well as limitations, see
[Isolate containers with a user namespace](https://docs.docker.com/engine/security/userns-remap/).
### Miscellaneous options
components/cli/docs/reference/commandline/exec.md
+11
View File
@@ -76,6 +76,17 @@ $ docker exec -it ubuntu_bash bash
This will create a new Bash session in the container `ubuntu_bash`.
Next, set an environment variable in the current bash session.
```bash
$ docker exec -it -e VAR=1 ubuntu_bash bash
```
This will create a new Bash session in the container `ubuntu_bash` with environment
variable `$VAR` set to "1". Note that this environment variable will only be valid
on the current Bash session.
### Try to run `docker exec` on a paused container
If the container is paused, then the `docker exec` command will fail with an error:
components/cli/docs/reference/commandline/ps.md
+31 -30
View File
@@ -82,20 +82,21 @@ than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bi
The currently supported filters are:
* id (container's id)
* label (`label=<key>` or `label=<key>=<value>`)
* name (container's name)
* exited (int - the code of exited containers. Only useful with `--all`)
* status (`created|restarting|running|removing|paused|exited|dead`)
* ancestor (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filters containers that were created from the given image or a descendant.
* before (container's id or name) - filters containers created before given id or name
* since (container's id or name) - filters containers created since given id or name
* isolation (`default|process|hyperv`) (Windows daemon only)
* volume (volume name or mount point) - filters containers that mount volumes.
* network (network id or name) - filters containers connected to the provided network
* health (starting|healthy|unhealthy|none) - filters containers based on healthcheck status
* publish=(container's published port) - filters published ports by containers
* expose=(container's exposed port) - filters exposed ports by containers
| Filter | Description |
|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------|
| `id` | container's ID |
| `name` | container's name |
| `label` | An arbitrary string representing either a key or a key-value pair |
| `exited` | An integer representing the container's exit code. Only useful with `--all`. |
| `status` | One of `created|restarting|running|removing|paused|exited|dead` |
| `ancestor` | Filters containers which share a given image as an ancestor. Expressed as `<image-name>[:<tag>]`, `<image id>`, or `<image@digest>` |
| `before` or `since` | Filters containers created before or after a given container ID or name |
| `volume` | Filters running containers which have mounted a given volume or bind mount. |
| `network` | Filters running containers connected to a given network. |
| `publish` or `expose` | Filters containers which publish or expose a given port. |
| `health` | One of `starting|healthy|unhealthy|none`. Filters containers based on their healthcheck status. |
| `isolation` | Windows daemon only. One of `default|process|hyperv`. |
#### label
@@ -387,21 +388,21 @@ template.
Valid placeholders for the Go template are listed below:
Placeholder | Description
--------------|----------------------------------------------------------------------------------------------------
`.ID` | Container ID
`.Image` | Image ID
`.Command` | Quoted command
`.CreatedAt` | Time when the container was created.
`.RunningFor` | Elapsed time since the container was started.
`.Ports` | Exposed ports.
`.Status` | Container status.
`.Size` | Container disk size.
`.Names` | Container names.
`.Labels` | All labels assigned to the container.
`.Label` | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'`
`.Mounts` | Names of the volumes mounted in this container.
`.Networks` | Names of the networks attached to this container.
| Placeholder | Description |
|:--------------|:------------------------------------------------------------------------------------------------|
| `.ID` | Container ID |
| `.Image` | Image ID |
| `.Command` | Quoted command |
| `.CreatedAt` | Time when the container was created. |
| `.RunningFor` | Elapsed time since the container was started. |
| `.Ports` | Exposed ports. |
| `.Status` | Container status. |
| `.Size` | Container disk size. |
| `.Names` | Container names. |
| `.Labels` | All labels assigned to the container. |
| `.Label` | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'` |
| `.Mounts` | Names of the volumes mounted in this container. |
| `.Networks` | Names of the networks attached to this container. |
When using the `--format` option, the `ps` command will either output the data
exactly as the template declares or, when using the `table` directive, includes
@@ -429,4 +430,4 @@ a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
01946d9d34d8
c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6
41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd
```
```
components/cli/docs/reference/commandline/service_create.md
+20 -2
View File
@@ -167,6 +167,8 @@ $ docker service create --name redis \
4cdgfyky7ozwh3htjfw0d12qv
```
To grant a service access to multiple secrets, use multiple `--secret` flags.
Secrets are located in `/run/secrets` in the container. If no target is
specified, the name of the secret will be used as the in memory file in the
container. If a target is specified, that will be the filename. In the
@@ -191,10 +193,26 @@ tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/).
### Set environment variables (-e, --env)
This sets environmental variables for all tasks in a service. For example:
This sets an environmental variable for all tasks in a service. For example:
```bash
$ docker service create --name redis_2 --replicas 5 --env MYVAR=foo redis:3.0.6
$ docker service create \
--name redis_2 \
--replicas 5 \
--env MYVAR=foo \
redis:3.0.6
```
To specify multiple environment variables, specify multiple `--env` flags, each
with a separate key-value pair.
```bash
$ docker service create \
--name redis_2 \
--replicas 5 \
--env MYVAR=foo \
--env MYVAR2=bar \
redis:3.0.6
```
### Create a service with specific hostname (--hostname)
components/cli/docs/reference/commandline/stack_deploy.md
+23 -2
View File
@@ -40,7 +40,7 @@ has to be run targeting a manager node.
### Compose file
The `deploy` command supports compose file version `3.0` and above."
The `deploy` command supports compose file version `3.0` and above.
```bash
$ docker stack deploy --compose-file docker-compose.yml vossibility
@@ -57,7 +57,28 @@ Creating service vossibility_ghollector
Creating service vossibility_lookupd
```
You can verify that the services were correctly created
Only a single Compose file is accepted. If your configuration is split between
multiple Compose files, e.g. a base configuration and environment-specific overrides,
you can combine these by passing them to `docker-compose config` with the `-f` option
and redirecting the merged output into a new file.
```bash
$ docker-compose -f docker-compose.yml -f docker-compose.prod.yml config > docker-stack.yml
$ docker stack deploy --compose-file docker-stack.yml vossibility
Ignoring unsupported options: links
Creating network vossibility_vossibility
Creating network vossibility_default
Creating service vossibility_nsqd
Creating service vossibility_logstash
Creating service vossibility_elasticsearch
Creating service vossibility_kibana
Creating service vossibility_ghollector
Creating service vossibility_lookupd
```
You can verify that the services were correctly created:
```bash
$ docker service ls
components/cli/docs/reference/run.md
+60 -59
View File
@@ -87,8 +87,9 @@ default foreground mode:
To start a container in detached mode, you use `-d=true` or just `-d` option. By
design, containers started in detached mode exit when the root process used to
run the container exits. A container in detached mode cannot be automatically
removed when it stops, this means you cannot use the `--rm` option with `-d` option.
run the container exits, unless you also specify the `--rm` option. If you use
`-d` with `--rm`, the container is removed when it exits **or** when the daemon
exits, whichever happens first.
Do not pass a `service x start` command to a detached container. For example, this
command attempts to start the `nginx` service.
@@ -149,7 +150,7 @@ is receiving its standard input from a pipe, as in:
The operator can identify a container in three ways:
| Identifier type | Example value |
| --------------------- | ------------------------------------------------------------------ |
|:----------------------|:-------------------------------------------------------------------|
| UUID long identifier | "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" |
| UUID short identifier | "f78375b1c487" |
| Name | "evil_ptolemy" |
@@ -686,29 +687,29 @@ parent group.
The operator can also adjust the performance parameters of the
container:
| Option | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `-m`, `--memory=""` | Memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. |
| `--memory-swap=""` | Total memory limit (memory + swap, format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. |
| `--memory-reservation=""` | Memory soft limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. |
| `--kernel-memory=""` | Kernel memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. |
| `-c`, `--cpu-shares=0` | CPU shares (relative weight) |
| `--cpus=0.000` | Number of CPUs. Number is a fractional number. 0.000 means no limit. |
| `--cpu-period=0` | Limit the CPU CFS (Completely Fair Scheduler) period |
| `--cpuset-cpus=""` | CPUs in which to allow execution (0-3, 0,1) |
| `--cpuset-mems=""` | Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. |
| `--cpu-quota=0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
| `--cpu-rt-period=0` | Limit the CPU real-time period. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. |
| `--cpu-rt-runtime=0` | Limit the CPU real-time runtime. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. |
| `--blkio-weight=0` | Block IO weight (relative weight) accepts a weight value between 10 and 1000. |
| `--blkio-weight-device=""` | Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`) |
| `--device-read-bps=""` | Limit read rate from a device (format: `<device-path>:<number>[<unit>]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. |
| `--device-write-bps=""` | Limit write rate to a device (format: `<device-path>:<number>[<unit>]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. |
| `--device-read-iops="" ` | Limit read rate (IO per second) from a device (format: `<device-path>:<number>`). Number is a positive integer. |
| `--device-write-iops="" ` | Limit write rate (IO per second) to a device (format: `<device-path>:<number>`). Number is a positive integer. |
| `--oom-kill-disable=false` | Whether to disable OOM Killer for the container or not. |
| `--oom-score-adj=0` | Tune container's OOM preferences (-1000 to 1000) |
| `--memory-swappiness=""` | Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. |
| Option | Description |
|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-m`, `--memory=""` | Memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. |
| `--memory-swap=""` | Total memory limit (memory + swap, format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. |
| `--memory-reservation=""` | Memory soft limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. |
| `--kernel-memory=""` | Kernel memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. |
| `-c`, `--cpu-shares=0` | CPU shares (relative weight) |
| `--cpus=0.000` | Number of CPUs. Number is a fractional number. 0.000 means no limit. |
| `--cpu-period=0` | Limit the CPU CFS (Completely Fair Scheduler) period |
| `--cpuset-cpus=""` | CPUs in which to allow execution (0-3, 0,1) |
| `--cpuset-mems=""` | Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. |
| `--cpu-quota=0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
| `--cpu-rt-period=0` | Limit the CPU real-time period. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. |
| `--cpu-rt-runtime=0` | Limit the CPU real-time runtime. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. |
| `--blkio-weight=0` | Block IO weight (relative weight) accepts a weight value between 10 and 1000. |
| `--blkio-weight-device=""` | Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`) |
| `--device-read-bps=""` | Limit read rate from a device (format: `<device-path>:<number>[<unit>]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. |
| `--device-write-bps=""` | Limit write rate to a device (format: `<device-path>:<number>[<unit>]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. |
| `--device-read-iops="" ` | Limit read rate (IO per second) from a device (format: `<device-path>:<number>`). Number is a positive integer. |
| `--device-write-iops="" ` | Limit write rate (IO per second) to a device (format: `<device-path>:<number>`). Number is a positive integer. |
| `--oom-kill-disable=false` | Whether to disable OOM Killer for the container or not. |
| `--oom-score-adj=0` | Tune container's OOM preferences (-1000 to 1000) |
| `--memory-swappiness=""` | Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. |
| `--shm-size=""` | Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. |
### User memory constraints
@@ -1158,7 +1159,7 @@ list of capabilities that are kept. The following table lists the Linux capabili
options which are allowed by default and can be dropped.
| Capability Key | Capability Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|:-----------------|:------------------------------------------------------------------------------------------------------------------------------|
| SETPCAP | Modify process capabilities. |
| MKNOD | Create special files using mknod(2). |
| AUDIT_WRITE | Write records to kernel auditing log. |
@@ -1176,31 +1177,31 @@ options which are allowed by default and can be dropped.
The next table shows the capabilities which are not granted by default and may be added.
| Capability Key | Capability Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| SYS_MODULE | Load and unload kernel modules. |
| SYS_RAWIO | Perform I/O port operations (iopl(2) and ioperm(2)). |
| SYS_PACCT | Use acct(2), switch process accounting on or off. |
| SYS_ADMIN | Perform a range of system administration operations. |
| SYS_NICE | Raise process nice value (nice(2), setpriority(2)) and change the nice value for arbitrary processes. |
| SYS_RESOURCE | Override resource Limits. |
| SYS_TIME | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock. |
| SYS_TTY_CONFIG | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals. |
| AUDIT_CONTROL | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. |
| MAC_OVERRIDE | Allow MAC configuration or state changes. Implemented for the Smack LSM. |
| MAC_ADMIN | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM). |
| NET_ADMIN | Perform various network-related operations. |
| SYSLOG | Perform privileged syslog(2) operations. |
| DAC_READ_SEARCH | Bypass file read permission checks and directory read and execute permission checks. |
| LINUX_IMMUTABLE | Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags. |
| NET_BROADCAST | Make socket broadcasts, and listen to multicasts. |
| IPC_LOCK | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). |
| IPC_OWNER | Bypass permission checks for operations on System V IPC objects. |
| SYS_PTRACE | Trace arbitrary processes using ptrace(2). |
| SYS_BOOT | Use reboot(2) and kexec_load(2), reboot and load a new kernel for later execution. |
| LEASE | Establish leases on arbitrary files (see fcntl(2)). |
| WAKE_ALARM | Trigger something that will wake up the system. |
| BLOCK_SUSPEND | Employ features that can block system suspend. |
| Capability Key | Capability Description |
|:----------------|:----------------------------------------------------------------------------------------------------------------|
| SYS_MODULE | Load and unload kernel modules. |
| SYS_RAWIO | Perform I/O port operations (iopl(2) and ioperm(2)). |
| SYS_PACCT | Use acct(2), switch process accounting on or off. |
| SYS_ADMIN | Perform a range of system administration operations. |
| SYS_NICE | Raise process nice value (nice(2), setpriority(2)) and change the nice value for arbitrary processes. |
| SYS_RESOURCE | Override resource Limits. |
| SYS_TIME | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock. |
| SYS_TTY_CONFIG | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals. |
| AUDIT_CONTROL | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. |
| MAC_OVERRIDE | Allow MAC configuration or state changes. Implemented for the Smack LSM. |
| MAC_ADMIN | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM). |
| NET_ADMIN | Perform various network-related operations. |
| SYSLOG | Perform privileged syslog(2) operations. |
| DAC_READ_SEARCH | Bypass file read permission checks and directory read and execute permission checks. |
| LINUX_IMMUTABLE | Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags. |
| NET_BROADCAST | Make socket broadcasts, and listen to multicasts. |
| IPC_LOCK | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). |
| IPC_OWNER | Bypass permission checks for operations on System V IPC objects. |
| SYS_PTRACE | Trace arbitrary processes using ptrace(2). |
| SYS_BOOT | Use reboot(2) and kexec_load(2), reboot and load a new kernel for later execution. |
| LEASE | Establish leases on arbitrary files (see fcntl(2)). |
| WAKE_ALARM | Trigger something that will wake up the system. |
| BLOCK_SUSPEND | Employ features that can block system suspend. |
Further reference information is available on the [capabilities(7) - Linux man page](http://man7.org/linux/man-pages/man7/capabilities.7.html)
@@ -1252,7 +1253,7 @@ the `--log-driver=VALUE` with the `docker run` command to configure the
container's logging driver. The following options are supported:
| Driver | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
|:------------|:------------------------------------------------------------------------------------------------------------------------------|
| `none` | Disables any logging for the container. `docker logs` won't be available with this driver. |
| `json-file` | Default logging driver for Docker. Writes JSON messages to file. No logging options are supported for this driver. |
| `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. |
@@ -1398,12 +1399,12 @@ container.
The following environment variables are set for Linux containers:
| Variable | Value |
| -------- | ----- |
| `HOME` | Set based on the value of `USER` |
| `HOSTNAME` | The hostname associated with the container |
| `PATH` | Includes popular directories, such as `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` |
| `TERM` | `xterm` if the container is allocated a pseudo-TTY |
| Variable | Value |
|:-----------|:-----------------------------------------------------------------------------------------------------|
| `HOME` | Set based on the value of `USER` |
| `HOSTNAME` | The hostname associated with the container |
| `PATH` | Includes popular directories, such as `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` |
| `TERM` | `xterm` if the container is allocated a pseudo-TTY |
Additionally, the operator can **set any environment variable** in the
components/cli/experimental/docker-stacks-and-bundles.md
-3
View File
@@ -161,21 +161,18 @@ A service has the following fields:
only specify the container port to be exposed. These ports can be
mapped on runtime hosts at the operator's discretion.
</dd>
<dt>
WorkingDir <code>string</code>
</dt>
<dd>
Working directory inside the service containers.
</dd>
<dt>
User <code>string</code>
</dt>
<dd>
Username or UID (format: <code>&lt;name|uid&gt;[:&lt;group|gid&gt;]</code>).
</dd>
<dt>
Networks <code>[]string</code>
</dt>
components/engine/api/swagger.yaml
+21
View File
@@ -7352,6 +7352,16 @@ paths:
AdvertiseAddr:
description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible."
type: "string"
DataPathAddr:
description: |
Address or interface to use for data path traffic (format: `<ip|interface>`), for example, `192.168.1.1`,
or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr`
is used.
The `DataPathAddr` specifies the address that global scope network drivers will publish towards other
nodes in order to reach the containers running on this node. Using this parameter it is possible to
separate the container data traffic from the management traffic of the cluster.
type: "string"
ForceNewCluster:
description: "Force creation of a new swarm."
type: "boolean"
@@ -7400,6 +7410,17 @@ paths:
type: "string"
AdvertiseAddr:
description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible."
type: "string"
DataPathAddr:
description: |
Address or interface to use for data path traffic (format: `<ip|interface>`), for example, `192.168.1.1`,
or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr`
is used.
The `DataPathAddr` specifies the address that global scope network drivers will publish towards other
nodes in order to reach the containers running on this node. Using this parameter it is possible to
separate the container data traffic from the management traffic of the cluster.
type: "string"
RemoteAddrs:
description: "Addresses of manager nodes already participating in the swarm."
components/engine/docs/api/version-history.md
+2
View File
@@ -29,6 +29,8 @@ keywords: "API, Docker, rcli, REST, documentation"
generate and rotate to a new CA certificate/key pair.
* `POST /service/create` and `POST /services/(id or name)/update` now take the field `Platforms` as part of the service `Placement`, allowing to specify platforms supported by the service.
* `POST /containers/(name)/wait` now accepts a `condition` query parameter to indicate which state change condition to wait for. Also, response headers are now returned immediately to acknowledge that the server has registered a wait callback for the client.
* `POST /swarm/init` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic
* `POST /swarm/join` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic
## v1.29 API changes