docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated CLI reference files

This commit is contained in:
gbarr01 2017-11-10 16:51:01 -08:00 committed by Gwendolynne Barr
parent e19223dd94
commit 23e525082a
21 changed files with 345 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
_data/engine-cli-edge/docker_build.yaml
View File

@ -406,35 +406,52 @@ examples: "### Build with PATH\n\n```bash\n$ docker build .\n\nUploading context
stage by name as a final stage for the resulting\nimage. Commands after the target
stage will be skipped.\n\n```Dockerfile\nFROM debian AS build-env\n...\n\nFROM alpine
AS production-env\n...\n```\n\n```bash\n$ docker build -t mybuildimage --target
build-env .\n```\n\n### Squash an image's layers (--squash) **Experimental Only**\n\n####
build-env .\n```\n\n### Squash an image's layers (--squash) (experimental)\n\n####
Overview\n\nOnce the image is built, squash the new layers into a new image with
a single\nnew layer. Squashing does not destroy any existing image, rather it creates
a new\nimage with the content of the squashed layers. This effectively makes it
look\nlike all `Dockerfile` commands were created with a single layer. The build\ncache
is preserved with this method.\n\n**Note**: using this option means the new image
will not be able to take\nadvantage of layer sharing with other images and may use
significantly more\nspace.\n\n**Note**: using this option you may see significantly
more space used due to\nstoring two copies of the image, one for the build cache
with all the cache\nlayers in tact, and one for the squashed version.\n\n#### Prerequisites\n\nThe
example on this page is using experimental mode in Docker 1.13.\n\nExperimental
is preserved with this method.\n\nThe `--squash` option is an experimental feature,
and should not be considered\nstable.\n\n\nSquashing layers can be beneficial if
your Dockerfile produces multiple layers\nmodifying the same files, for example,
file that are created in one step, and\nremoved in another step. For other use-cases,
squashing images may actually have\na negative impact on performance; when pulling
an image consisting of multiple\nlayers, layers can be pulled in parallel, and allows
sharing layers between\nimages (saving space).\n\nFor most use cases, multi-stage
are a better alternative, as they give more\nfine-grained control over your build,
and can take advantage of future\noptimizations in the builder. Refer to the [use
multi-stage builds](https://docs.docker.com/engine/userguide/eng-image/multistage-build/)\nsection
in the userguide for more information.\n\n\n#### Known limitations\n\nThe `--squash`
option has a number of known limitations:\n\n- When squashing layers, the resulting
image cannot take advantage of layer \n sharing with other images, and may use
significantly more space. Sharing the\n base image is still supported.\n- When
using this option you may see significantly more space used due to\n storing two
copies of the image, one for the build cache with all the cache\n layers in tact,
and one for the squashed version.\n- While squashing layers may produce smaller
images, it may have a negative\n impact on performance, as a single layer takes
longer to extract, and\n downloading a single layer cannot be paralellized.\n-
When attempting to squash an image that does not make changes to the\n filesystem
(for example, the Dockerfile only contains `ENV` instructions),\n the squash step
will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)\n\n####
Prerequisites\n\nThe example on this page is using experimental mode in Docker 1.13.\n\nExperimental
mode can be enabled by using the `--experimental` flag when starting the Docker
daemon or setting `experimental: true` in the `daemon.json` configuration file.\n\nBy
default, experimental mode is disabled. To see the current configuration, use the
`docker version` command.\n\n```none\n\nServer:\n Version: 1.13.1\n API version:
`docker version` command.\n\n```none\nServer:\n Version: 1.13.1\n API version:
\ 1.26 (minimum version 1.12)\n Go version: go1.7.5\n Git commit: 092cba3\n
Built: Wed Feb 8 06:35:24 2017\n OS/Arch: linux/amd64\n Experimental:
false\n\n [...]\n\n```\n\nTo enable experimental mode, users need to restart the
docker daemon with the experimental flag enabled.\n\n#### Enable Docker experimental\n\nExperimental
false\n\n [...]\n```\n\nTo enable experimental mode, users need to restart the docker
daemon with the experimental flag enabled.\n\n#### Enable Docker experimental\n\nExperimental
features are now included in the standard Docker binaries as of version 1.13.0.
For enabling experimental features, you need to start the Docker daemon with `--experimental`
flag. You can also enable the daemon flag via /etc/docker/daemon.json. e.g.\n\n```\n\n{\n
\ \"experimental\": true\n}\n\n```\nThen make sure the experimental flag is enabled:\n\n```bash\n\n$
docker version -f '{{.Server.Experimental}}'\ntrue\n\n```\n\n#### Build an image
with `--squash` argument\n\nThe following is an example of docker build with `--squash`
argument\n\n```Dockerfile\n\nFROM busybox\nRUN echo hello > /hello\nRUN echo world
>> /hello\nRUN touch remove_me /remove_me\nENV HELLO world\nRUN rm /remove_me\n\n```\nAn
image named `test` is built with `--squash` argument.\n\n```bash\n\n$ docker build
--squash -t test .\n\n[...]\n\n```\n\nIf everything is right, the history will look
flag. You can also enable the daemon flag via /etc/docker/daemon.json. e.g.\n\n```json\n{\n
\ \"experimental\": true\n}\n```\n\nThen make sure the experimental flag is enabled:\n\n```bash\n$
docker version -f '{{.Server.Experimental}}'\ntrue\n```\n\n#### Build an image with
`--squash` argument\n\nThe following is an example of docker build with `--squash`
argument\n\n```Dockerfile\nFROM busybox\nRUN echo hello > /hello\nRUN echo world
>> /hello\nRUN touch remove_me /remove_me\nENV HELLO world\nRUN rm /remove_me\n```\n\nAn
image named `test` is built with `--squash` argument.\n\n```bash\n$ docker build
--squash -t test .\n\n[...]\n```\n\nIf everything is right, the history will look
like this:\n\n```bash\n$ docker history test \n\nIMAGE CREATED CREATED
BY SIZE COMMENT\n4e10cb5b4cac
\ 3 seconds ago 12 B
@ -447,7 +464,7 @@ examples: "### Build with PATH\n\n```bash\n$ docker build .\n\nUploading context
/hello 0 B\n<missing> 6 minutes ago /bin/sh -c echo
hello > /hello 0 B\n<missing> 7 weeks ago /bin/sh
-c #(nop) CMD [\"sh\"] 0 B\n<missing> 7 weeks ago /bin/sh
-c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB\n\n```\nWe could find that all
-c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB\n```\n\nWe could find that all
layer's name is `<missing>`, and there is a new layer with COMMENT `merge`.\n\nTest
the image, check for `/remove_me` being gone, make sure `hello\\nworld` is in `/hello`,
make sure the `HELLO` envvar's value is `world`."

114
_data/engine-cli-edge/docker_service_create.yaml
View File

@ -645,7 +645,7 @@ examples: |-
<li><tt>default</tt>: Equivalent to <tt>consistent</tt>.</li>
<li><tt>consistent</tt>: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.</li>
<li><tt>cached</tt>: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.</li>
<li><tt>delegated</tt>: The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are are visible on the host.</li>
<li><tt>delegated</tt>: The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are visible on the host.</li>
</ul>
</p>
</td>
@ -880,27 +880,27 @@ examples: |-
<tr>
<td><tt>node.id</tt></td>
<td>Node ID</td>
<td><tt>node.id == 2ivku8v2gvtg4</tt></td>
<td><tt>node.id==2ivku8v2gvtg4</tt></td>
</tr>
<tr>
<td><tt>node.hostname</tt></td>
<td>Node hostname</td>
<td><tt>node.hostname != node-2</tt></td>
<td><tt>node.hostname!=node-2</tt></td>
</tr>
<tr>
<td><tt>node.role</tt></td>
<td>Node role</td>
<td><tt>node.role == manager</tt></td>
<td><tt>node.role==manager</tt></td>
</tr>
<tr>
<td><tt>node.labels</tt></td>
<td>user defined node labels</td>
<td><tt>node.labels.security == high</tt></td>
<td><tt>node.labels.security==high</tt></td>
</tr>
<tr>
<td><tt>engine.labels</tt></td>
<td>Docker Engine's labels</td>
<td><tt>engine.labels.operatingsystem == ubuntu 14.04</tt></td>
<td><tt>engine.labels.operatingsystem==ubuntu 14.04</tt></td>
</tr>
</table>
@ -1027,52 +1027,76 @@ examples: |-
### Publish service ports externally to the swarm (-p, --publish)
You can publish service ports to make them available externally to the swarm
using the `--publish` flag:
```bash
$ docker service create --publish <TARGET-PORT>:<SERVICE-PORT> nginx
```
For example:
using the `--publish` flag. The `--publish` flag can take two different styles
of arguments. The short version is positional, and allows you to specify the
target port and container port separated by a colon.
```bash
$ docker service create --name my_web --replicas 3 --publish 8080:80 nginx
```
When you publish a service port, the swarm routing mesh makes the service
accessible at the target port on every node regardless if there is a task for
the service running on the node. For more information refer to
There is also a long format, which is easier to read and allows you to specify
more options. The long format is preferred. You cannot specify the service's
mode when using the short format. Here is an example of using the long format
for the same service as above:
```bash
$ docker service create --name my_web --replicas 3 --publish target=8080,port=80 nginx
```
The options you can specify are:
<table>
<thead>
<tr>
<th>Option</th>
<th>Short syntax</th>
<th>Long syntax</th>
<th>Description</th>
</tr>
<tr>
<td>target and container port </td>
<td><tt></tt></td>
<td><tt></tt></td>
<td></td>
</tr>
<tr>
<td>protocol</td>
<td><tt>--publish 8080:80</tt></td>
<td><tt>--publish target=8080,port=80</tt></td>
<td><p>
The container port to publish and the target port to bind it to on the
routing mesh or directly on the node.
</p></td>
</tr>
<tr>
<td>mode</td>
<td>Not possible to set using short syntax.</td>
<td><tt>--publish target=8080,port=80,mode=host</tt></td>
<td><p>
The mode to use for binding the port, either `ingress` or `host`. Defaults
to `ingress` to use the routing mesh.
</p></td>
</tr>
<tr>
<td>protocol</td>
<td><tt>--publish 8080:80/tcp</tt></td>
<td><tt>--publish target=8080,port=80,protocol=tcp</tt></td>
<td><p>
The protocol to use, either `tcp` or `udp`. Defaults to `tcp`. To bind a
port for both protocols, specify the `-p` or `--publish` flag twice.
</p></td>
</tr>
</table>
When you publish a service port using `ingres` mode, the swarm routing mesh
makes the service accessible at the target port on every node regardless if
there is a task for the service running on the node. If you use `host` mode,
the port is only bound on nodes where the service is running, and a given port
on a node can only be bound once. You can only set the publication mode using
the long syntax. For more information refer to
[Use swarm mode routing mesh](https://docs.docker.com/engine/swarm/ingress/).
### Publish a port for TCP only or UDP only
By default, when you publish a port, it is a TCP port. You can
specifically publish a UDP port instead of or in addition to a TCP port. When
you publish both TCP and UDP ports, Docker 1.12.2 and earlier require you to
add the suffix `/tcp` for TCP ports. Otherwise it is optional.
#### TCP only
The following two commands are equivalent.
```bash
$ docker service create --name dns-cache -p 53:53 dns-cache
$ docker service create --name dns-cache -p 53:53/tcp dns-cache
```
#### TCP and UDP
```bash
$ docker service create --name dns-cache -p 53:53/tcp -p 53:53/udp dns-cache
```
#### UDP only
```bash
$ docker service create --name dns-cache -p 53:53/udp dns-cache
```
### Provide credential specs for managed service accounts (Windows only)
This option is only used for services using Windows containers. The

17
_data/engine-cli-edge/docker_service_update.yaml
View File

@ -176,7 +176,7 @@ options:
experimental: false
- option: host-add
value_type: list
description: Add or update a custom host-to-IP mapping (host:ip)
description: Add a custom host-to-IP mapping (host:ip)
deprecated: false
min_api_version: "1.25"
experimental: false
@ -535,6 +535,21 @@ examples: |-
myservice
```
### Add or remove port mappings
Use the `--port-add` or `--port-rm` flags to add or remove port mappings to or
from a service. You can use the short or long syntax discussed in the
[docker service update](service_create/#attach-a-service-to-an-existing-network-network)
reference.
The following example adds a port mapping to an existing service.
```bash
$ docker service update \
--port-add port=80,target=8080 \
myservice
```
### Roll back to the previous version of a service
Use the `--rollback` option to roll back to the previous version of the service.

2
_data/engine-cli-edge/docker_stats.yaml
View File

@ -4,6 +4,8 @@ long: |-
The `docker stats` command returns a live data stream for running containers. To limit data to one or more specific containers, specify a list of container names or ids separated by a space. You can specify a stopped container but stopped containers do not return any data.
If you want more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint.
> **Note**: On Linux, the Docker CLI reports memory usage by subtracting page cache usage from the total memory usage. The API does not perform such a calculation but rather provides the total memory usage and the amount from the page cache so that clients can use the data as needed.
usage: docker stats [OPTIONS] [CONTAINER...]
pname: docker
plink: docker.yaml

2
_data/engine-cli-edge/docker_system_prune.yaml
View File

@ -114,7 +114,7 @@ examples: |-
### Filtering
The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
The filtering flag (`--filter`) format is of "key=value". If there is more
than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
The currently supported filters are:

4
_data/engine-cli-edge/docker_trust.yaml
View File

@ -5,12 +5,16 @@ usage: docker trust
pname: docker
plink: docker.yaml
cname:
- docker trust key
- docker trust revoke
- docker trust sign
- docker trust signer
- docker trust view
clink:
- docker_trust_key.yaml
- docker_trust_revoke.yaml
- docker_trust_sign.yaml
- docker_trust_signer.yaml
- docker_trust_view.yaml
deprecated: false
experimental: false

15
_data/engine-cli-edge/docker_trust_key.yaml Normal file
View File

@ -0,0 +1,15 @@
command: docker trust key
short: Manage keys for signing Docker images (experimental)
long: Manage keys for signing Docker images (experimental)
usage: docker trust key
pname: docker trust
plink: docker_trust.yaml
cname:
- docker trust key generate
- docker trust key load
clink:
- docker_trust_key_generate.yaml
- docker_trust_key_load.yaml
deprecated: false
experimental: false

15
_data/engine-cli-edge/docker_trust_key_generate.yaml Normal file
View File

@ -0,0 +1,15 @@
command: docker trust key generate
short: Generate and load a signing key-pair
long: Generate and load a signing key-pair
usage: docker trust key generate NAME
pname: docker trust key
plink: docker_trust_key.yaml
options:
- option: dir
value_type: string
description: Directory to generate key in, defaults to current directory
deprecated: false
experimental: false
deprecated: false
experimental: false

16
_data/engine-cli-edge/docker_trust_key_load.yaml Normal file
View File

@ -0,0 +1,16 @@
command: docker trust key load
short: Load a private key file for signing
long: Load a private key file for signing
usage: docker trust key load [OPTIONS] KEYFILE
pname: docker trust key
plink: docker_trust_key.yaml
options:
- option: name
value_type: string
default_value: signer
description: Name for the loaded key
deprecated: false
experimental: false
deprecated: false
experimental: false

4
_data/engine-cli-edge/docker_trust_sign.yaml
View File

@ -19,7 +19,7 @@ examples: "### Sign a tag as a repo admin\n\nGiven an image:\n\n```bash\n$ docke
exists\na3fbb648f0bd: Layer already exists\n5eac2de68a97: Layer already exists\n8d4d1ab5ff74:
Layer already exists\nv2: digest: sha256:8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56
size: 1787\nSigning and pushing trust metadata\nEnter passphrase for repository
key with ID 36d4c36:\nSuccessfully signed \"docker.io/example/trust-demo\":v2\n```\n\n`docker
key with ID 36d4c36:\nSuccessfully signed docker.io/example/trust-demo:v2\n```\n\n`docker
trust view` lists the new signature:\n\n```bash\n$ docker trust view example/trust-demo\nSIGNED
TAG DIGEST SIGNERS\nv1
\ c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41
@ -37,7 +37,7 @@ examples: "### Sign a tag as a repo admin\n\nGiven an image:\n\n```bash\n$ docke
Layer already exists\n8a5132998025: Layer already exists\naca233ed29c3: Layer already
exists\ne5d2f035d7a4: Layer already exists\nv1: digest: sha256:74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4
size: 1357\nSigning and pushing trust metadata\nEnter passphrase for delegation
key with ID 27d42a8:\nSuccessfully signed \"docker.io/example/trust-demo\":v1\n```\n\n`docker
key with ID 27d42a8:\nSuccessfully signed docker.io/example/trust-demo:v1\n```\n\n`docker
trust view` lists the new signature:\n\n```bash\n$ docker trust view example/trust-demo\nSIGNED
TAG DIGEST SIGNERS\nv1
\ 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4

15
_data/engine-cli-edge/docker_trust_signer.yaml Normal file
View File

@ -0,0 +1,15 @@
command: docker trust signer
short: Manage entities who can sign Docker images (experimental)
long: Manage entities who can sign Docker images (experimental)
usage: docker trust signer
pname: docker trust
plink: docker_trust.yaml
cname:
- docker trust signer add
- docker trust signer remove
clink:
- docker_trust_signer_add.yaml
- docker_trust_signer_remove.yaml
deprecated: false
experimental: false

15
_data/engine-cli-edge/docker_trust_signer_add.yaml Normal file
View File

@ -0,0 +1,15 @@
command: docker trust signer add
short: Add a signer
long: Add a signer
usage: 'docker trust signer add OPTIONS NAME REPOSITORY [REPOSITORY...] '
pname: docker trust signer
plink: docker_trust_signer.yaml
options:
- option: key
value_type: list
description: Path to the signer's public key file
deprecated: false
experimental: false
deprecated: false
experimental: false

18
_data/engine-cli-edge/docker_trust_signer_remove.yaml Normal file
View File

@ -0,0 +1,18 @@
command: docker trust signer remove
short: Remove a signer
long: Remove a signer
usage: docker trust signer remove [OPTIONS] NAME REPOSITORY [REPOSITORY...]
pname: docker trust signer
plink: docker_trust_signer.yaml
options:
- option: force
shorthand: f
value_type: bool
default_value: "false"
description: |
Do not prompt for confirmation before removing the most recent signer
deprecated: false
experimental: false
deprecated: false
experimental: false

1
_data/engine-cli-edge/docker_unpause.yaml
View File

@ -13,6 +13,7 @@ plink: docker.yaml
examples: |-
```bash
$ docker unpause my_container
my_container
```
deprecated: false
experimental: false

12
_data/toc.yaml
View File

@ -1275,10 +1275,22 @@ reference:
section:
- path: /edge/engine/reference/commandline/trust/
title: docker trust
- path: /edge/engine/reference/commandline/trust_key/
title: docker trust key
- path: /edge/engine/reference/commandline/trust_key_generate/
title: docker trust key generate
- path: /edge/engine/reference/commandline/trust_key_load/
title: docker trust key load
- path: /edge/engine/reference/commandline/trust_revoke/
title: docker trust revoke
- path: /edge/engine/reference/commandline/trust_sign/
title: docker trust sign
- path: /edge/engine/reference/commandline/trust_signer/
title: docker trust signer
- path: /edge/engine/reference/commandline/trust_signer_add/
title: docker trust signer add
- path: /edge/engine/reference/commandline/trust_signer_remove/
title: docker trust signer remove
- path: /edge/engine/reference/commandline/trust_view/
title: docker trust view
- path: /edge/engine/reference/commandline/unpause/

18
edge/engine/reference/commandline/trust_key.md Normal file
View File

@ -0,0 +1,18 @@
---
datafolder: engine-cli-edge
datafile: docker_trust_key
title: docker trust key
---
<!--
Sorry, but the contents of this page are automatically generated from
Docker's source code. If you want to suggest a change to the text that appears
here, you'll need to find the string by searching this repo:
https://github.com/docker/cli
-->
{% if page.datafolder contains '-edge' %}
{% include edge_only.md section="cliref" %}
{% endif %}
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

18
edge/engine/reference/commandline/trust_key_generate.md Normal file
View File

@ -0,0 +1,18 @@
---
datafolder: engine-cli-edge
datafile: docker_trust_key_generate
title: docker trust key generate
---
<!--
Sorry, but the contents of this page are automatically generated from
Docker's source code. If you want to suggest a change to the text that appears
here, you'll need to find the string by searching this repo:
https://github.com/docker/cli
-->
{% if page.datafolder contains '-edge' %}
{% include edge_only.md section="cliref" %}
{% endif %}
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

18
edge/engine/reference/commandline/trust_key_load.md Normal file
View File

@ -0,0 +1,18 @@
---
datafolder: engine-cli-edge
datafile: docker_trust_key_load
title: docker trust key load
---
<!--
Sorry, but the contents of this page are automatically generated from
Docker's source code. If you want to suggest a change to the text that appears
here, you'll need to find the string by searching this repo:
https://github.com/docker/cli
-->
{% if page.datafolder contains '-edge' %}
{% include edge_only.md section="cliref" %}
{% endif %}
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

18
edge/engine/reference/commandline/trust_signer.md Normal file
View File

@ -0,0 +1,18 @@
---
datafolder: engine-cli-edge
datafile: docker_trust_signer
title: docker trust signer
---
<!--
Sorry, but the contents of this page are automatically generated from
Docker's source code. If you want to suggest a change to the text that appears
here, you'll need to find the string by searching this repo:
https://github.com/docker/cli
-->
{% if page.datafolder contains '-edge' %}
{% include edge_only.md section="cliref" %}
{% endif %}
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

18
edge/engine/reference/commandline/trust_signer_add.md Normal file
View File

@ -0,0 +1,18 @@
---
datafolder: engine-cli-edge
datafile: docker_trust_signer_add
title: docker trust signer add
---
<!--
Sorry, but the contents of this page are automatically generated from
Docker's source code. If you want to suggest a change to the text that appears
here, you'll need to find the string by searching this repo:
https://github.com/docker/cli
-->
{% if page.datafolder contains '-edge' %}
{% include edge_only.md section="cliref" %}
{% endif %}
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

18
edge/engine/reference/commandline/trust_signer_remove.md Normal file
View File

@ -0,0 +1,18 @@
---
datafolder: engine-cli-edge
datafile: docker_trust_signer_remove
title: docker trust signer remove
---
<!--
Sorry, but the contents of this page are automatically generated from
Docker's source code. If you want to suggest a change to the text that appears
here, you'll need to find the string by searching this repo:
https://github.com/docker/cli
-->
{% if page.datafolder contains '-edge' %}
{% include edge_only.md section="cliref" %}
{% endif %}
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}