diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 51b7f3a136..6fdd9e4aea 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,20 +5,25 @@ /build/ @crazy-max @jedevc @dvdksn -/compose/ @usha-mandya @aevesdocker +/compose/ @aevesdocker /desktop/ @aevesdocker -/docker-hub/ @jerae-duffin @craig-osterhout +/desktop/extensions/ @ChrisChinchilla + +/desktop/extensions-sdk/ @ChrisChinchilla + +/scout/ @ChrisChinchilla + +/docker-hub/ @aevesdocker @craig-osterhout /engine/ @dvdksn -/subscription/ @jerae-duffin +/subscription/ @aevesdocker -/docker-hub/publish/ @dvdksn +/docker-hub/publish/ @ChrisChinchilla -/docker-hub/official_images/ @dvdksn +/docker-hub/official_images/ @ChrisChinchilla /registry/ @dvdksn -/atomist/ @dvdksn diff --git a/.github/vale/Docker/Acronyms.yml b/.github/vale/Docker/Acronyms.yml index 5dd53743ac..b81e42c7e2 100644 --- a/.github/vale/Docker/Acronyms.yml +++ b/.github/vale/Docker/Acronyms.yml @@ -63,3 +63,5 @@ exceptions: - XSS - YAML - ZIP + - SBOM + - CVE diff --git a/.github/vale/Docker/ComplexWords.yml b/.github/vale/Docker/ComplexWords.yml index 7c4fb90cd3..03af01a343 100644 --- a/.github/vale/Docker/ComplexWords.yml +++ b/.github/vale/Docker/ComplexWords.yml @@ -63,6 +63,7 @@ swap: facilitate: ease females: women finalize: complete|finish + illustrate: show itemized: listed jeopardize: risk liaise: work with|partner with diff --git a/.github/vale/Docker/Contractions.yml b/.github/vale/Docker/Contractions.yml index a814a1c8e9..c378035da6 100644 --- a/.github/vale/Docker/Contractions.yml +++ b/.github/vale/Docker/Contractions.yml @@ -2,6 +2,8 @@ extends: substitution message: "Consider using '%s' instead of '%s'." level: warning ignorecase: true +action: + name: replace swap: are not: aren't cannot: can't diff --git a/.github/vale/Docker/Substitute.yml b/.github/vale/Docker/Substitute.yml index d44f28011b..9acd2d28a4 100644 --- a/.github/vale/Docker/Substitute.yml +++ b/.github/vale/Docker/Substitute.yml @@ -3,6 +3,8 @@ message: "Consider using '%s' instead of '%s'" link: https://docs.docker.com/contribute/style/recommended-words/ ignorecase: true level: suggestion +action: + name: replace swap: '\b(?:eg|e\.g\.)[\s,]': for example '\b(?:ie|i\.e\.)[\s,]': that is diff --git a/.github/vale/Vocab/Docker/accept.txt b/.github/vale/Vocab/Docker/accept.txt index d1b0f6466b..b8658768fc 100644 --- a/.github/vale/Vocab/Docker/accept.txt +++ b/.github/vale/Vocab/Docker/accept.txt @@ -1,4 +1,5 @@ (Certified|Verified) Publisher( Program)? +Docker-Sponsored Open Source Autotest BuildKit Docker diff --git a/.github/vale/Vocab/Industry/accept.txt b/.github/vale/Vocab/Industry/accept.txt index 6c4b090737..d8c8e7c152 100644 --- a/.github/vale/Vocab/Industry/accept.txt +++ b/.github/vale/Vocab/Industry/accept.txt @@ -1,6 +1,7 @@ ARM AWS Amazon +Ambassador Anchore Apple Artifactory @@ -9,6 +10,7 @@ BusyBox CentOS Ceph CloudFront +CNCF Codefresh CouchDB Couchbase @@ -17,6 +19,7 @@ Django Fargate Fedora Flink +Gefyra GeoNetwork GitHub( Actions)? Google @@ -54,6 +57,7 @@ Snyk Solr SonarQube Syft +Telepresence TLS Twilio Ubuntu @@ -62,5 +66,9 @@ Wasm Windows XWiki Zsh +kubefwd +ktunnel macOS minikube +sandbox +sandboxed \ No newline at end of file diff --git a/.github/vale/Vocab/Technology/accept.txt b/.github/vale/Vocab/Technology/accept.txt index 082df9686e..9d3d122a6d 100644 --- a/.github/vale/Vocab/Technology/accept.txt +++ b/.github/vale/Vocab/Technology/accept.txt @@ -1,4 +1,5 @@ APIs? +CVEs? DHCP DNS Ethernet @@ -13,6 +14,7 @@ JPEG MAC RPM PNG +SARIF SDKs? SSO TCP diff --git a/.github/workflows/merge.yml b/.github/workflows/merge.yml new file mode 100644 index 0000000000..d19f236a17 --- /dev/null +++ b/.github/workflows/merge.yml @@ -0,0 +1,31 @@ +name: merge + +# open or update publishing PR when there is a push to main +on: + workflow_dispatch: + push: + branches: + - main + +jobs: + main-to-published: + runs-on: ubuntu-22.04 + if: github.repository_owner == 'docker' + steps: + - uses: actions/checkout@v3 + with: + ref: published + - name: Reset published branch + run: | + git fetch origin main:main + git reset --hard main + - name: Create Pull Request + uses: peter-evans/create-pull-request@5b4a9f6a9e2af26e5f02351490b90d01eb8ec1e5 + with: + delete-branch: false + branch: published-update + commit-message: publish updates from main + labels: area/release + title: publish updates from main + body: | + Automated pull request for publishing docs updates. diff --git a/.github/workflows/validate-upstream.yml b/.github/workflows/validate-upstream.yml index cd19b6bf9e..19f70edfc0 100644 --- a/.github/workflows/validate-upstream.yml +++ b/.github/workflows/validate-upstream.yml @@ -16,6 +16,9 @@ on: data-files-folder: required: false type: string + data-files-placeholder-folder: + required: false + type: string jobs: run: @@ -64,7 +67,7 @@ jobs: yq _config.yml # cleanup js-yaml module and data files rm -rf ./node_modules - if [ -n "./_data/${{ inputs.data-files-folder }}" ]; then + if [[ -n "${{ inputs.data-files-folder }}" ]] && [[ -d "./_data/${{ inputs.data-files-folder }}" ]]; then rm -rf ./_data/${{ inputs.data-files-folder }}/* fi - @@ -73,7 +76,41 @@ jobs: if: ${{ inputs.data-files-id != '' && inputs.data-files-folder != '' }} with: name: ${{ inputs.data-files-id }} - path: ./_data/${{ inputs.data-files-folder }} + path: /tmp/_data/${{ inputs.data-files-folder }} + - + # Copy data files from /tmp/_data/${{ inputs.data-files-folder }} to + # _data/${{ inputs.data-files-folder }}. If data-files-placeholder-folder + # is set, then check if a placeholder file exists for each data file in + # that folder. If not, then creates a placeholder file with the same + # name as the data file, but with a .md extension. + name: Copy data files + if: ${{ inputs.data-files-id != '' && inputs.data-files-folder != '' }} + uses: actions/github-script@v6 + with: + script: | + const fs = require('fs'); + const path = require('path'); + const dataFilesPlaceholderFolder = `${{ inputs.data-files-placeholder-folder }}`; + const globber = await glob.create(`/tmp/_data/${{ inputs.data-files-folder }}/*.yaml`); + for await (const yamlSrcPath of globber.globGenerator()) { + const yamlSrcFilename = path.basename(yamlSrcPath); + const yamlDestPath = path.join('_data', `${{ inputs.data-files-folder }}`, yamlSrcFilename); + const placeholderPath = path.join(dataFilesPlaceholderFolder, yamlSrcFilename.replace(/^docker_/, '').replace(/\.yaml$/, '.md')); + if (dataFilesPlaceholderFolder !== '' && !fs.existsSync(placeholderPath)) { + const placeholderContent = `--- + datafolder: ${{ inputs.data-files-folder }} + datafile: ${yamlSrcFilename.replace(/\.[^/.]+$/, '')} + title: ${yamlSrcFilename.replace(/\.[^/.]+$/, "").replaceAll('_', ' ')} + --- + {% include cli.md datafolder=page.datafolder datafile=page.datafile %}`; + await core.group(`creating ${placeholderPath}`, async () => { + core.info(placeholderContent); + }); + await fs.writeFileSync(placeholderPath, placeholderContent); + } + core.info(`${yamlSrcPath} => ${yamlDestPath}`); + await fs.copyFileSync(yamlSrcPath, yamlDestPath); + } - name: Set up Docker Buildx uses: docker/setup-buildx-action@v2 diff --git a/Gemfile.lock b/Gemfile.lock index 6bdce6a01a..3d6ebe40f2 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -70,18 +70,16 @@ GEM mixlib-config (>= 2.2.1, < 4) mixlib-shellout mercenary (0.4.0) - mini_portile2 (2.8.0) mixlib-cli (2.1.8) mixlib-config (3.0.27) tomlrb mixlib-shellout (3.2.7) chef-utils - nokogiri (1.13.10) - mini_portile2 (~> 2.8.0) + nokogiri (1.14.3-aarch64-linux) racc (~> 1.4) - nokogiri (1.13.10-aarch64-linux) + nokogiri (1.14.3-arm-linux) racc (~> 1.4) - nokogiri (1.13.10-x86_64-linux) + nokogiri (1.14.3-x86_64-linux) racc (~> 1.4) octopress-hooks (2.6.2) jekyll (>= 2.0) @@ -89,7 +87,7 @@ GEM pathutil (0.16.2) forwardable-extended (~> 2.6) public_suffix (5.0.1) - racc (1.6.1) + racc (1.6.2) rainbow (3.1.1) rake (13.0.6) rb-fsevent (0.11.2) diff --git a/README.md b/README.md index a40ddb43c7..4470f80777 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ an existing issue. If possible, we recommend that you suggest a fix to the issue by creating a pull request. You can ask general questions and get community support through the [Docker -Community Slack](http://dockr.ly/slack). Personalized support is available +Community Slack](https://dockr.ly/comm-slack). Personalized support is available through the Docker Pro, Team, and Business subscriptions. See [Docker Pricing](https://www.docker.com/pricing) for details. @@ -30,11 +30,15 @@ repository. We've made it really easy for you to file new issues. -- Click **New issue** on the docs repository and fill in the details, or +- Click **[New issue](https://github.com/docker/docs/issues/new)** on the docs repository and fill in the details, or - Click **Request docs changes** in the right column of every page on - docs.docker.com and add the details. + [docs.docker.com](https://docs.docker.com/) and add the details, or -![Docs feedback on each page](/opensource/images/docs-site-feedback.png) + ![Request changes link](/assets/images/docs-site-feedback.png) + +- Click the **Give feedback** link on the side of every page in the docs. + + ![Docs feedback on each page](/assets/images/feedback-widget.png) ## Contribute to Docker docs @@ -45,4 +49,4 @@ contribute, see our [Contribute section](https://docs.docker.com/contribute/over ## Copyright and license -Copyright 2013-2023 Docker, inc, released under the Apache 2.0 license. +Copyright 2013-2023 Docker, inc, released under the Apache 2.0 license . diff --git a/_config.yml b/_config.yml index e96dbac572..cbbd0472bc 100644 --- a/_config.yml +++ b/_config.yml @@ -42,10 +42,10 @@ exclude: # Component versions -- address like site.docker_ce_version # You can't have - characters in these for non-YAML reasons. # When updating 'latest_engine_api_version', also update 'min_api_threshold' below. -latest_engine_api_version: "1.41" -docker_ce_version: "20.10" +latest_engine_api_version: "1.42" +docker_ce_version: "23.0.0" compose_v1_version: "1.29.2" -compose_version: "v2.15.1" +compose_version: "v2.17.2" compose_file_v3: "3.9" compose_file_v2: "2.4" machine_version: "0.16.0" @@ -153,7 +153,7 @@ defaults: fetch-remote: - repo: "https://github.com/docker/cli" default_branch: "master" - ref: "20.10" + ref: "23.0" paths: - dest: "engine/extend" src: @@ -171,12 +171,7 @@ fetch-remote: - repo: "https://github.com/docker/docker" default_branch: "master" - # The default branch has separate files for each API version, so we can - # consume the swagger files from that branch (we only publish the ones - # that have been released through the stubs in the engine/api/ directory). - # Using the default (master) branch allows for API docs changes to be - # published without them being cherry-picked into the release branch. - ref: "master" + ref: "23.0" paths: - dest: "engine/api" src: @@ -220,3 +215,50 @@ fetch-remote: - dest: "build/attestations/attestation-storage.md" src: - "docs/attestations/attestation-storage.md" + + - repo: "https://github.com/compose-spec/compose-spec" + default_branch: "master" + ref: "master" + paths: + - dest: "compose/compose-file/01-status.md" + src: + - "01-status.md" + - dest: "compose/compose-file/02-model.md" + src: + - "02-model.md" + - dest: "compose/compose-file/03-compose-file.md" + src: + - "03-compose-file.md" + - dest: "compose/compose-file/04-version-and-name.md" + src: + - "04-version-and-name.md" + - dest: "compose/compose-file/05-services.md" + src: + - "05-services.md" + - dest: "compose/compose-file/06-networks.md" + src: + - "06-networks.md" + - dest: "compose/compose-file/07-volumes.md" + src: + - "07-volumes.md" + - dest: "compose/compose-file/08-configs.md" + src: + - "08-configs.md" + - dest: "compose/compose-file/09-secrets.md" + src: + - "09-secrets.md" + - dest: "compose/compose-file/10-fragments.md" + src: + - "10-fragments.md" + - dest: "compose/compose-file/11-extension.md" + src: + - "11-extension.md" + - dest: "compose/compose-file/12-interpolation.md" + src: + - "12-interpolation.md" + - dest: "compose/compose-file/build.md" + src: + - "build.md" + - dest: "compose/compose-file/deploy.md" + src: + - "deploy.md" diff --git a/_data/buildx/docker_buildx_bake.yaml b/_data/buildx/docker_buildx_bake.yaml index 08a265e6c6..584f974df4 100644 --- a/_data/buildx/docker_buildx_bake.yaml +++ b/_data/buildx/docker_buildx_bake.yaml @@ -5,7 +5,7 @@ long: |- Bake is a high-level build command. Each specified target will run in parallel as part of the build. - Read [High-level build options with Bake](/build/customize/bake/) + Read [High-level build options with Bake](/build/bake/) guide for introduction to writing bake files. > **Note** @@ -85,6 +85,7 @@ options: - option: provenance value_type: string description: Shorthand for `--set=*.attest=type=provenance` + details_url: '#provenance' deprecated: false hidden: false experimental: false @@ -115,6 +116,7 @@ options: - option: sbom value_type: string description: Shorthand for `--set=*.attest=type=sbom` + details_url: '#sbom' deprecated: false hidden: false experimental: false @@ -184,7 +186,7 @@ examples: |- $ docker buildx bake -f docker-bake.dev.hcl db webapp-release ``` - See our [file definition](/build/customize/bake/file-definition/) + See our [file definition](/build/bake/file-definition/) guide for more details. ### Do not use cache when building the image (--no-cache) {#no-cache} @@ -222,10 +224,18 @@ examples: |- Same as [`build --progress`](buildx_build.md#progress). + ### Create provenance attestations (--provenance) {#provenance} + + Same as [`build --provenance`](buildx_build.md#provenance). + ### Always attempt to pull a newer version of the image (--pull) {#pull} Same as `build --pull`. + ### Create SBOM attestations (--sbom) {#sbom} + + Same as [`build --sbom`](buildx_build.md#sbom). + ### Override target configurations from command line (--set) {#set} ``` diff --git a/_data/buildx/docker_buildx_build.yaml b/_data/buildx/docker_buildx_build.yaml index 1807b494bb..a813ee1743 100644 --- a/_data/buildx/docker_buildx_build.yaml +++ b/_data/buildx/docker_buildx_build.yaml @@ -39,6 +39,7 @@ options: value_type: stringArray default_value: '[]' description: 'Attestation parameters (format: `type=sbom,generator=image`)' + details_url: '#attest' deprecated: false hidden: false experimental: false @@ -337,6 +338,7 @@ options: - option: provenance value_type: string description: Shortand for `--attest=type=provenance` + details_url: '#provenance' deprecated: false hidden: false experimental: false @@ -388,6 +390,7 @@ options: - option: sbom value_type: string description: Shorthand for `--attest=type=sbom` + details_url: '#sbom' deprecated: false hidden: false experimental: false @@ -494,6 +497,33 @@ inherited_options: kubernetes: false swarm: false examples: |- + ### Create attestations (--attest) {#attest} + + ``` + --attest=type=sbom,... + --attest=type=provenance,... + ``` + + Create [image attestations](/build/attestations/). + BuildKit currently supports: + + - `sbom` - Software Bill of Materials. + + Use `--attest=type=sbom` to generate an SBOM for an image at build-time. + Alternatively, you can use the [`--sbom` shorthand](#sbom). + + For more information, see [here](/build/attestations/sbom/). + + - `provenance` - SLSA Provenance + + Use `--attest=type=provenance` to generate provenance for an image at + build-time. Alternatively, you can use the [`--provenance` shorthand](#provenance). + + By default, a minimal provenance attestation will be created for the build + result, which will only be attached for images pushed to registries. + + For more information, see [here](/build/attestations/slsa-provenance/). + ### Allow extra privileged entitlement (--allow) {#allow} ``` @@ -815,8 +845,13 @@ examples: |- Set the target platform for the build. All `FROM` commands inside the Dockerfile without their own `--platform` flag will pull base images for this platform and - this value will also be the platform of the resulting image. The default value - will be the current platform of the buildkit daemon. + this value will also be the platform of the resulting image. + + The default value is the platform of the BuildKit daemon where the build runs. + The value takes the form of `os/arch` or `os/arch/variant`. For example, + `linux/amd64` or `linux/arm/v7`. Additionally, the `--platform` flag also supports + a special `local` value, which tells BuildKit to use the platform of the BuildKit + client that invokes the build. When using `docker-container` driver with `buildx`, this flag can accept multiple values as an input separated by a comma. With multiple values the result will be @@ -879,11 +914,41 @@ examples: |- > Check also our [Color output controls guide](https://github.com/docker/buildx/blob/master/docs/guides/color-output.md) > for modifying the colors that are used to output information to the terminal. + ### Create provenance attestations (--provenance) {#provenance} + + Shorthand for [`--attest=type=provenance`](#attest), used to configure + provenance attestations for the build result. For example, + `--provenance=mode=max` can be used as an abbreviation for + `--attest=type=provenance,mode=max`. + + Additionally, `--provenance` can be used with boolean values to broadly enable + or disable provenance attestations. For example, `--provenance=false` can be + used to disable all provenance attestations, while `--provenance=true` can be + used to enable all provenance attestations. + + By default, a minimal provenance attestation will be created for the build + result, which will only be attached for images pushed to registries. + + For more information, see [here](/build/attestations/slsa-provenance/). + ### Push the build result to a registry (--push) {#push} Shorthand for [`--output=type=registry`](#registry). Will automatically push the build result to registry. + ### Create SBOM attestations (--sbom) {#sbom} + + Shorthand for [`--attest=type=sbom`](#attest), used to configure SBOM + attestations for the build result. For example, + `--sbom=generator=/` can be used as an abbreviation for + `--attest=type=sbom,generator=/`. + + Additionally, `--sbom` can be used with boolean values to broadly enable or + disable SBOM attestations. For example, `--sbom=false` can be used to disable + all SBOM attestations. + + For more information, see [here](/build/attestations/sbom/). + ### Secret to expose to the build (--secret) {#secret} ``` diff --git a/_data/compose-cli/docker_compose.yaml b/_data/compose-cli/docker_compose.yaml index 9709ef880b..16b3d3fd9d 100644 --- a/_data/compose-cli/docker_compose.yaml +++ b/_data/compose-cli/docker_compose.yaml @@ -63,12 +63,19 @@ long: |- ### Use `-p` to specify a project name - Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t - specify the flag, Compose uses the current directory name. - Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable. - - Many Compose subcommands can be run without a Compose file by passing - the project name. + Each configuration has a project name. Compose sets the project name using + the following mechanisms, in order of precedence: + - The `-p` command line flag + - The `COMPOSE_PROJECT_NAME` environment variable + - The top level `name:` variable from the config file (or the last `name:` + from a series of config files specified using `-f`) + - The `basename` of the project directory containing the config file (or + containing the first config file specified using `-f`) + - The `basename` of the current directory if no config file is specified + Project names must contain only lowercase letters, decimal digits, dashes, + and underscores, and must begin with a lowercase letter or decimal digit. If + the `basename` of the project directory or current directory violates this + constraint, you must use one of the other mechanisms. ```console $ docker compose -p my_project ps -a @@ -89,13 +96,22 @@ long: |- Profiles can also be set by `COMPOSE_PROFILES` environment variable. + ### Configuring parallelism + + Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls. + Calling `docker compose --parallel 1 pull` will pull the pullable images defined in the Compose file + one at a time. This can also be used to control build concurrency. + + Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable. + ### Set up environment variables You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags. Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag, `COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag, - and `COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag. + `COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag + and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag. If flags are explicitly set on the command line, the associated environment variable is ignored. @@ -106,7 +122,7 @@ pname: docker plink: docker.yaml cname: - docker compose build - - docker compose convert + - docker compose config - docker compose cp - docker compose create - docker compose down @@ -132,7 +148,7 @@ cname: - docker compose version clink: - docker_compose_build.yaml - - docker_compose_convert.yaml + - docker_compose_config.yaml - docker_compose_cp.yaml - docker_compose_create.yaml - docker_compose_down.yaml @@ -178,8 +194,19 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: dry-run + value_type: bool + default_value: "false" + description: Execute command in dry run mode + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: env-file - value_type: string + value_type: stringArray + default_value: '[]' description: Specify an alternate environment file. deprecated: false hidden: false diff --git a/_data/compose-cli/docker_compose_alpha.yaml b/_data/compose-cli/docker_compose_alpha.yaml new file mode 100644 index 0000000000..a8a83b6e74 --- /dev/null +++ b/_data/compose-cli/docker_compose_alpha.yaml @@ -0,0 +1,17 @@ +command: docker compose alpha +short: Experimental commands +long: Experimental commands +pname: docker compose +plink: docker_compose.yaml +cname: + - docker compose alpha dry-run + - docker compose alpha watch +clink: + - docker_compose_alpha_dry-run.yaml + - docker_compose_alpha_watch.yaml +deprecated: false +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/_data/compose-cli/docker_compose_alpha_dry-run.yaml b/_data/compose-cli/docker_compose_alpha_dry-run.yaml new file mode 100644 index 0000000000..d489d39aeb --- /dev/null +++ b/_data/compose-cli/docker_compose_alpha_dry-run.yaml @@ -0,0 +1,14 @@ +command: docker compose alpha dry-run +short: | + EXPERIMENTAL - Dry run command allow you to test a command without applying changes +long: | + EXPERIMENTAL - Dry run command allow you to test a command without applying changes +usage: docker compose alpha dry-run -- [COMMAND...] +pname: docker compose alpha +plink: docker_compose_alpha.yaml +deprecated: false +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/_data/compose-cli/docker_compose_alpha_watch.yaml b/_data/compose-cli/docker_compose_alpha_watch.yaml new file mode 100644 index 0000000000..1aa5d9d2ee --- /dev/null +++ b/_data/compose-cli/docker_compose_alpha_watch.yaml @@ -0,0 +1,25 @@ +command: docker compose alpha watch +short: | + EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated +long: | + EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated +usage: docker compose alpha watch [SERVICE...] +pname: docker compose alpha +plink: docker_compose_alpha.yaml +options: + - option: quiet + value_type: bool + default_value: "false" + description: hide build output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/_data/compose-cli/docker_compose_build.yaml b/_data/compose-cli/docker_compose_build.yaml index efb0149b17..11049c99e3 100644 --- a/_data/compose-cli/docker_compose_build.yaml +++ b/_data/compose-cli/docker_compose_build.yaml @@ -106,6 +106,16 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: push + value_type: bool + default_value: "false" + description: Push service images. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: quiet shorthand: q value_type: bool diff --git a/_data/compose-cli/docker_compose_config.yaml b/_data/compose-cli/docker_compose_config.yaml new file mode 100644 index 0000000000..d05425e401 --- /dev/null +++ b/_data/compose-cli/docker_compose_config.yaml @@ -0,0 +1,138 @@ +command: docker compose config +aliases: docker compose config, docker compose convert +short: Parse, resolve and render compose file in canonical format +long: |- + `docker compose config` renders the actual data model to be applied on the Docker engine. + it merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into + the canonical format. +usage: docker compose config [OPTIONS] [SERVICE...] +pname: docker compose +plink: docker_compose.yaml +options: + - option: format + value_type: string + default_value: yaml + description: 'Format the output. Values: [yaml | json]' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: hash + value_type: string + description: Print the service config hash, one per line. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: images + value_type: bool + default_value: "false" + description: Print the image names, one per line. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-consistency + value_type: bool + default_value: "false" + description: | + Don't check model consistency - warning: may produce invalid Compose output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-interpolate + value_type: bool + default_value: "false" + description: Don't interpolate environment variables. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-normalize + value_type: bool + default_value: "false" + description: Don't normalize compose model. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: output + shorthand: o + value_type: string + description: Save to file (default to stdout) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: profiles + value_type: bool + default_value: "false" + description: Print the profile names, one per line. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only validate the configuration, don't print anything. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: resolve-image-digests + value_type: bool + default_value: "false" + description: Pin image tags to digests. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: services + value_type: bool + default_value: "false" + description: Print the service names, one per line. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volumes + value_type: bool + default_value: "false" + description: Print the volume names, one per line. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/compose-cli/docker_compose_create.yaml b/_data/compose-cli/docker_compose_create.yaml index 814c5cc394..1dfa25e376 100644 --- a/_data/compose-cli/docker_compose_create.yaml +++ b/_data/compose-cli/docker_compose_create.yaml @@ -57,6 +57,27 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: remove-orphans + value_type: bool + default_value: "false" + description: Remove containers for services not defined in the Compose file. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: scale + value_type: stringArray + default_value: '[]' + description: | + Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/compose-cli/docker_compose_logs.yaml b/_data/compose-cli/docker_compose_logs.yaml index c9afcc8129..f0163c02c3 100644 --- a/_data/compose-cli/docker_compose_logs.yaml +++ b/_data/compose-cli/docker_compose_logs.yaml @@ -47,6 +47,7 @@ options: kubernetes: false swarm: false - option: tail + shorthand: "n" value_type: string default_value: all description: | diff --git a/_data/compose-cli/docker_compose_ps.yaml b/_data/compose-cli/docker_compose_ps.yaml index 6325f285a1..d19346d18e 100644 --- a/_data/compose-cli/docker_compose_ps.yaml +++ b/_data/compose-cli/docker_compose_ps.yaml @@ -2,13 +2,20 @@ command: docker compose ps short: List containers long: |- Lists containers for a Compose project, with current status and exposed ports. - By default, both running and stopped containers are shown: ```console $ docker compose ps - NAME COMMAND SERVICE STATUS PORTS - example-bar-1 "/docker-entrypoint.…" bar exited (0) - example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp + NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS + example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp + ``` + + By default, only running containers are shown. `--all` flag can be used to include stopped containers + + ```console + $ docker compose ps --all + NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS + example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp + example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0) ``` usage: docker compose ps [OPTIONS] [SERVICE...] pname: docker compose @@ -139,12 +146,12 @@ examples: |- ```console $ docker compose ps --status=running - NAME COMMAND SERVICE STATUS PORTS - example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp + NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS + example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp $ docker compose ps --status=exited - NAME COMMAND SERVICE STATUS PORTS - example-bar-1 "/docker-entrypoint.…" bar exited (0) + NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS + example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0) ``` ### Filter containers by status (--filter) {#filter} @@ -155,12 +162,8 @@ examples: |- ```console $ docker compose ps --filter status=running - NAME COMMAND SERVICE STATUS PORTS - example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp - - $ docker compose ps --filter status=running - NAME COMMAND SERVICE STATUS PORTS - example-bar-1 "/docker-entrypoint.…" bar exited (0) + NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS + example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp ``` The `docker compose ps` command currently only supports the `--filter status=` diff --git a/_data/compose-cli/docker_compose_restart.yaml b/_data/compose-cli/docker_compose_restart.yaml index ea6c2628b8..91ba742e84 100644 --- a/_data/compose-cli/docker_compose_restart.yaml +++ b/_data/compose-cli/docker_compose_restart.yaml @@ -15,6 +15,16 @@ usage: docker compose restart [OPTIONS] [SERVICE...] pname: docker compose plink: docker_compose.yaml options: + - option: no-deps + value_type: bool + default_value: "false" + description: Don't restart dependent services. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: timeout shorthand: t value_type: int diff --git a/_data/compose-cli/docker_compose_run.yaml b/_data/compose-cli/docker_compose_run.yaml index 9d5715f4ea..97066f123f 100644 --- a/_data/compose-cli/docker_compose_run.yaml +++ b/_data/compose-cli/docker_compose_run.yaml @@ -172,6 +172,16 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: remove-orphans + value_type: bool + default_value: "false" + description: Remove containers for services not defined in the Compose file. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: rm value_type: bool default_value: "false" diff --git a/_data/compose-cli/docker_compose_up.yaml b/_data/compose-cli/docker_compose_up.yaml index f8ab468e7b..fb3dcb98cc 100644 --- a/_data/compose-cli/docker_compose_up.yaml +++ b/_data/compose-cli/docker_compose_up.yaml @@ -231,18 +231,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: timeout - shorthand: t - value_type: int - default_value: "10" - description: | - Use this timeout in seconds for container shutdown when attached or when containers are already running. - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - option: timestamps value_type: bool default_value: "false" @@ -263,6 +251,28 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: wait-timeout + value_type: int + default_value: "0" + description: timeout waiting for application to be running|healthy. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: waitTimeout + shorthand: t + value_type: int + default_value: "10" + description: | + Use this waitTimeout in seconds for container shutdown when attached or when containers are already running. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/docker-app/docker_app.yaml b/_data/docker-app/docker_app.yaml deleted file mode 100644 index 95cf64a731..0000000000 --- a/_data/docker-app/docker_app.yaml +++ /dev/null @@ -1,40 +0,0 @@ -command: docker app -short: Docker Application -long: A tool to build and manage Docker Applications. -pname: docker -plink: docker.yaml -cname: -- docker app bundle -- docker app completion -- docker app init -- docker app inspect -- docker app install -- docker app list -- docker app pull -- docker app push -- docker app render -- docker app status -- docker app uninstall -- docker app upgrade -- docker app validate -- docker app version -clink: -- docker_app_bundle.yaml -- docker_app_completion.yaml -- docker_app_init.yaml -- docker_app_inspect.yaml -- docker_app_install.yaml -- docker_app_list.yaml -- docker_app_pull.yaml -- docker_app_push.yaml -- docker_app_render.yaml -- docker_app_status.yaml -- docker_app_uninstall.yaml -- docker_app_upgrade.yaml -- docker_app_validate.yaml -- docker_app_version.yaml -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false diff --git a/_data/docker-app/docker_app_bundle.yaml b/_data/docker-app/docker_app_bundle.yaml deleted file mode 100644 index 87123ebdf2..0000000000 --- a/_data/docker-app/docker_app_bundle.yaml +++ /dev/null @@ -1,24 +0,0 @@ -command: docker app bundle -short: Create a CNAB invocation image and `bundle.json` for the application -long: Create a CNAB invocation image and `bundle.json` for the application -usage: docker app bundle [APP_NAME] [--output OUTPUT_FILE] -pname: docker app -plink: docker_app.yaml -options: -- option: output - shorthand: o - value_type: string - default_value: bundle.json - description: Output file (- for stdout) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app bundle myapp.dockerapp -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_completion.yaml b/_data/docker-app/docker_app_completion.yaml deleted file mode 100644 index be9d9b2a24..0000000000 --- a/_data/docker-app/docker_app_completion.yaml +++ /dev/null @@ -1,24 +0,0 @@ -command: docker app completion -short: Generates completion scripts for the specified shell (bash or zsh) -long: | - # Load the "docker app" completion code for bash into the current shell - . <(docker app completion bash) - # Set the "docker app" completion code for bash to autoload on startup in your ~/.bashrc, - # ~/.profile or ~/.bash_profile - . <(docker app completion bash) - # Note: bash-completion is needed. - - # Load the "docker app" completion code for zsh into the current shell - source <(docker app completion zsh) - # Set the "docker app" completion code for zsh to autoload on startup in your ~/.zshrc, - source <(docker app completion zsh) -usage: docker app completion SHELL -pname: docker app -plink: docker_app.yaml -examples: $ . <(docker app completion bash) -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_init.yaml b/_data/docker-app/docker_app_init.yaml deleted file mode 100644 index 4b68cc703f..0000000000 --- a/_data/docker-app/docker_app_init.yaml +++ /dev/null @@ -1,51 +0,0 @@ -command: docker app init -short: Initialize Docker Application definition -long: Start building a Docker Application package. If there is a docker-compose.yml - file in the current directory it will be copied and used. -usage: docker app init APP_NAME [--compose-file COMPOSE_FILE] [--description DESCRIPTION] - [--maintainer NAME:EMAIL ...] [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: compose-file - value_type: string - description: Compose file to use as application base (optional) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: description - value_type: string - description: Human readable description of your application (optional) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: maintainer - value_type: stringArray - default_value: '[]' - description: | - Name and email address of person responsible for the application (name:email) (optional) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: single-file - value_type: bool - default_value: "false" - description: Create a single-file Docker Application definition - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app init myapp --description "a useful description" -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_inspect.yaml b/_data/docker-app/docker_app_inspect.yaml deleted file mode 100644 index 406cad17c7..0000000000 --- a/_data/docker-app/docker_app_inspect.yaml +++ /dev/null @@ -1,52 +0,0 @@ -command: docker app inspect -short: Shows metadata, parameters and a summary of the Compose file for a given application -long: Shows metadata, parameters and a summary of the Compose file for a given application -usage: docker app inspect [APP_NAME] [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: insecure-registries - value_type: stringSlice - default_value: '[]' - description: | - Use HTTP instead of HTTPS when pulling from/pushing to those registries - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: parameters-file - value_type: stringArray - default_value: '[]' - description: Override parameters file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Pull the bundle - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: set - shorthand: s - value_type: stringArray - default_value: '[]' - description: Override parameter value - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app inspect myapp.dockerapp -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_install.yaml b/_data/docker-app/docker_app_install.yaml deleted file mode 100644 index 8862d54393..0000000000 --- a/_data/docker-app/docker_app_install.yaml +++ /dev/null @@ -1,115 +0,0 @@ -command: docker app install -aliases: deploy -short: Install an application -long: |- - Install an application. - By default, the application definition in the current directory will be - installed. The APP_NAME can also be: - - a path to a Docker Application definition (.dockerapp) or a CNAB bundle.json - - a registry Application Package reference -usage: docker app install [APP_NAME] [--name INSTALLATION_NAME] [--target-context - TARGET_CONTEXT] [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: credential-set - value_type: stringArray - default_value: '[]' - description: | - Use a YAML file containing a credential set or a credential set present in the credential store - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: insecure-registries - value_type: stringSlice - default_value: '[]' - description: | - Use HTTP instead of HTTPS when pulling from/pushing to those registries - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kubernetes-namespace - value_type: string - default_value: default - description: Kubernetes namespace to install into - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: name - value_type: string - description: Installation name (defaults to application name) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: orchestrator - value_type: string - description: Orchestrator to install on (swarm, kubernetes) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: parameters-file - value_type: stringArray - default_value: '[]' - description: Override parameters file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Pull the bundle - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: set - shorthand: s - value_type: stringArray - default_value: '[]' - description: Override parameter value - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: target-context - value_type: string - description: | - Context on which the application is installed (default: ) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: with-registry-auth - value_type: bool - default_value: "false" - description: Sends registry auth - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - $ docker app install myapp.dockerapp --name myinstallation --target-context=mycontext - $ docker app install myrepo/myapp:mytag --name myinstallation --target-context=mycontext - $ docker app install bundle.json --name myinstallation --credential-set=mycredentials.yml -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_list.yaml b/_data/docker-app/docker_app_list.yaml deleted file mode 100644 index b88ac9d0a5..0000000000 --- a/_data/docker-app/docker_app_list.yaml +++ /dev/null @@ -1,22 +0,0 @@ -command: docker app list -aliases: ls -short: List the installations and their last known installation result -long: List the installations and their last known installation result -usage: docker app list [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: target-context - value_type: string - description: List installations on this context - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_pull.yaml b/_data/docker-app/docker_app_pull.yaml deleted file mode 100644 index a9131af832..0000000000 --- a/_data/docker-app/docker_app_pull.yaml +++ /dev/null @@ -1,24 +0,0 @@ -command: docker app pull -short: Pull an application package from a registry -long: Pull an application package from a registry -usage: docker app pull NAME:TAG [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: insecure-registries - value_type: stringSlice - default_value: '[]' - description: | - Use HTTP instead of HTTPS when pulling from/pushing to those registries - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app pull docker/app-example:0.1.0 -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_push.yaml b/_data/docker-app/docker_app_push.yaml deleted file mode 100644 index e7b0ca69ae..0000000000 --- a/_data/docker-app/docker_app_push.yaml +++ /dev/null @@ -1,44 +0,0 @@ -command: docker app push -short: Push an application package to a registry -long: Push an application package to a registry -usage: docker app push [APP_NAME] --tag TARGET_REFERENCE [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: insecure-registries - value_type: stringSlice - default_value: '[]' - description: | - Use HTTP instead of HTTPS when pulling from/pushing to those registries - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: stringSlice - default_value: '[]' - description: | - For multi-arch service images, only push the specified platforms - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tag - shorthand: t - value_type: string - description: | - Target registry reference (default: : from metadata) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app push myapp --tag myrepo/myapp:mytag -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_render.yaml b/_data/docker-app/docker_app_render.yaml deleted file mode 100644 index f895b6c065..0000000000 --- a/_data/docker-app/docker_app_render.yaml +++ /dev/null @@ -1,72 +0,0 @@ -command: docker app render -short: Render the Compose file for an Application Package -long: Render the Compose file for an Application Package -usage: docker app render [APP_NAME] [--set KEY=VALUE ...] [--parameters-file PARAMETERS-FILE - ...] [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: formatter - value_type: string - default_value: yaml - description: Configure the output format (yaml|json) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: insecure-registries - value_type: stringSlice - default_value: '[]' - description: | - Use HTTP instead of HTTPS when pulling from/pushing to those registries - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: output - shorthand: o - value_type: string - default_value: '-' - description: Output file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: parameters-file - value_type: stringArray - default_value: '[]' - description: Override parameters file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Pull the bundle - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: set - shorthand: s - value_type: stringArray - default_value: '[]' - description: Override parameter value - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app render myapp.dockerapp --set key=value -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_status.yaml b/_data/docker-app/docker_app_status.yaml deleted file mode 100644 index f18a7c6c7e..0000000000 --- a/_data/docker-app/docker_app_status.yaml +++ /dev/null @@ -1,43 +0,0 @@ -command: docker app status -short: Get the installation status of an application -long: Get the installation status of an application. If the installation is a Docker - Application, the status shows the stack services. -usage: docker app status INSTALLATION_NAME [--target-context TARGET_CONTEXT] [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: credential-set - value_type: stringArray - default_value: '[]' - description: | - Use a YAML file containing a credential set or a credential set present in the credential store - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: target-context - value_type: string - description: | - Context on which the application is installed (default: ) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: with-registry-auth - value_type: bool - default_value: "false" - description: Sends registry auth - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app status myinstallation --target-context=mycontext -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_uninstall.yaml b/_data/docker-app/docker_app_uninstall.yaml deleted file mode 100644 index 230df867b3..0000000000 --- a/_data/docker-app/docker_app_uninstall.yaml +++ /dev/null @@ -1,51 +0,0 @@ -command: docker app uninstall -short: Uninstall an application -long: Uninstall an application -usage: docker app uninstall INSTALLATION_NAME [--target-context TARGET_CONTEXT] [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: credential-set - value_type: stringArray - default_value: '[]' - description: | - Use a YAML file containing a credential set or a credential set present in the credential store - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force - value_type: bool - default_value: "false" - description: Force removal of installation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: target-context - value_type: string - description: | - Context on which the application is installed (default: ) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: with-registry-auth - value_type: bool - default_value: "false" - description: Sends registry auth - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app uninstall myinstallation --target-context=mycontext -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_upgrade.yaml b/_data/docker-app/docker_app_upgrade.yaml deleted file mode 100644 index 13b4b83ee6..0000000000 --- a/_data/docker-app/docker_app_upgrade.yaml +++ /dev/null @@ -1,88 +0,0 @@ -command: docker app upgrade -short: Upgrade an installed application -long: Upgrade an installed application -usage: docker app upgrade INSTALLATION_NAME [--target-context TARGET_CONTEXT] [OPTIONS] -pname: docker app -plink: docker_app.yaml -options: -- option: app-name - value_type: string - description: Override the installation with another Application Package - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: credential-set - value_type: stringArray - default_value: '[]' - description: | - Use a YAML file containing a credential set or a credential set present in the credential store - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: insecure-registries - value_type: stringSlice - default_value: '[]' - description: | - Use HTTP instead of HTTPS when pulling from/pushing to those registries - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: parameters-file - value_type: stringArray - default_value: '[]' - description: Override parameters file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Pull the bundle - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: set - shorthand: s - value_type: stringArray - default_value: '[]' - description: Override parameter value - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: target-context - value_type: string - description: | - Context on which the application is installed (default: ) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: with-registry-auth - value_type: bool - default_value: "false" - description: Sends registry auth - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: $ docker app upgrade myinstallation --target-context=mycontext --set key=value -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_validate.yaml b/_data/docker-app/docker_app_validate.yaml deleted file mode 100644 index 4845676593..0000000000 --- a/_data/docker-app/docker_app_validate.yaml +++ /dev/null @@ -1,32 +0,0 @@ -command: docker app validate -short: Checks the rendered application is syntactically correct -long: Checks the rendered application is syntactically correct -usage: docker app validate [APP_NAME] [--set KEY=VALUE ...] [--parameters-file PARAMETERS_FILE] -pname: docker app -plink: docker_app.yaml -options: -- option: parameters-file - value_type: stringArray - default_value: '[]' - description: Override parameters file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: set - shorthand: s - value_type: stringArray - default_value: '[]' - description: Override parameter value - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/docker-app/docker_app_version.yaml b/_data/docker-app/docker_app_version.yaml deleted file mode 100644 index 860f75d77b..0000000000 --- a/_data/docker-app/docker_app_version.yaml +++ /dev/null @@ -1,12 +0,0 @@ -command: docker app version -short: Print version information -long: Print version information -usage: docker app version -pname: docker app -plink: docker_app.yaml -deprecated: true -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/engine-cli/docker.yaml b/_data/engine-cli/docker.yaml index dbd4b6b7db..12008d56d5 100644 --- a/_data/engine-cli/docker.yaml +++ b/_data/engine-cli/docker.yaml @@ -2,121 +2,235 @@ command: docker short: The base command for the Docker CLI. long: The base command for the Docker CLI. cname: -- docker attach -- docker build -- docker builder -- docker checkpoint -- docker commit -- docker config -- docker container -- docker context -- docker cp -- docker create -- docker diff -- docker events -- docker exec -- docker export -- docker history -- docker image -- docker images -- docker import -- docker info -- docker inspect -- docker kill -- docker load -- docker login -- docker logout -- docker logs -- docker manifest -- docker network -- docker node -- docker pause -- docker plugin -- docker port -- docker ps -- docker pull -- docker push -- docker rename -- docker restart -- docker rm -- docker rmi -- docker run -- docker save -- docker search -- docker secret -- docker service -- docker stack -- docker start -- docker stats -- docker stop -- docker swarm -- docker system -- docker tag -- docker top -- docker trust -- docker unpause -- docker update -- docker version -- docker volume -- docker wait + - docker attach + - docker build + - docker builder + - docker checkpoint + - docker commit + - docker config + - docker container + - docker context + - docker cp + - docker create + - docker diff + - docker events + - docker exec + - docker export + - docker history + - docker image + - docker images + - docker import + - docker info + - docker inspect + - docker kill + - docker load + - docker login + - docker logout + - docker logs + - docker manifest + - docker network + - docker node + - docker pause + - docker plugin + - docker port + - docker ps + - docker pull + - docker push + - docker rename + - docker restart + - docker rm + - docker rmi + - docker run + - docker save + - docker search + - docker secret + - docker service + - docker stack + - docker start + - docker stats + - docker stop + - docker swarm + - docker system + - docker tag + - docker top + - docker trust + - docker unpause + - docker update + - docker version + - docker volume + - docker wait clink: -- docker_attach.yaml -- docker_build.yaml -- docker_builder.yaml -- docker_checkpoint.yaml -- docker_commit.yaml -- docker_config.yaml -- docker_container.yaml -- docker_context.yaml -- docker_cp.yaml -- docker_create.yaml -- docker_diff.yaml -- docker_events.yaml -- docker_exec.yaml -- docker_export.yaml -- docker_history.yaml -- docker_image.yaml -- docker_images.yaml -- docker_import.yaml -- docker_info.yaml -- docker_inspect.yaml -- docker_kill.yaml -- docker_load.yaml -- docker_login.yaml -- docker_logout.yaml -- docker_logs.yaml -- docker_manifest.yaml -- docker_network.yaml -- docker_node.yaml -- docker_pause.yaml -- docker_plugin.yaml -- docker_port.yaml -- docker_ps.yaml -- docker_pull.yaml -- docker_push.yaml -- docker_rename.yaml -- docker_restart.yaml -- docker_rm.yaml -- docker_rmi.yaml -- docker_run.yaml -- docker_save.yaml -- docker_search.yaml -- docker_secret.yaml -- docker_service.yaml -- docker_stack.yaml -- docker_start.yaml -- docker_stats.yaml -- docker_stop.yaml -- docker_swarm.yaml -- docker_system.yaml -- docker_tag.yaml -- docker_top.yaml -- docker_trust.yaml -- docker_unpause.yaml -- docker_update.yaml -- docker_version.yaml -- docker_volume.yaml -- docker_wait.yaml + - docker_attach.yaml + - docker_build.yaml + - docker_builder.yaml + - docker_checkpoint.yaml + - docker_commit.yaml + - docker_config.yaml + - docker_container.yaml + - docker_context.yaml + - docker_cp.yaml + - docker_create.yaml + - docker_diff.yaml + - docker_events.yaml + - docker_exec.yaml + - docker_export.yaml + - docker_history.yaml + - docker_image.yaml + - docker_images.yaml + - docker_import.yaml + - docker_info.yaml + - docker_inspect.yaml + - docker_kill.yaml + - docker_load.yaml + - docker_login.yaml + - docker_logout.yaml + - docker_logs.yaml + - docker_manifest.yaml + - docker_network.yaml + - docker_node.yaml + - docker_pause.yaml + - docker_plugin.yaml + - docker_port.yaml + - docker_ps.yaml + - docker_pull.yaml + - docker_push.yaml + - docker_rename.yaml + - docker_restart.yaml + - docker_rm.yaml + - docker_rmi.yaml + - docker_run.yaml + - docker_save.yaml + - docker_search.yaml + - docker_secret.yaml + - docker_service.yaml + - docker_stack.yaml + - docker_start.yaml + - docker_stats.yaml + - docker_stop.yaml + - docker_swarm.yaml + - docker_system.yaml + - docker_tag.yaml + - docker_top.yaml + - docker_trust.yaml + - docker_unpause.yaml + - docker_update.yaml + - docker_version.yaml + - docker_volume.yaml + - docker_wait.yaml +options: + - option: config + value_type: string + default_value: /root/.docker + description: Location of client config files + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: context + shorthand: c + value_type: string + description: | + Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with `docker context use`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: debug + shorthand: D + value_type: bool + default_value: "false" + description: Enable debug mode + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: host + shorthand: H + value_type: list + description: Daemon socket(s) to connect to + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-level + shorthand: l + value_type: string + default_value: info + description: Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tls + value_type: bool + default_value: "false" + description: Use TLS; implied by --tlsverify + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tlscacert + value_type: string + default_value: /root/.docker/ca.pem + description: Trust certs signed only by this CA + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tlscert + value_type: string + default_value: /root/.docker/cert.pem + description: Path to TLS certificate file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tlskey + value_type: string + default_value: /root/.docker/key.pem + description: Path to TLS key file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tlsverify + value_type: bool + default_value: "false" + description: Use TLS and verify the remote + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_attach.yaml b/_data/engine-cli/docker_attach.yaml index e29783a11f..ef581befac 100644 --- a/_data/engine-cli/docker_attach.yaml +++ b/_data/engine-cli/docker_attach.yaml @@ -1,182 +1,198 @@ command: docker attach -short: Attach local standard input, output, and error streams to a running container +aliases: docker container attach, docker attach +short: | + Attach local standard input, output, and error streams to a running container long: |- - Use `docker attach` to attach your terminal's standard input, output, and error - (or any combination of the three) to a running container using the container's - ID or name. This allows you to view its ongoing output or to control it - interactively, as though the commands were running directly in your terminal. + Use `docker attach` to attach your terminal's standard input, output, and error + (or any combination of the three) to a running container using the container's + ID or name. This allows you to view its ongoing output or to control it + interactively, as though the commands were running directly in your terminal. - > **Note:** - > The `attach` command will display the output of the `ENTRYPOINT/CMD` process. This - > can appear as if the attach command is hung when in fact the process may simply - > not be interacting with the terminal at that time. + > **Note:** + > The `attach` command will display the output of the `ENTRYPOINT/CMD` process. This + > can appear as if the attach command is hung when in fact the process may simply + > not be interacting with the terminal at that time. - You can attach to the same contained process multiple times simultaneously, - from different sessions on the Docker host. + You can attach to the same contained process multiple times simultaneously, + 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 - the container. If the container was run with `-i` and `-t`, you can detach from - a container and leave it running using the `CTRL-p CTRL-q` key sequence. + 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 + the container. If the container was run with `-i` and `-t`, you can detach from + a container and leave it running using the `CTRL-p CTRL-q` key sequence. - > **Note:** - > A process running as PID 1 inside a container is treated specially by - > Linux: it ignores any signal with the default action. So, the process - > will not terminate on `SIGINT` or `SIGTERM` unless it is coded to do - > so. + > **Note:** + > A process running as PID 1 inside a container is treated specially by + > Linux: it ignores any signal with the default action. So, the process + > will not terminate on `SIGINT` or `SIGTERM` unless it is coded to do + > so. - It is forbidden to redirect the standard input of a `docker attach` command - while attaching to a TTY-enabled container (using the `-i` and `-t` options). + It is forbidden to redirect the standard input of a `docker attach` command + while attaching to a TTY-enabled container (using the `-i` and `-t` options). - While a client is connected to container's `stdio` using `docker attach`, Docker - uses a ~1MB memory buffer to maximize the throughput of the application. - Once this buffer is full, the speed of the API connection is affected, and so - this impacts the output process' writing speed. This is similar to other - applications like SSH. Because of this, it is not recommended to run - performance critical applications that generate a lot of output in the - foreground over a slow client connection. Instead, users should use the - `docker logs` command to get access to the logs. + While a client is connected to container's `stdio` using `docker attach`, Docker + uses a ~1MB memory buffer to maximize the throughput of the application. + Once this buffer is full, the speed of the API connection is affected, and so + this impacts the output process' writing speed. This is similar to other + applications like SSH. Because of this, it is not recommended to run + performance critical applications that generate a lot of output in the + foreground over a slow client connection. Instead, users should use the + `docker logs` command to get access to the logs. - ### Override the detach sequence + ### Override the detach sequence - If you want, you can configure an override the Docker key sequence for detach. - This is useful if the Docker default sequence conflicts with key sequence you - use for other applications. There are two ways to define your own detach key - sequence, as a per-container override or as a configuration property on your - entire configuration. + If you want, you can configure an override the Docker key sequence for detach. + This is useful if the Docker default sequence conflicts with key sequence you + use for other applications. There are two ways to define your own detach key + sequence, as a per-container override or as a configuration property on your + entire configuration. - To override the sequence for an individual container, use the - `--detach-keys=""` flag with the `docker attach` command. The format of - the `` is either a letter [a-Z], or the `ctrl-` combined with any of - the following: + To override the sequence for an individual container, use the + `--detach-keys=""` flag with the `docker attach` command. The format of + the `` is either a letter [a-Z], or the `ctrl-` combined with any of + the following: - * `a-z` (a single lowercase alpha character ) - * `@` (at sign) - * `[` (left bracket) - * `\\` (two backward slashes) - * `_` (underscore) - * `^` (caret) + * `a-z` (a single lowercase alpha character ) + * `@` (at sign) + * `[` (left bracket) + * `\\` (two backward slashes) + * `_` (underscore) + * `^` (caret) - These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key - sequences. To configure a different configuration default key sequence for all - containers, see [**Configuration file** section](cli.md#configuration-files). + These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key + sequences. To configure a different configuration default key sequence for all + containers, see [**Configuration file** section](cli.md#configuration-files). usage: docker attach [OPTIONS] CONTAINER pname: docker plink: docker.yaml options: -- option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-stdin - value_type: bool - default_value: "false" - description: Do not attach STDIN - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sig-proxy - value_type: bool - default_value: "true" - description: Proxy all received signals to the process - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: detach-keys + value_type: string + description: Override the key sequence for detaching a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-stdin + value_type: bool + default_value: "false" + description: Do not attach STDIN + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sig-proxy + value_type: bool + default_value: "true" + description: Proxy all received signals to the process + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Attach to and detach from a running container + ### Attach to and detach from a running container - The following example starts an ubuntu container running `top` in detached mode, - then attaches to the container; + The following example starts an ubuntu container running `top` in detached mode, + then attaches to the container; - ```console - $ docker run -d --name topdemo ubuntu:22.04 /usr/bin/top -b + ```console + $ docker run -d --name topdemo ubuntu:22.04 /usr/bin/top -b - $ docker attach topdemo + $ docker attach topdemo - top - 12:27:44 up 3 days, 21:54, 0 users, load average: 0.00, 0.00, 0.00 - Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - %Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.8 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st - MiB Mem : 3934.3 total, 770.1 free, 674.2 used, 2490.1 buff/cache - MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2814.0 avail Mem + top - 12:27:44 up 3 days, 21:54, 0 users, load average: 0.00, 0.00, 0.00 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + %Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.8 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st + MiB Mem : 3934.3 total, 770.1 free, 674.2 used, 2490.1 buff/cache + MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2814.0 avail Mem - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top - ``` + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top + ``` - As the container was started without the `-i`, and `-t` options, signals are - forwarded to the attached process, which means that the default `CTRL-p CTRL-q` - detach key sequence produces no effect, but pressing `CTRL-c` terminates the - container: + As the container was started without the `-i`, and `-t` options, signals are + forwarded to the attached process, which means that the default `CTRL-p CTRL-q` + detach key sequence produces no effect, but pressing `CTRL-c` terminates the + container: - ```console - <...> - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top^P^Q - ^C + ```console + <...> + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top^P^Q + ^C - $ docker ps -a --filter name=topdemo + $ docker ps -a --filter name=topdemo - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4cf0d0ebb079 ubuntu:22.04 "/usr/bin/top -b" About a minute ago Exited (0) About a minute ago topdemo - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 4cf0d0ebb079 ubuntu:22.04 "/usr/bin/top -b" About a minute ago Exited (0) About a minute ago topdemo + ``` - Repeating the example above, but this time with the `-i` and `-t` options set; + Repeating the example above, but this time with the `-i` and `-t` options set; - ```console - $ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b - ``` + ```console + $ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b + ``` - Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read - escape sequence"), the Docker CLI is handling the detach sequence, and the - `attach` command is detached from the container. Checking the container's status - with `docker ps` shows that the container is still running in the background: + Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read + escape sequence"), the Docker CLI is handling the detach sequence, and the + `attach` command is detached from the container. Checking the container's status + with `docker ps` shows that the container is still running in the background: - ```console - $ docker attach topdemo2 + ```console + $ docker attach topdemo2 - top - 12:44:32 up 3 days, 22:11, 0 users, load average: 0.00, 0.00, 0.00 - Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - %Cpu(s): 50.0 us, 0.0 sy, 0.0 ni, 50.0 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st - MiB Mem : 3934.3 total, 770.6 free, 672.4 used, 2491.4 buff/cache - MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2815.8 avail Mem + top - 12:44:32 up 3 days, 22:11, 0 users, load average: 0.00, 0.00, 0.00 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + %Cpu(s): 50.0 us, 0.0 sy, 0.0 ni, 50.0 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st + MiB Mem : 3934.3 total, 770.6 free, 672.4 used, 2491.4 buff/cache + MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2815.8 avail Mem - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 7180 2776 2452 R 0.0 0.1 0:00.02 topread escape sequence + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 7180 2776 2452 R 0.0 0.1 0:00.02 topread escape sequence - $ docker ps -a --filter name=topdemo2 + $ docker ps -a --filter name=topdemo2 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - b1661dce0fc2 ubuntu:22.04 "/usr/bin/top -b" 2 minutes ago Up 2 minutes topdemo2 - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + b1661dce0fc2 ubuntu:22.04 "/usr/bin/top -b" 2 minutes ago Up 2 minutes topdemo2 + ``` - ### Get the exit code of the container's command + ### Get the exit code of the container's command - And in this second example, you can see the exit code returned by the `bash` - process is returned by the `docker attach` command to its caller too: + And in this second example, you can see the exit code returned by the `bash` + process is returned by the `docker attach` command to its caller too: - ```console - $ docker run --name test -dit alpine - 275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab + ```console + $ docker run --name test -dit alpine + 275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab - $ docker attach test - /# exit 13 + $ docker attach test + /# exit 13 - $ echo $? - 13 + $ echo $? + 13 - $ docker ps -a --filter name=test + $ docker ps -a --filter name=test - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_build.yaml b/_data/engine-cli/docker_build.yaml index 43b6891f15..db54cf12ff 100644 --- a/_data/engine-cli/docker_build.yaml +++ b/_data/engine-cli/docker_build.yaml @@ -1,1017 +1,1011 @@ command: docker build +aliases: docker image build, docker build, docker buildx build, docker builder build short: Build an image from a Dockerfile long: |- - 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 `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*](/engine/reference/builder/#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. + The `URL` parameter can refer to three kinds of resources: Git repositories, + pre-packaged tarball contexts and plain text files. - ### Git repositories + ### Git repositories - When the `URL` parameter points to the location of a Git repository, the - repository acts as the build context. The system recursively fetches the - repository and its submodules. The commit history is not preserved. A - repository is first pulled into a temporary directory on your local host. After - that succeeds, the directory is sent to the Docker daemon as the context. - Local copy gives you the ability to access private repositories using local - user credentials, VPN's, and so forth. + When the `URL` parameter points to the location of a Git repository, the + repository acts as the build context. The system recursively fetches the + repository and its submodules. The commit history is not preserved. A + repository is first pulled into a temporary directory on your local host. After + that succeeds, the directory is sent to the Docker daemon as the context. + Local copy gives you the ability to access private repositories using local + user credentials, VPN's, and so forth. - > **Note** - > - > If the `URL` parameter contains a fragment the system will recursively clone - > the repository and its submodules using a `git clone --recursive` command. + > **Note** + > + > If the `URL` parameter contains a fragment the system will recursively clone + > the repository and its submodules using a `git clone --recursive` command. - Git URLs accept context configuration in their fragment section, separated by a - colon (`:`). The first part represents the reference that Git will check out, - 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. + Git URLs accept context configuration in their fragment section, separated by a + colon (`:`). The first part represents the reference that Git will check out, + 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. - For example, run this command to use a directory called `docker` in the branch - `container`: + For example, run this command to use a directory called `docker` in the branch + `container`: - ```console - $ docker build https://github.com/docker/rootfs.git#container:docker - ``` + ```console + $ docker build https://github.com/docker/rootfs.git#container:docker + ``` - The following table represents all the valid suffixes with their build - contexts: + The following table represents all the valid suffixes with their build + contexts: - | Build Syntax Suffix | Commit Used | Build Context Used | - |--------------------------------|-----------------------|--------------------| - | `myrepo.git` | `refs/heads/master` | `/` | - | `myrepo.git#mytag` | `refs/tags/mytag` | `/` | - | `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` | - | `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` | - | `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` | - | `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` | - | `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` | - | `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` | + | Build Syntax Suffix | Commit Used | Build Context Used | + |--------------------------------|-----------------------|--------------------| + | `myrepo.git` | `refs/heads/master` | `/` | + | `myrepo.git#mytag` | `refs/tags/mytag` | `/` | + | `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` | + | `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` | + | `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` | + | `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` | + | `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` | + | `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` | - > **Note** - > - > You cannot specify the build-context directory (`myfolder` in the examples above) - > when using BuildKit as builder (`DOCKER_BUILDKIT=1`). Support for this feature - > is tracked in [buildkit#1684](https://github.com/moby/buildkit/issues/1684). + ### Tarball contexts - ### Tarball contexts + If you pass an URL to a remote tarball, the URL itself is sent to the daemon: - If you pass an URL to a remote tarball, the URL itself is sent to the daemon: + ```console + $ docker build http://server/context.tar.gz + ``` - ```console - $ docker build http://server/context.tar.gz - ``` + The download operation will be performed on the host the Docker daemon is + running on, which is not necessarily the same host from which the build command + is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the + build context. Tarball contexts must be tar archives conforming to the standard + `tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2', + 'gzip' or 'identity' (no compression) formats. - The download operation will be performed on the host the Docker daemon is - running on, which is not necessarily the same host from which the build command - is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the - build context. Tarball contexts must be tar archives conforming to the standard - `tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2', - 'gzip' or 'identity' (no compression) formats. + ### Text files - ### Text files + Instead of specifying a context, you can pass a single `Dockerfile` in the + `URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`: - Instead of specifying a context, you can pass a single `Dockerfile` in the - `URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`: + ```console + $ docker build - < Dockerfile + ``` - ```console - $ docker build - < Dockerfile - ``` + With Powershell on Windows, you can run: - With Powershell on Windows, you can run: + ```powershell + Get-Content Dockerfile | docker build - + ``` - ```powershell - Get-Content Dockerfile | docker build - - ``` + If you use `STDIN` or specify a `URL` pointing to a plain text file, the system + places the contents into a file called `Dockerfile`, and any `-f`, `--file` + option is ignored. In this scenario, there is no context. - If you use `STDIN` or specify a `URL` pointing to a plain text file, the system - places the contents into a file called `Dockerfile`, and any `-f`, `--file` - option is ignored. In this scenario, there is no context. + By default the `docker build` command will look for a `Dockerfile` at the root + of the build context. The `-f`, `--file`, option lets you specify the path to + an alternative file to use instead. This is useful in cases where the same set + of files are used for multiple builds. The path must be to a file within the + build context. If a relative path is specified then it is interpreted as + relative to the root of the context. - By default the `docker build` command will look for a `Dockerfile` at the root - of the build context. The `-f`, `--file`, option lets you specify the path to - an alternative file to use instead. This is useful in cases where the same set - of files are used for multiple builds. The path must be to a file within the - build context. If a relative path is specified then it is interpreted as - relative to the root of the context. + In most cases, it's best to put each Dockerfile in an empty directory. Then, + add to that directory only the files needed for building the Dockerfile. To + increase the build's performance, you can exclude files and directories by + adding a `.dockerignore` file to that directory as well. For information on + creating one, see the [.dockerignore file](/engine/reference/builder/#dockerignore-file). - In most cases, it's best to put each Dockerfile in an empty directory. Then, - add to that directory only the files needed for building the Dockerfile. To - increase the build's performance, you can exclude files and directories by - adding a `.dockerignore` file to that directory as well. For information on - creating one, see the [.dockerignore file](../builder.md#dockerignore-file). - - If the Docker client loses connection to the daemon, the build is canceled. - This happens if you interrupt the Docker client with `CTRL-c` or if the Docker - client is killed for any reason. If the build initiated a pull which is still - running at the time the build is cancelled, the pull is cancelled as well. + If the Docker client loses connection to the daemon, the build is canceled. + This happens if you interrupt the Docker client with `CTRL-c` or if the Docker + client is killed for any reason. If the build initiated a pull which is still + running at the time the build is cancelled, the pull is cancelled as well. usage: docker build [OPTIONS] PATH | URL | - pname: docker plink: docker.yaml options: -- option: add-host - value_type: list - description: Add a custom host-to-IP mapping (host:ip) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: build-arg - value_type: list - description: Set build-time variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cache-from - value_type: stringSlice - default_value: '[]' - description: Images to consider as cache sources - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroup-parent - value_type: string - description: Optional parent cgroup for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: compress - value_type: bool - default_value: "false" - description: Compress the build context using gzip - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit the CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit the CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: file - shorthand: f - value_type: string - description: Name of the Dockerfile (Default is 'PATH/Dockerfile') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force-rm - value_type: bool - default_value: "false" - description: Always remove intermediate containers - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: iidfile - value_type: string - description: Write the image ID to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Container isolation technology - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - value_type: list - description: Set metadata for an image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: string - default_value: default - description: | - Set the networking mode for the RUN instructions during build - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-cache - value_type: bool - default_value: "false" - description: Do not use cache when building the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: output - shorthand: o - value_type: stringArray - default_value: '[]' - description: 'Output destination (format: type=local,dest=path)' - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.38" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: progress - value_type: string - default_value: auto - description: | - Set type of progress output (auto, plain, tty). Use plain to show container output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Always attempt to pull a newer version of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress the build output and print image ID on success - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rm - value_type: bool - default_value: "true" - description: Remove intermediate containers after a successful build - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: secret - value_type: stringArray - default_value: '[]' - description: | - Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret - deprecated: false - min_api_version: "1.39" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: security-opt - value_type: stringSlice - default_value: '[]' - description: Security options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: shm-size - value_type: bytes - default_value: "0" - description: Size of /dev/shm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: squash - value_type: bool - default_value: "false" - description: Squash newly built layers into a single new layer - deprecated: false - min_api_version: "1.25" - experimental: true - experimentalcli: false - kubernetes: false - swarm: false -- option: ssh - value_type: stringArray - default_value: '[]' - description: | - SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|[=|[,]]) - deprecated: false - min_api_version: "1.39" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stream - value_type: bool - default_value: "false" - description: Stream attaches to server to negotiate build context - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tag - shorthand: t - value_type: list - description: Name and optionally a tag in the 'name:tag' format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: target - value_type: string - description: Set the target build stage to build. - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: ulimit - default_value: '[]' - description: Ulimit options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: add-host + value_type: list + description: Add a custom host-to-IP mapping (`host:ip`) + details_url: '#add-host' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: build-arg + value_type: list + description: Set build-time variables + details_url: '#build-arg' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cache-from + value_type: stringSlice + default_value: '[]' + description: Images to consider as cache sources + details_url: '#cache-from' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + details_url: '#cgroup-parent' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: compress + value_type: bool + default_value: "false" + description: Compress the build context using gzip + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: file + shorthand: f + value_type: string + description: Name of the Dockerfile (Default is `PATH/Dockerfile`) + details_url: '#file' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force-rm + value_type: bool + default_value: "false" + description: Always remove intermediate containers + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: iidfile + value_type: string + description: Write the image ID to the file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Container isolation technology + details_url: '#isolation' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + value_type: list + description: Set metadata for an image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: 'Swap limit equal to memory plus swap: -1 to enable unlimited swap' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: string + default_value: default + description: Set the networking mode for the RUN instructions during build + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-cache + value_type: bool + default_value: "false" + description: Do not use cache when building the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.38" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pull + value_type: bool + default_value: "false" + description: Always attempt to pull a newer version of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the build output and print image ID on success + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rm + value_type: bool + default_value: "true" + description: Remove intermediate containers after a successful build + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: security-opt + value_type: stringSlice + default_value: '[]' + description: Security options + details_url: '#security-opt' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: shm-size + value_type: bytes + default_value: "0" + description: Size of `/dev/shm` + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: squash + value_type: bool + default_value: "false" + description: Squash newly built layers into a single new layer + details_url: '#squash' + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: true + experimentalcli: false + kubernetes: false + swarm: false + - option: tag + shorthand: t + value_type: list + description: Name and optionally a tag in the `name:tag` format + details_url: '#tag' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: target + value_type: string + description: Set the target build stage to build. + details_url: '#target' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + details_url: '#ulimit' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Build with PATH - - ```console - $ docker build . - - Uploading context 10240 bytes - Step 1/3 : FROM busybox - Pulling repository busybox - ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/ - Step 2/3 : RUN ls -lh / - ---> Running in 9c9e81692ae9 - total 24 - drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin - drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev - drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc - drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib - lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib - dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc - lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin - dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys - drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp - drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr - ---> b35f4035db3f - Step 3/3 : CMD echo Hello world - ---> Running in 02071fceb21b - ---> f52f38b7823e - Successfully built f52f38b7823e - Removing intermediate container 9c9e81692ae9 - Removing intermediate container 02071fceb21b - ``` - - This example specifies that the `PATH` is `.`, and so all the files in the - local directory get `tar`d and sent to the Docker daemon. The `PATH` specifies - where to find the files for the "context" of the build on the Docker daemon. - Remember that the daemon could be running on a remote machine and that no - parsing of the Dockerfile happens at the client side (where you're running - `docker build`). That means that *all* the files at `PATH` get sent, not just - the ones listed to [*ADD*](../builder.md#add) in the Dockerfile. - - The transfer of context from the local machine to the Docker daemon is what the - `docker` client means when you see the "Sending build context" message. - - If you wish to keep the intermediate containers after the build is complete, - you must use `--rm=false`. This does not affect the build cache. - - ### Build with URL - - ```console - $ docker build github.com/creack/docker-firefox - ``` - - This will clone the GitHub repository and use the cloned repository as context. - The Dockerfile at the root of the repository is used as Dockerfile. You can - specify an arbitrary Git repository by using the `git://` or `git@` scheme. - - ```console - $ docker build -f ctx/Dockerfile http://server/ctx.tar.gz - - Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B - Step 1/3 : FROM busybox - ---> 8c2e06607696 - Step 2/3 : ADD ctx/container.cfg / - ---> e7829950cee3 - Removing intermediate container b35224abf821 - Step 3/3 : CMD /bin/ls - ---> Running in fbc63d321d73 - ---> 3286931702ad - Removing intermediate container fbc63d321d73 - Successfully built 377c409b35e4 - ``` - - This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which - downloads and extracts the referenced tarball. The `-f ctx/Dockerfile` - parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used - to build the image. Any `ADD` commands in that `Dockerfile` that refers to local - paths must be relative to the root of the contents inside `ctx.tar.gz`. In the - example above, the tarball contains a directory `ctx/`, so the `ADD - ctx/container.cfg /` operation works as expected. - - ### Build with - - - ```console - $ docker build - < Dockerfile - ``` - - This will read a Dockerfile from `STDIN` without context. Due to the lack of a - context, no contents of any local directory will be sent to the Docker daemon. - Since there is no context, a Dockerfile `ADD` only works if it refers to a - remote URL. - - ```console - $ docker build - < context.tar.gz - ``` - - This will build an image for a compressed context read from `STDIN`. Supported - formats are: bzip2, gzip and xz. - - ### Use a .dockerignore file - - ```console - $ docker build . - - Uploading context 18.829 MB - Uploading context - Step 1/2 : FROM busybox - ---> 769b9341d937 - Step 2/2 : CMD echo Hello world - ---> Using cache - ---> 99cc1ad10469 - Successfully built 99cc1ad10469 - $ echo ".git" > .dockerignore - $ docker build . - Uploading context 6.76 MB - Uploading context - Step 1/2 : FROM busybox - ---> 769b9341d937 - Step 2/2 : CMD echo Hello world - ---> Using cache - ---> 99cc1ad10469 - Successfully built 99cc1ad10469 - ``` - - This example shows the use of the `.dockerignore` file to exclude the `.git` - directory from the context. Its effect can be seen in the changed size of the - uploaded context. The builder reference contains detailed information on - [creating a .dockerignore file](../builder.md#dockerignore-file). - - When using the [BuildKit backend](https://docs.docker.com/build/buildkit/), - `docker build` searches for a `.dockerignore` file relative to the Dockerfile - name. For example, running `docker build -f myapp.Dockerfile .` will first look - for an ignore file named `myapp.Dockerfile.dockerignore`. If such a file is not - found, the `.dockerignore` file is used if present. Using a Dockerfile based - `.dockerignore` is useful if a project contains multiple Dockerfiles that - expect to ignore different sets of files. - - - ### Tag an image (-t, --tag) - - ```console - $ docker build -t vieux/apache:2.0 . - ``` - - This will build like the previous example, but it will then tag the resulting - image. The repository name will be `vieux/apache` and the tag will be `2.0`. - [Read more about valid tags](tag.md). - - You can apply multiple tags to an image. For example, you can apply the `latest` - tag to a newly built image and add another tag that references a specific - version. - For example, to tag an image both as `whenry/fedora-jboss:latest` and - `whenry/fedora-jboss:v2.1`, use the following: - - ```console - $ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . - ``` - - ### Specify a Dockerfile (-f, --file) - - ```console - $ docker build -f Dockerfile.debug . - ``` - - This will use a file called `Dockerfile.debug` for the build instructions - instead of `Dockerfile`. - - ```console - $ curl example.com/remote/Dockerfile | docker build -f - . - ``` - - The above command will use the current directory as the build context and read - a Dockerfile from stdin. - - ```console - $ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . - $ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . - ``` - - The above commands will build the current build context (as specified by the - `.`) twice, once using a debug version of a `Dockerfile` and once using a - production version. + ### Build with PATH + + ```console + $ docker build . + + Uploading context 10240 bytes + Step 1/3 : FROM busybox + Pulling repository busybox + ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/ + Step 2/3 : RUN ls -lh / + ---> Running in 9c9e81692ae9 + total 24 + drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin + drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev + drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc + drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib + lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib + dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc + lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin + dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys + drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp + drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr + ---> b35f4035db3f + Step 3/3 : CMD echo Hello world + ---> Running in 02071fceb21b + ---> f52f38b7823e + Successfully built f52f38b7823e + Removing intermediate container 9c9e81692ae9 + Removing intermediate container 02071fceb21b + ``` + + This example specifies that the `PATH` is `.`, and so all the files in the + local directory get `tar`d and sent to the Docker daemon. The `PATH` specifies + where to find the files for the "context" of the build on the Docker daemon. + Remember that the daemon could be running on a remote machine and that no + parsing of the Dockerfile happens at the client side (where you're running + `docker build`). That means that *all* the files at `PATH` get sent, not just + the ones listed to [*ADD*](/engine/reference/builder/#add) + in the Dockerfile. + + The transfer of context from the local machine to the Docker daemon is what the + `docker` client means when you see the "Sending build context" message. + + If you wish to keep the intermediate containers after the build is complete, + you must use `--rm=false`. This does not affect the build cache. + + ### Build with URL + + ```console + $ docker build github.com/creack/docker-firefox + ``` + + This will clone the GitHub repository and use the cloned repository as context. + The Dockerfile at the root of the repository is used as Dockerfile. You can + specify an arbitrary Git repository by using the `git://` or `git@` scheme. + + ```console + $ docker build -f ctx/Dockerfile http://server/ctx.tar.gz + + Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B + Step 1/3 : FROM busybox + ---> 8c2e06607696 + Step 2/3 : ADD ctx/container.cfg / + ---> e7829950cee3 + Removing intermediate container b35224abf821 + Step 3/3 : CMD /bin/ls + ---> Running in fbc63d321d73 + ---> 3286931702ad + Removing intermediate container fbc63d321d73 + Successfully built 377c409b35e4 + ``` + + This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which + downloads and extracts the referenced tarball. The `-f ctx/Dockerfile` + parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used + to build the image. Any `ADD` commands in that `Dockerfile` that refers to local + paths must be relative to the root of the contents inside `ctx.tar.gz`. In the + example above, the tarball contains a directory `ctx/`, so the `ADD + ctx/container.cfg /` operation works as expected. + + ### Build with - + + ```console + $ docker build - < Dockerfile + ``` + + This will read a Dockerfile from `STDIN` without context. Due to the lack of a + context, no contents of any local directory will be sent to the Docker daemon. + Since there is no context, a Dockerfile `ADD` only works if it refers to a + remote URL. + + ```console + $ docker build - < context.tar.gz + ``` + + This will build an image for a compressed context read from `STDIN`. Supported + formats are: bzip2, gzip and xz. + + ### Use a .dockerignore file + + ```console + $ docker build . + + Uploading context 18.829 MB + Uploading context + Step 1/2 : FROM busybox + ---> 769b9341d937 + Step 2/2 : CMD echo Hello world + ---> Using cache + ---> 99cc1ad10469 + Successfully built 99cc1ad10469 + $ echo ".git" > .dockerignore + $ docker build . + Uploading context 6.76 MB + Uploading context + Step 1/2 : FROM busybox + ---> 769b9341d937 + Step 2/2 : CMD echo Hello world + ---> Using cache + ---> 99cc1ad10469 + Successfully built 99cc1ad10469 + ``` + + This example shows the use of the `.dockerignore` file to exclude the `.git` + directory from the context. Its effect can be seen in the changed size of the + uploaded context. The builder reference contains detailed information on + [creating a .dockerignore file](/engine/reference/builder/#dockerignore-file). + + When using the [BuildKit backend](/build/buildkit/), + `docker build` searches for a `.dockerignore` file relative to the Dockerfile + name. For example, running `docker build -f myapp.Dockerfile .` will first look + for an ignore file named `myapp.Dockerfile.dockerignore`. If such a file is not + found, the `.dockerignore` file is used if present. Using a Dockerfile based + `.dockerignore` is useful if a project contains multiple Dockerfiles that expect + to ignore different sets of files. + + + ### Tag an image (-t, --tag) {#tag} + + ```console + $ docker build -t vieux/apache:2.0 . + ``` + + This will build like the previous example, but it will then tag the resulting + image. The repository name will be `vieux/apache` and the tag will be `2.0`. + [Read more about valid tags](tag.md). + + You can apply multiple tags to an image. For example, you can apply the `latest` + tag to a newly built image and add another tag that references a specific + version. + For example, to tag an image both as `whenry/fedora-jboss:latest` and + `whenry/fedora-jboss:v2.1`, use the following: + + ```console + $ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . + ``` + + ### Specify a Dockerfile (-f, --file) {#file} + + ```console + $ docker build -f Dockerfile.debug . + ``` + + This will use a file called `Dockerfile.debug` for the build instructions + instead of `Dockerfile`. + + ```console + $ curl example.com/remote/Dockerfile | docker build -f - . + ``` + + The above command will use the current directory as the build context and read + a Dockerfile from stdin. + + ```console + $ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . + $ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . + ``` + + The above commands will build the current build context (as specified by the + `.`) twice, once using a debug version of a `Dockerfile` and once using a + production version. - ```console - $ cd /home/me/myapp/some/dir/really/deep - $ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp - $ docker build -f ../../../../dockerfiles/debug /home/me/myapp - ``` + ```console + $ cd /home/me/myapp/some/dir/really/deep + $ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp + $ docker build -f ../../../../dockerfiles/debug /home/me/myapp + ``` - These two `docker build` commands do the exact same thing. They both use the - contents of the `debug` file instead of looking for a `Dockerfile` and will use - `/home/me/myapp` as the root of the build context. Note that `debug` is in the - directory structure of the build context, regardless of how you refer to it on - the command line. + These two `docker build` commands do the exact same thing. They both use the + contents of the `debug` file instead of looking for a `Dockerfile` and will use + `/home/me/myapp` as the root of the build context. Note that `debug` is in the + directory structure of the build context, regardless of how you refer to it on + the command line. - > **Note** - > - > `docker build` returns a `no such file or directory` error if the - > file or directory does not exist in the uploaded context. This may - > happen if there is no context, or if you specify a file that is - > elsewhere on the Host system. The context is limited to the current - > directory (and its children) for security reasons, and to ensure - > repeatable builds on remote Docker hosts. This is also the reason why - > `ADD ../file` does not work. - - ### Use a custom parent cgroup (--cgroup-parent) - - When `docker build` is run with the `--cgroup-parent` option the containers - used in the build will be run with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups). + > **Note** + > + > `docker build` returns a `no such file or directory` error if the + > file or directory does not exist in the uploaded context. This may + > happen if there is no context, or if you specify a file that is + > elsewhere on the Host system. The context is limited to the current + > directory (and its children) for security reasons, and to ensure + > repeatable builds on remote Docker hosts. This is also the reason why + > `ADD ../file` does not work. + + ### Use a custom parent cgroup (--cgroup-parent) {#cgroup-parent} + + When `docker build` is run with the `--cgroup-parent` option the containers + used in the build will be run with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups). - ### Set ulimits in container (--ulimit) + ### Set ulimits in container (--ulimit) {#ulimit} - Using the `--ulimit` option with `docker build` will cause each build step's - container to be started using those [`--ulimit` flag values](run.md#ulimit). + Using the `--ulimit` option with `docker build` will cause each build step's + container to be started using those [`--ulimit` flag values](run.md#ulimit). - ### Set build-time variables (--build-arg) + ### Set build-time variables (--build-arg) {#build-arg} - You can use `ENV` instructions in a Dockerfile to define variable - values. These values persist in the built image. However, often - persistence is not what you want. Users want to specify variables differently - depending on which host they build an image on. + You can use `ENV` instructions in a Dockerfile to define variable + values. These values persist in the built image. However, often + persistence is not what you want. Users want to specify variables differently + depending on which host they build an image on. - A good example is `http_proxy` or source versions for pulling intermediate - files. The `ARG` instruction lets Dockerfile authors define values that users - can set at build-time using the `--build-arg` flag: + A good example is `http_proxy` or source versions for pulling intermediate + files. The `ARG` instruction lets Dockerfile authors define values that users + can set at build-time using the `--build-arg` flag: - ```console - $ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 . - ``` + ```console + $ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 . + ``` - This flag allows you to pass the build-time variables that are - accessed like regular environment variables in the `RUN` instruction of the - Dockerfile. Also, these values don't persist in the intermediate or final images - like `ENV` values do. You must add `--build-arg` for each build argument. + This flag allows you to pass the build-time variables that are + accessed like regular environment variables in the `RUN` instruction of the + Dockerfile. Also, these values don't persist in the intermediate or final images + like `ENV` values do. You must add `--build-arg` for each build argument. - Using this flag will not alter the output you see when the `ARG` lines from the - Dockerfile are echoed during the build process. + Using this flag will not alter the output you see when the `ARG` lines from the + Dockerfile are echoed during the build process. - For detailed information on using `ARG` and `ENV` instructions, see the - [Dockerfile reference](../builder.md). + For detailed information on using `ARG` and `ENV` instructions, see the + [Dockerfile reference](/engine/reference/builder/). - You may also use the `--build-arg` flag without a value, in which case the value - from the local environment will be propagated into the Docker container being - built: + You may also use the `--build-arg` flag without a value, in which case the value + from the local environment will be propagated into the Docker container being + built: - ```console - $ export HTTP_PROXY=http://10.20.30.2:1234 - $ docker build --build-arg HTTP_PROXY . - ``` + ```console + $ export HTTP_PROXY=http://10.20.30.2:1234 + $ docker build --build-arg HTTP_PROXY . + ``` - This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env) - for more information. + This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env) + for more information. - ### Optional security options (--security-opt) + ### Optional security options (--security-opt) {#security-opt} - This flag is only supported on a daemon running on Windows, and only supports - the `credentialspec` option. The `credentialspec` must be in the format - `file://spec.txt` or `registry://keyname`. + This flag is only supported on a daemon running on Windows, and only supports + the `credentialspec` option. The `credentialspec` must be in the format + `file://spec.txt` or `registry://keyname`. - ### Specify isolation technology for container (--isolation) + ### Specify isolation technology for container (--isolation) {#isolation} - This option is useful in situations where you are running Docker containers on - Windows. The `--isolation=` option sets a container's isolation - technology. On Linux, the only supported is the `default` option which uses - Linux namespaces. On Microsoft Windows, you can specify these values: + This option is useful in situations where you are running Docker containers on + Windows. The `--isolation=` option sets a container's isolation + technology. On Linux, the only supported is the `default` option which uses + Linux namespaces. On Microsoft Windows, you can specify these values: - | Value | Description | - |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | - | `process` | Namespace isolation only. | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | + | Value | Description | + |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | + | `process` | Namespace isolation only. | + | `hyperv` | Hyper-V hypervisor partition-based isolation. | - Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. + Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. - ### Add entries to container hosts file (--add-host) + ### Add entries to container hosts file (--add-host) {#add-host} - You can add other hosts into a container's `/etc/hosts` file by using one or - more `--add-host` flags. This example adds a static address for a host named - `docker`: + You can add other hosts into a container's `/etc/hosts` file by using one or + more `--add-host` flags. This example adds a static address for a host named + `docker`: - $ docker build --add-host=docker:10.180.0.1 . + $ docker build --add-host=docker:10.180.0.1 . - ### Specifying target build stage (--target) + ### Specifying target build stage (--target) {#target} - When building a Dockerfile with multiple build stages, `--target` can be used to - specify an intermediate build stage by name as a final stage for the resulting - image. Commands after the target stage will be skipped. + When building a Dockerfile with multiple build stages, `--target` can be used to + specify an intermediate build stage by name as a final stage for the resulting + image. Commands after the target stage will be skipped. - ```dockerfile - FROM debian AS build-env - # ... + ```dockerfile + FROM debian AS build-env + # ... - FROM alpine AS production-env - # ... - ``` + FROM alpine AS production-env + # ... + ``` - ```console - $ docker build -t mybuildimage --target build-env . - ``` + ```console + $ docker build -t mybuildimage --target build-env . + ``` - ### Custom build outputs (--output) + ### Custom build outputs (--output) {#output} - > **Note** - > - > This feature requires the BuildKit backend. You can either - > [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or - > use the [buildx](https://github.com/docker/buildx) plugin which provides more - > output type options. + > **Note** + > + > This feature requires the BuildKit backend. You can either + > [enable BuildKit](/build/buildkit/#getting-started) or + > use the [buildx](https://github.com/docker/buildx) plugin which provides more + > output type options. - By default, a local container image is created from the build result. The - `--output` (or `-o`) flag allows you to override this behavior, and a specify a - custom exporter. For example, custom exporters allow you to export the build - artifacts as files on the local filesystem instead of a Docker image, which can - be useful for generating local binaries, code generation etc. + By default, a local container image is created from the build result. The + `--output` (or `-o`) flag allows you to override this behavior, and a specify a + custom exporter. For example, custom exporters allow you to export the build + artifacts as files on the local filesystem instead of a Docker image, which can + be useful for generating local binaries, code generation etc. - The value for `--output` is a CSV-formatted string defining the exporter type - and options. Currently, `local` and `tar` exporters are supported. The `local` - exporter writes the resulting build files to a directory on the client side. The - `tar` exporter is similar but writes the files as a single tarball (`.tar`). + The value for `--output` is a CSV-formatted string defining the exporter type + and options. Currently, `local` and `tar` exporters are supported. The `local` + exporter writes the resulting build files to a directory on the client side. The + `tar` exporter is similar but writes the files as a single tarball (`.tar`). - If no type is specified, the value defaults to the output directory of the local - exporter. Use a hyphen (`-`) to write the output tarball to standard output - (`STDOUT`). + If no type is specified, the value defaults to the output directory of the local + exporter. Use a hyphen (`-`) to write the output tarball to standard output + (`STDOUT`). - The following example builds an image using the current directory (`.`) as build - context, and exports the files to a directory named `out` in the current directory. - If the directory does not exist, Docker creates the directory automatically: + The following example builds an image using the current directory (`.`) as build + context, and exports the files to a directory named `out` in the current directory. + If the directory does not exist, Docker creates the directory automatically: - ```console - $ docker build -o out . - ``` + ```console + $ docker build -o out . + ``` - The example above uses the short-hand syntax, omitting the `type` options, and - thus uses the default (`local`) exporter. The example below shows the equivalent - using the long-hand CSV syntax, specifying both `type` and `dest` (destination - path): + The example above uses the short-hand syntax, omitting the `type` options, and + thus uses the default (`local`) exporter. The example below shows the equivalent + using the long-hand CSV syntax, specifying both `type` and `dest` (destination + path): - ```console - $ docker build --output type=local,dest=out . - ``` + ```console + $ docker build --output type=local,dest=out . + ``` - Use the `tar` type to export the files as a `.tar` archive: + Use the `tar` type to export the files as a `.tar` archive: - ```console - $ docker build --output type=tar,dest=out.tar . - ``` + ```console + $ docker build --output type=tar,dest=out.tar . + ``` - The example below shows the equivalent when using the short-hand syntax. In this - case, `-` is specified as destination, which automatically selects the `tar` type, - and writes the output tarball to standard output, which is then redirected to - the `out.tar` file: + The example below shows the equivalent when using the short-hand syntax. In this + case, `-` is specified as destination, which automatically selects the `tar` type, + and writes the output tarball to standard output, which is then redirected to + the `out.tar` file: - ```console - $ docker build -o - . > out.tar - ``` + ```console + $ docker build -o - . > out.tar + ``` - The `--output` option exports all files from the target stage. A common pattern - for exporting only specific files is to do multi-stage builds and to copy the - desired files to a new scratch stage with [`COPY --from`](../builder.md#copy). + The `--output` option exports all files from the target stage. A common pattern + for exporting only specific files is to do multi-stage builds and to copy the + desired files to a new scratch stage with [`COPY --from`](/engine/reference/builder/#copy). - The example `Dockerfile` below uses a separate stage to collect the - build-artifacts for exporting: + The example `Dockerfile` below uses a separate stage to collect the + build-artifacts for exporting: - ```dockerfile - FROM golang AS build-stage - RUN go get -u github.com/LK4D4/vndr + ```dockerfile + FROM golang AS build-stage + RUN go get -u github.com/LK4D4/vndr - FROM scratch AS export-stage - COPY --from=build-stage /go/bin/vndr / - ``` + FROM scratch AS export-stage + COPY --from=build-stage /go/bin/vndr / + ``` - When building the Dockerfile with the `-o` option, only the files from the final - stage are exported to the `out` directory, in this case, the `vndr` binary: + When building the Dockerfile with the `-o` option, only the files from the final + stage are exported to the `out` directory, in this case, the `vndr` binary: - ```console - $ docker build -o out . - - [+] Building 2.3s (7/7) FINISHED - => [internal] load build definition from Dockerfile 0.1s - => => transferring dockerfile: 176B 0.0s - => [internal] load .dockerignore 0.0s - => => transferring context: 2B 0.0s - => [internal] load metadata for docker.io/library/golang:latest 1.6s - => [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s - => => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s - => CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr 0.0s - => [export-stage 1/1] COPY --from=build-stage /go/bin/vndr / 0.2s - => exporting to client 0.4s - => => copying files 10.30MB 0.3s - - $ ls ./out - vndr - ``` - - ### Specifying external cache sources (--cache-from) - - > **Note** - > - > This feature requires the BuildKit backend. You can either - > [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or - > use the [buildx](https://github.com/docker/buildx) plugin. The previous - > builder has limited support for reusing cache from pre-pulled images. - - In addition to local build cache, the builder can reuse the cache generated from - previous builds with the `--cache-from` flag pointing to an image in the registry. - - To use an image as a cache source, cache metadata needs to be written into the - image on creation. This can be done by setting `--build-arg BUILDKIT_INLINE_CACHE=1` - when building the image. After that, the built image can be used as a cache source - for subsequent builds. - - Upon importing the cache, the builder will only pull the JSON metadata from the - registry and determine possible cache hits based on that information. If there - is a cache hit, the matched layers are pulled into the local environment. - - In addition to images, the cache can also be pulled from special cache manifests - generated by [`buildx`](https://github.com/docker/buildx) or the BuildKit CLI - (`buildctl`). These manifests (when built with the `type=registry` and `mode=max` - options) allow pulling layer data for intermediate stages in multi-stage builds. - - The following example builds an image with inline-cache metadata and pushes it - to a registry, then uses the image as a cache source on another machine: - - ```console - $ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 . - $ docker push myname/myapp - ``` - - After pushing the image, the image is used as cache source on another machine. - BuildKit automatically pulls the image from the registry if needed. - - On another machine: - - ```console - $ docker build --cache-from myname/myapp . - ``` - - ### Squash an image's layers (--squash) (experimental) - - #### Overview - - Once the image is built, squash the new layers into a new image with a single - new layer. Squashing does not destroy any existing image, rather it creates a new - image with the content of the squashed layers. This effectively makes it look - like all `Dockerfile` commands were created with a single layer. The build - cache is preserved with this method. - - The `--squash` option is an experimental feature, and should not be considered - stable. - - - Squashing layers can be beneficial if your Dockerfile produces multiple layers - modifying the same files, for example, files that are created in one step, and - removed in another step. For other use-cases, squashing images may actually have - a negative impact on performance; when pulling an image consisting of multiple - layers, layers can be pulled in parallel, and allows sharing layers between - images (saving space). - - For most use cases, multi-stage builds are a better alternative, as they give more - fine-grained control over your build, and can take advantage of future - optimizations in the builder. Refer to the [use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) - section in the userguide for more information. - - - #### Known limitations - - The `--squash` option has a number of known limitations: - - - When squashing layers, the resulting image cannot take advantage of layer - sharing with other images, and may use significantly more space. Sharing the - base image is still supported. - - When using this option you may see significantly more space used due to - storing two copies of the image, one for the build cache with all the cache - layers intact, and one for the squashed version. - - While squashing layers may produce smaller images, it may have a negative - impact on performance, as a single layer takes longer to extract, and - downloading a single layer cannot be parallelized. - - When attempting to squash an image that does not make changes to the - filesystem (for example, the Dockerfile only contains `ENV` instructions), - the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)). - - #### Prerequisites - - The example on this page is using experimental mode in Docker 19.03. - - Experimental mode can be enabled by using the `--experimental` flag when starting - the Docker daemon or setting `experimental: true` in the `daemon.json` configuration - file. - - By default, experimental mode is disabled. To see the current configuration of - the docker daemon, use the `docker version` command and check the `Experimental` - line in the `Engine` section: - - ```console - Client: Docker Engine - Community - Version: 19.03.8 - API version: 1.40 - Go version: go1.12.17 - Git commit: afacb8b - Built: Wed Mar 11 01:21:11 2020 - OS/Arch: darwin/amd64 - Experimental: false - - Server: Docker Engine - Community - Engine: - Version: 19.03.8 - API version: 1.40 (minimum version 1.12) - Go version: go1.12.17 - Git commit: afacb8b - Built: Wed Mar 11 01:29:16 2020 - OS/Arch: linux/amd64 - Experimental: true - [...] - ``` - - To enable experimental mode, users need to restart the docker daemon with the - experimental flag enabled. - - #### Enable Docker experimental - - To enable experimental features, you need to start the Docker daemon with - `--experimental` flag. You can also enable the daemon flag via - `/etc/docker/daemon.json`, for example: - - ```json - { - "experimental": true - } - ``` - - Then make sure the experimental flag is enabled: - - ```console - $ docker version -f '{{.Server.Experimental}}' - true - ``` - - #### Build an image with `--squash` argument - - The following is an example of docker build with `--squash` argument - - ```dockerfile - FROM busybox - RUN echo hello > /hello - RUN echo world >> /hello - RUN touch remove_me /remove_me - ENV HELLO=world - RUN rm /remove_me - ``` - - An image named `test` is built with `--squash` argument. - - ```console - $ docker build --squash -t test . - - <...> - ``` - - If everything is right, the history looks like this: - - ```console - $ docker history test - - IMAGE CREATED CREATED BY SIZE COMMENT - 4e10cb5b4cac 3 seconds ago 12 B merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb - 5 minutes ago /bin/sh -c rm /remove_me 0 B - 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B - 5 minutes ago /bin/sh -c touch remove_me /remove_me 0 B - 5 minutes ago /bin/sh -c echo world >> /hello 0 B - 6 minutes ago /bin/sh -c echo hello > /hello 0 B - 7 weeks ago /bin/sh -c #(nop) CMD ["sh"] 0 B - 7 weeks ago /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB - ``` - - We could find that a layer's name is ``, and there is a new layer with - COMMENT `merge`. - - Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is - in `/hello`, make sure the `HELLO` environment variable's value is `world`. + ```console + $ docker build -o out . + + [+] Building 2.3s (7/7) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 176B 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 2B 0.0s + => [internal] load metadata for docker.io/library/golang:latest 1.6s + => [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s + => => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s + => CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr 0.0s + => [export-stage 1/1] COPY --from=build-stage /go/bin/vndr / 0.2s + => exporting to client 0.4s + => => copying files 10.30MB 0.3s + + $ ls ./out + vndr + ``` + + ### Specifying external cache sources (--cache-from) {#cache-from} + + > **Note** + > + > This feature requires the BuildKit backend. You can either + > [enable BuildKit](/build/buildkit/#getting-started) or + > use the [buildx](https://github.com/docker/buildx) plugin. The previous + > builder has limited support for reusing cache from pre-pulled images. + + In addition to local build cache, the builder can reuse the cache generated from + previous builds with the `--cache-from` flag pointing to an image in the registry. + + To use an image as a cache source, cache metadata needs to be written into the + image on creation. This can be done by setting `--build-arg BUILDKIT_INLINE_CACHE=1` + when building the image. After that, the built image can be used as a cache source + for subsequent builds. + + Upon importing the cache, the builder will only pull the JSON metadata from the + registry and determine possible cache hits based on that information. If there + is a cache hit, the matched layers are pulled into the local environment. + + In addition to images, the cache can also be pulled from special cache manifests + generated by [`buildx`](https://github.com/docker/buildx) or the BuildKit CLI + (`buildctl`). These manifests (when built with the `type=registry` and `mode=max` + options) allow pulling layer data for intermediate stages in multi-stage builds. + + The following example builds an image with inline-cache metadata and pushes it + to a registry, then uses the image as a cache source on another machine: + + ```console + $ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 . + $ docker push myname/myapp + ``` + + After pushing the image, the image is used as cache source on another machine. + BuildKit automatically pulls the image from the registry if needed. + + On another machine: + + ```console + $ docker build --cache-from myname/myapp . + ``` + + ### Squash an image's layers (--squash) (experimental) {#squash} + + #### Overview + + Once the image is built, squash the new layers into a new image with a single + new layer. Squashing does not destroy any existing image, rather it creates a new + image with the content of the squashed layers. This effectively makes it look + like all `Dockerfile` commands were created with a single layer. The build + cache is preserved with this method. + + The `--squash` option is an experimental feature, and should not be considered + stable. + + + Squashing layers can be beneficial if your Dockerfile produces multiple layers + modifying the same files, for example, files that are created in one step, and + removed in another step. For other use-cases, squashing images may actually have + a negative impact on performance; when pulling an image consisting of multiple + layers, layers can be pulled in parallel, and allows sharing layers between + images (saving space). + + For most use cases, multi-stage builds are a better alternative, as they give more + fine-grained control over your build, and can take advantage of future + optimizations in the builder. Refer to the [use multi-stage builds](/develop/develop-images/multistage-build/) + section in the userguide for more information. + + + #### Known limitations + + The `--squash` option has a number of known limitations: + + - When squashing layers, the resulting image cannot take advantage of layer + sharing with other images, and may use significantly more space. Sharing the + base image is still supported. + - When using this option you may see significantly more space used due to + storing two copies of the image, one for the build cache with all the cache + layers intact, and one for the squashed version. + - While squashing layers may produce smaller images, it may have a negative + impact on performance, as a single layer takes longer to extract, and + downloading a single layer cannot be parallelized. + - When attempting to squash an image that does not make changes to the + filesystem (for example, the Dockerfile only contains `ENV` instructions), + the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)). + + #### Prerequisites + + The example on this page is using experimental mode in Docker 19.03. + + Experimental mode can be enabled by using the `--experimental` flag when starting + the Docker daemon or setting `experimental: true` in the `daemon.json` configuration + file. + + By default, experimental mode is disabled. To see the current configuration of + the docker daemon, use the `docker version` command and check the `Experimental` + line in the `Engine` section: + + ```console + Client: Docker Engine - Community + Version: 19.03.8 + API version: 1.40 + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:21:11 2020 + OS/Arch: darwin/amd64 + Experimental: false + + Server: Docker Engine - Community + Engine: + Version: 19.03.8 + API version: 1.40 (minimum version 1.12) + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:29:16 2020 + OS/Arch: linux/amd64 + Experimental: true + [...] + ``` + + To enable experimental mode, users need to restart the docker daemon with the + experimental flag enabled. + + #### Enable Docker experimental + + To enable experimental features, you need to start the Docker daemon with + `--experimental` flag. You can also enable the daemon flag via + `/etc/docker/daemon.json`, for example: + + ```json + { + "experimental": true + } + ``` + + Then make sure the experimental flag is enabled: + + ```console + $ docker version -f '{{.Server.Experimental}}' + true + ``` + + #### Build an image with `--squash` argument + + The following is an example of docker build with `--squash` argument + + ```dockerfile + FROM busybox + RUN echo hello > /hello + RUN echo world >> /hello + RUN touch remove_me /remove_me + ENV HELLO=world + RUN rm /remove_me + ``` + + An image named `test` is built with `--squash` argument. + + ```console + $ docker build --squash -t test . + + <...> + ``` + + If everything is right, the history looks like this: + + ```console + $ docker history test + + IMAGE CREATED CREATED BY SIZE COMMENT + 4e10cb5b4cac 3 seconds ago 12 B merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb + 5 minutes ago /bin/sh -c rm /remove_me 0 B + 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B + 5 minutes ago /bin/sh -c touch remove_me /remove_me 0 B + 5 minutes ago /bin/sh -c echo world >> /hello 0 B + 6 minutes ago /bin/sh -c echo hello > /hello 0 B + 7 weeks ago /bin/sh -c #(nop) CMD ["sh"] 0 B + 7 weeks ago /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB + ``` + + We could find that a layer's name is ``, and there is a new layer with + COMMENT `merge`. + + Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is + in `/hello`, make sure the `HELLO` environment variable's value is `world`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_builder.yaml b/_data/engine-cli/docker_builder.yaml index c7178bfbd6..518ca35fda 100644 --- a/_data/engine-cli/docker_builder.yaml +++ b/_data/engine-cli/docker_builder.yaml @@ -5,11 +5,22 @@ usage: docker builder pname: docker plink: docker.yaml cname: -- docker builder build -- docker builder prune + - docker builder build + - docker builder prune clink: -- docker_builder_build.yaml -- docker_builder_prune.yaml + - docker_builder_build.yaml + - docker_builder_prune.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.31" experimental: false diff --git a/_data/engine-cli/docker_builder_build.yaml b/_data/engine-cli/docker_builder_build.yaml index 30b108b6d8..b3ddc82567 100644 --- a/_data/engine-cli/docker_builder_build.yaml +++ b/_data/engine-cli/docker_builder_build.yaml @@ -1,330 +1,318 @@ command: docker builder build +aliases: docker image build, docker build, docker buildx build, docker builder build short: Build an image from a Dockerfile -long: Build an image from a Dockerfile +long: See [docker build](build.md) for more information. usage: docker builder build [OPTIONS] PATH | URL | - pname: docker builder plink: docker_builder.yaml options: -- option: add-host - value_type: list - description: Add a custom host-to-IP mapping (host:ip) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: build-arg - value_type: list - description: Set build-time variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cache-from - value_type: stringSlice - default_value: '[]' - description: Images to consider as cache sources - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroup-parent - value_type: string - description: Optional parent cgroup for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: compress - value_type: bool - default_value: "false" - description: Compress the build context using gzip - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit the CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit the CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: file - shorthand: f - value_type: string - description: Name of the Dockerfile (Default is 'PATH/Dockerfile') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force-rm - value_type: bool - default_value: "false" - description: Always remove intermediate containers - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: iidfile - value_type: string - description: Write the image ID to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Container isolation technology - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - value_type: list - description: Set metadata for an image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: string - default_value: default - description: | - Set the networking mode for the RUN instructions during build - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-cache - value_type: bool - default_value: "false" - description: Do not use cache when building the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: output - shorthand: o - value_type: stringArray - default_value: '[]' - description: 'Output destination (format: type=local,dest=path)' - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.38" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: progress - value_type: string - default_value: auto - description: | - Set type of progress output (auto, plain, tty). Use plain to show container output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Always attempt to pull a newer version of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress the build output and print image ID on success - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rm - value_type: bool - default_value: "true" - description: Remove intermediate containers after a successful build - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: secret - value_type: stringArray - default_value: '[]' - description: | - Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret - deprecated: false - min_api_version: "1.39" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: security-opt - value_type: stringSlice - default_value: '[]' - description: Security options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: shm-size - value_type: bytes - default_value: "0" - description: Size of /dev/shm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: squash - value_type: bool - default_value: "false" - description: Squash newly built layers into a single new layer - deprecated: false - min_api_version: "1.25" - experimental: true - experimentalcli: false - kubernetes: false - swarm: false -- option: ssh - value_type: stringArray - default_value: '[]' - description: | - SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|[=|[,]]) - deprecated: false - min_api_version: "1.39" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stream - value_type: bool - default_value: "false" - description: Stream attaches to server to negotiate build context - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tag - shorthand: t - value_type: list - description: Name and optionally a tag in the 'name:tag' format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: target - value_type: string - description: Set the target build stage to build. - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: ulimit - default_value: '[]' - description: Ulimit options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: add-host + value_type: list + description: Add a custom host-to-IP mapping (`host:ip`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: build-arg + value_type: list + description: Set build-time variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cache-from + value_type: stringSlice + default_value: '[]' + description: Images to consider as cache sources + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: compress + value_type: bool + default_value: "false" + description: Compress the build context using gzip + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: file + shorthand: f + value_type: string + description: Name of the Dockerfile (Default is `PATH/Dockerfile`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force-rm + value_type: bool + default_value: "false" + description: Always remove intermediate containers + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: iidfile + value_type: string + description: Write the image ID to the file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Container isolation technology + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + value_type: list + description: Set metadata for an image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: 'Swap limit equal to memory plus swap: -1 to enable unlimited swap' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: string + default_value: default + description: Set the networking mode for the RUN instructions during build + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-cache + value_type: bool + default_value: "false" + description: Do not use cache when building the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.38" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pull + value_type: bool + default_value: "false" + description: Always attempt to pull a newer version of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the build output and print image ID on success + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rm + value_type: bool + default_value: "true" + description: Remove intermediate containers after a successful build + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: security-opt + value_type: stringSlice + default_value: '[]' + description: Security options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: shm-size + value_type: bytes + default_value: "0" + description: Size of `/dev/shm` + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: squash + value_type: bool + default_value: "false" + description: Squash newly built layers into a single new layer + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: true + experimentalcli: false + kubernetes: false + swarm: false + - option: tag + shorthand: t + value_type: list + description: Name and optionally a tag in the `name:tag` format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: target + value_type: string + description: Set the target build stage to build. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.31" experimental: false diff --git a/_data/engine-cli/docker_builder_prune.yaml b/_data/engine-cli/docker_builder_prune.yaml index f8614f9904..00071e4c19 100644 --- a/_data/engine-cli/docker_builder_prune.yaml +++ b/_data/engine-cli/docker_builder_prune.yaml @@ -5,43 +5,58 @@ usage: docker builder prune pname: docker builder plink: docker_builder.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Remove all unused build cache, not just dangling ones - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: filter - value_type: filter - description: Provide filter values (e.g. 'until=24h') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Do not prompt for confirmation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: keep-storage - value_type: bytes - default_value: "0" - description: Amount of disk space to keep for cache - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Remove all unused build cache, not just dangling ones + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: filter + value_type: filter + description: Provide filter values (e.g. `until=24h`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Do not prompt for confirmation + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: keep-storage + value_type: bytes + default_value: "0" + description: Amount of disk space to keep for cache + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.39" experimental: false diff --git a/_data/engine-cli/docker_checkpoint.yaml b/_data/engine-cli/docker_checkpoint.yaml index c2b9713145..f650506834 100644 --- a/_data/engine-cli/docker_checkpoint.yaml +++ b/_data/engine-cli/docker_checkpoint.yaml @@ -1,110 +1,121 @@ command: docker checkpoint short: Manage checkpoints long: |- - Checkpoint and Restore is an experimental feature that allows you to freeze a running - container by checkpointing it, which turns its state into a collection of files - on disk. Later, the container can be restored from the point it was frozen. + Checkpoint and Restore is an experimental feature that allows you to freeze a running + container by checkpointing it, which turns its state into a collection of files + on disk. Later, the container can be restored from the point it was frozen. - This is accomplished using a tool called [CRIU](https://criu.org), which is an - external dependency of this feature. A good overview of the history of - checkpoint and restore in Docker is available in this - [Kubernetes blog post](https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/). + This is accomplished using a tool called [CRIU](https://criu.org), which is an + external dependency of this feature. A good overview of the history of + checkpoint and restore in Docker is available in this + [Kubernetes blog post](https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/). - ### Installing CRIU + ### Installing CRIU - If you use a Debian system, you can add the CRIU PPA and install with `apt-get` - [from the criu launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa). + If you use a Debian system, you can add the CRIU PPA and install with `apt-get` + [from the criu launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa). - Alternatively, you can [build CRIU from source](https://criu.org/Installation). + Alternatively, you can [build CRIU from source](https://criu.org/Installation). - You need at least version 2.0 of CRIU to run checkpoint and restore in Docker. + You need at least version 2.0 of CRIU to run checkpoint and restore in Docker. - ### Use cases for checkpoint and restore + ### Use cases for checkpoint and restore - This feature is currently focused on single-host use cases for checkpoint and - restore. Here are a few: + This feature is currently focused on single-host use cases for checkpoint and + restore. Here are a few: - - Restarting the host machine without stopping/starting containers - - Speeding up the start time of slow start applications - - "Rewinding" processes to an earlier point in time - - "Forensic debugging" of running processes + - Restarting the host machine without stopping/starting containers + - Speeding up the start time of slow start applications + - "Rewinding" processes to an earlier point in time + - "Forensic debugging" of running processes - Another primary use case of checkpoint and restore outside of Docker is the live - migration of a server from one machine to another. This is possible with the - current implementation, but not currently a priority (and so the workflow is - not optimized for the task). + Another primary use case of checkpoint and restore outside of Docker is the live + migration of a server from one machine to another. This is possible with the + current implementation, but not currently a priority (and so the workflow is + not optimized for the task). - ### Using checkpoint and restore + ### Using checkpoint and restore - A new top level command `docker checkpoint` is introduced, with three subcommands: + A new top level command `docker checkpoint` is introduced, with three subcommands: - - `docker checkpoint create` (creates a new checkpoint) - - `docker checkpoint ls` (lists existing checkpoints) - - `docker checkpoint rm` (deletes an existing checkpoint) + - `docker checkpoint create` (creates a new checkpoint) + - `docker checkpoint ls` (lists existing checkpoints) + - `docker checkpoint rm` (deletes an existing checkpoint) - Additionally, a `--checkpoint` flag is added to the `docker container start` command. + Additionally, a `--checkpoint` flag is added to the `docker container start` command. - The options for `docker checkpoint create`: + The options for `docker checkpoint create`: - ```console - Usage: docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT + ```console + Usage: docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT - Create a checkpoint from a running container + Create a checkpoint from a running container - --leave-running=false Leave the container running after checkpoint - --checkpoint-dir Use a custom checkpoint storage directory - ``` + --leave-running=false Leave the container running after checkpoint + --checkpoint-dir Use a custom checkpoint storage directory + ``` - And to restore a container: + And to restore a container: - ```console - Usage: docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER - ``` + ```console + Usage: docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER + ``` - Example of using checkpoint and restore on a container: + Example of using checkpoint and restore on a container: - ```console - $ docker run --security-opt=seccomp:unconfined --name cr -d busybox /bin/sh -c 'i=0; while true; do echo $i; i=$(expr $i + 1); sleep 1; done' - abc0123 + ```console + $ docker run --security-opt=seccomp:unconfined --name cr -d busybox /bin/sh -c 'i=0; while true; do echo $i; i=$(expr $i + 1); sleep 1; done' + abc0123 - $ docker checkpoint create cr checkpoint1 + $ docker checkpoint create cr checkpoint1 - # - $ docker start --checkpoint checkpoint1 cr - abc0123 - ``` + # + $ docker start --checkpoint checkpoint1 cr + abc0123 + ``` - This process just logs an incrementing counter to stdout. If you run `docker logs` - in between running/checkpoint/restoring you should see that the counter - increases while the process is running, stops while it's checkpointed, and - resumes from the point it left off once you restore. + This process just logs an incrementing counter to stdout. If you run `docker logs` + in between running/checkpoint/restoring you should see that the counter + increases while the process is running, stops while it's checkpointed, and + resumes from the point it left off once you restore. - ### Known limitations + ### Known limitations - seccomp is only supported by CRIU in very up to date kernels. + seccomp is only supported by CRIU in very up to date kernels. - External terminal (i.e. `docker run -t ..`) is not supported at the moment. - If you try to create a checkpoint for a container with an external terminal, - it would fail: + External terminal (i.e. `docker run -t ..`) is not supported at the moment. + If you try to create a checkpoint for a container with an external terminal, + it would fail: - ```console - $ docker checkpoint create cr checkpoint1 - Error response from daemon: Cannot checkpoint container c1: rpc error: code = 2 desc = exit status 1: "criu failed: type NOTIFY errno 0\nlog file: /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log\n" + ```console + $ docker checkpoint create cr checkpoint1 + Error response from daemon: Cannot checkpoint container c1: rpc error: code = 2 desc = exit status 1: "criu failed: type NOTIFY errno 0\nlog file: /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log\n" - $ cat /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log - Error (mount.c:740): mnt: 126:./dev/console doesn't have a proper root mount - ``` + $ cat /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log + Error (mount.c:740): mnt: 126:./dev/console doesn't have a proper root mount + ``` usage: docker checkpoint pname: docker plink: docker.yaml cname: -- docker checkpoint create -- docker checkpoint ls -- docker checkpoint rm + - docker checkpoint create + - docker checkpoint ls + - docker checkpoint rm clink: -- docker_checkpoint_create.yaml -- docker_checkpoint_ls.yaml -- docker_checkpoint_rm.yaml + - docker_checkpoint_create.yaml + - docker_checkpoint_ls.yaml + - docker_checkpoint_rm.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.25" experimental: true diff --git a/_data/engine-cli/docker_checkpoint_create.yaml b/_data/engine-cli/docker_checkpoint_create.yaml index c45b1f5228..0fe3f3f9f1 100644 --- a/_data/engine-cli/docker_checkpoint_create.yaml +++ b/_data/engine-cli/docker_checkpoint_create.yaml @@ -5,23 +5,36 @@ usage: docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT pname: docker checkpoint plink: docker_checkpoint.yaml options: -- option: checkpoint-dir - value_type: string - description: Use a custom checkpoint storage directory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: leave-running - value_type: bool - default_value: "false" - description: Leave the container running after checkpoint - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: checkpoint-dir + value_type: string + description: Use a custom checkpoint storage directory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: leave-running + value_type: bool + default_value: "false" + description: Leave the container running after checkpoint + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.25" experimental: true diff --git a/_data/engine-cli/docker_checkpoint_ls.yaml b/_data/engine-cli/docker_checkpoint_ls.yaml index 2d5966a347..7188092ddb 100644 --- a/_data/engine-cli/docker_checkpoint_ls.yaml +++ b/_data/engine-cli/docker_checkpoint_ls.yaml @@ -1,19 +1,31 @@ command: docker checkpoint ls -aliases: list +aliases: docker checkpoint ls, docker checkpoint list short: List checkpoints for a container long: List checkpoints for a container usage: docker checkpoint ls [OPTIONS] CONTAINER pname: docker checkpoint plink: docker_checkpoint.yaml options: -- option: checkpoint-dir - value_type: string - description: Use a custom checkpoint storage directory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: checkpoint-dir + value_type: string + description: Use a custom checkpoint storage directory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.25" experimental: true diff --git a/_data/engine-cli/docker_checkpoint_rm.yaml b/_data/engine-cli/docker_checkpoint_rm.yaml index eab14820c7..a29cd33b5c 100644 --- a/_data/engine-cli/docker_checkpoint_rm.yaml +++ b/_data/engine-cli/docker_checkpoint_rm.yaml @@ -1,19 +1,31 @@ command: docker checkpoint rm -aliases: remove +aliases: docker checkpoint rm, docker checkpoint remove short: Remove a checkpoint long: Remove a checkpoint usage: docker checkpoint rm [OPTIONS] CONTAINER CHECKPOINT pname: docker checkpoint plink: docker_checkpoint.yaml options: -- option: checkpoint-dir - value_type: string - description: Use a custom checkpoint storage directory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: checkpoint-dir + value_type: string + description: Use a custom checkpoint storage directory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.25" experimental: true diff --git a/_data/engine-cli/docker_commit.yaml b/_data/engine-cli/docker_commit.yaml index a6e6efa2c2..0a40a255b9 100644 --- a/_data/engine-cli/docker_commit.yaml +++ b/_data/engine-cli/docker_commit.yaml @@ -1,130 +1,147 @@ command: docker commit +aliases: docker container commit, docker commit short: Create a new image from a container's changes long: |- - It can be useful to commit a container's file changes or settings into a new - image. This allows you to debug a container by running an interactive shell, or to - export a working dataset to another server. Generally, it is better to use - Dockerfiles to manage your images in a documented and maintainable way. - [Read more about valid image names and tags](tag.md). + It can be useful to commit a container's file changes or settings into a new + image. This allows you to debug a container by running an interactive shell, or to + export a working dataset to another server. Generally, it is better to use + Dockerfiles to manage your images in a documented and maintainable way. + [Read more about valid image names and tags](tag.md). - The commit operation will not include any data contained in - volumes mounted inside the container. + The commit operation will not include any data contained in + volumes mounted inside the container. - By default, the container being committed and its processes will be paused - while the image is committed. This reduces the likelihood of encountering data - corruption during the process of creating the commit. If this behavior is - undesired, set the `--pause` option to false. + By default, the container being committed and its processes will be paused + while the image is committed. This reduces the likelihood of encountering data + corruption during the process of creating the commit. If this behavior is + undesired, set the `--pause` option to false. - The `--change` option will apply `Dockerfile` instructions to the image that is - created. Supported `Dockerfile` instructions: - `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` + The `--change` option will apply `Dockerfile` instructions to the image that is + created. Supported `Dockerfile` instructions: + `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]] pname: docker plink: docker.yaml options: -- option: author - shorthand: a - value_type: string - description: Author (e.g., "John Hannibal Smith ") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: change - shorthand: c - value_type: list - description: Apply Dockerfile instruction to the created image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: message - shorthand: m - value_type: string - description: Commit message - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pause - shorthand: p - value_type: bool - default_value: "true" - description: Pause container during commit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: author + shorthand: a + value_type: string + description: Author (e.g., `John Hannibal Smith `) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: change + shorthand: c + value_type: list + description: Apply Dockerfile instruction to the created image + details_url: '#change' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: message + shorthand: m + value_type: string + description: Commit message + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pause + shorthand: p + value_type: bool + default_value: "true" + description: Pause container during commit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Commit a container + ### Commit a container - ```console - $ docker ps + ```console + $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - $ docker commit c3f279d17e0a svendowideit/testimage:version3 + $ docker commit c3f279d17e0a svendowideit/testimage:version3 - f5283438590d + f5283438590d - $ docker images + $ docker images - REPOSITORY TAG ID CREATED SIZE - svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB - ``` + REPOSITORY TAG ID CREATED SIZE + svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB + ``` - ### Commit a container with new configurations (--change) + ### Commit a container with new configurations (--change) {#change} - ```console - $ docker ps + ```console + $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a + $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a - [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin] + [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin] - $ docker commit --change "ENV DEBUG=true" c3f279d17e0a svendowideit/testimage:version3 + $ docker commit --change "ENV DEBUG=true" c3f279d17e0a svendowideit/testimage:version3 - f5283438590d + f5283438590d - $ docker inspect -f "{{ .Config.Env }}" f5283438590d + $ docker inspect -f "{{ .Config.Env }}" f5283438590d - [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true] - ``` + [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true] + ``` - ### Commit a container with new `CMD` and `EXPOSE` instructions + ### Commit a container with new `CMD` and `EXPOSE` instructions - ```console - $ docker ps + ```console + $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4 + $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4 - f5283438590d + f5283438590d - $ docker run -d svendowideit/testimage:version4 + $ docker run -d svendowideit/testimage:version4 - 89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0 + 89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0 - $ docker ps + $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat - c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat + c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_config.yaml b/_data/engine-cli/docker_config.yaml index 81801f1d9f..7abf0068dc 100644 --- a/_data/engine-cli/docker_config.yaml +++ b/_data/engine-cli/docker_config.yaml @@ -1,19 +1,30 @@ command: docker config -short: Manage Docker configs +short: Manage Swarm configs long: Manage configs. usage: docker config pname: docker plink: docker.yaml cname: -- docker config create -- docker config inspect -- docker config ls -- docker config rm + - docker config create + - docker config inspect + - docker config ls + - docker config rm clink: -- docker_config_create.yaml -- docker_config_inspect.yaml -- docker_config_ls.yaml -- docker_config_rm.yaml + - docker_config_create.yaml + - docker_config_inspect.yaml + - docker_config_ls.yaml + - docker_config_rm.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_config_create.yaml b/_data/engine-cli/docker_config_create.yaml index e9991284f3..6d716986a1 100644 --- a/_data/engine-cli/docker_config_create.yaml +++ b/_data/engine-cli/docker_config_create.yaml @@ -1,98 +1,112 @@ command: docker config create short: Create a config from a file or STDIN long: |- - Creates a config using standard input or from a file for the config content. + Creates a config using standard input or from a file for the config content. - For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). + For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/). - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker config create [OPTIONS] CONFIG file|- pname: docker config plink: docker_config.yaml options: -- option: label - shorthand: l - value_type: list - description: Config labels - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: template-driver - value_type: string - description: Template driver - deprecated: false - min_api_version: "1.37" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: label + shorthand: l + value_type: list + description: Config labels + details_url: '#label' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: template-driver + value_type: string + description: Template driver + deprecated: false + hidden: false + min_api_version: "1.37" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Create a config + ### Create a config - ```console - $ printf | docker config create my_config - + ```console + $ printf | docker config create my_config - - onakdyv307se2tl7nl20anokv + onakdyv307se2tl7nl20anokv - $ docker config ls + $ docker config ls - ID NAME CREATED UPDATED - onakdyv307se2tl7nl20anokv my_config 6 seconds ago 6 seconds ago - ``` + ID NAME CREATED UPDATED + onakdyv307se2tl7nl20anokv my_config 6 seconds ago 6 seconds ago + ``` - ### Create a config with a file + ### Create a config with a file - ```console - $ docker config create my_config ./config.json + ```console + $ docker config create my_config ./config.json - dg426haahpi5ezmkkj5kyl3sn + dg426haahpi5ezmkkj5kyl3sn - $ docker config ls + $ docker config ls - ID NAME CREATED UPDATED - dg426haahpi5ezmkkj5kyl3sn my_config 7 seconds ago 7 seconds ago - ``` + ID NAME CREATED UPDATED + dg426haahpi5ezmkkj5kyl3sn my_config 7 seconds ago 7 seconds ago + ``` - ### Create a config with labels (-l, --label) + ### Create a config with labels (-l, --label) {#label} - ```console - $ docker config create \ - --label env=dev \ - --label rev=20170324 \ - my_config ./config.json + ```console + $ docker config create \ + --label env=dev \ + --label rev=20170324 \ + my_config ./config.json - eo7jnzguqgtpdah3cm5srfb97 - ``` + eo7jnzguqgtpdah3cm5srfb97 + ``` - ```console - $ docker config inspect my_config + ```console + $ docker config inspect my_config - [ - { - "ID": "eo7jnzguqgtpdah3cm5srfb97", - "Version": { - "Index": 17 - }, - "CreatedAt": "2017-03-24T08:15:09.735271783Z", - "UpdatedAt": "2017-03-24T08:15:09.735271783Z", - "Spec": { - "Name": "my_config", - "Labels": { - "env": "dev", - "rev": "20170324" - }, - "Data": "aGVsbG8K" - } - } - ] - ``` + [ + { + "ID": "eo7jnzguqgtpdah3cm5srfb97", + "Version": { + "Index": 17 + }, + "CreatedAt": "2017-03-24T08:15:09.735271783Z", + "UpdatedAt": "2017-03-24T08:15:09.735271783Z", + "Spec": { + "Name": "my_config", + "Labels": { + "env": "dev", + "rev": "20170324" + }, + "Data": "aGVsbG8K" + } + } + ] + ``` deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_config_inspect.yaml b/_data/engine-cli/docker_config_inspect.yaml index 3335b0817d..0cdfe1dc63 100644 --- a/_data/engine-cli/docker_config_inspect.yaml +++ b/_data/engine-cli/docker_config_inspect.yaml @@ -1,96 +1,114 @@ command: docker config inspect short: Display detailed information on one or more configs long: |- - Inspects the specified config. + Inspects the specified config. - By default, this renders all results in a JSON array. If a format is specified, - the given template will be executed for each result. + By default, this renders all results in a JSON array. If a format is specified, + the given template will be executed for each result. - Go's [text/template](https://golang.org/pkg/text/template/) package - describes all the details of the format. + Go's [text/template](https://golang.org/pkg/text/template/) package + describes all the details of the format. - For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). + For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/). - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker config inspect [OPTIONS] CONFIG [CONFIG...] pname: docker config plink: docker_config.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pretty - value_type: bool - default_value: "false" - description: Print the information in a human friendly format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pretty + value_type: bool + default_value: "false" + description: Print the information in a human friendly format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Inspect a config by name or ID + ### Inspect a config by name or ID - You can inspect a config, either by its *name*, or *ID* + You can inspect a config, either by its *name*, or *ID* - For example, given the following config: + For example, given the following config: - ```console - $ docker config ls + ```console + $ docker config ls - ID NAME CREATED UPDATED - eo7jnzguqgtpdah3cm5srfb97 my_config 3 minutes ago 3 minutes ago - ``` + ID NAME CREATED UPDATED + eo7jnzguqgtpdah3cm5srfb97 my_config 3 minutes ago 3 minutes ago + ``` - ```console - $ docker config inspect config.json - ``` + ```console + $ docker config inspect config.json + ``` - The output is in JSON format, for example: + The output is in JSON format, for example: - ```json - [ - { - "ID": "eo7jnzguqgtpdah3cm5srfb97", - "Version": { - "Index": 17 - }, - "CreatedAt": "2017-03-24T08:15:09.735271783Z", - "UpdatedAt": "2017-03-24T08:15:09.735271783Z", - "Spec": { - "Name": "my_config", - "Labels": { - "env": "dev", - "rev": "20170324" + ```json + [ + { + "ID": "eo7jnzguqgtpdah3cm5srfb97", + "Version": { + "Index": 17 }, - "Data": "aGVsbG8K" + "CreatedAt": "2017-03-24T08:15:09.735271783Z", + "UpdatedAt": "2017-03-24T08:15:09.735271783Z", + "Spec": { + "Name": "my_config", + "Labels": { + "env": "dev", + "rev": "20170324" + }, + "Data": "aGVsbG8K" + } } - } - ] - ``` + ] + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - You can use the --format option to obtain specific information about a - config. The following example command outputs the creation time of the - config. + You can use the --format option to obtain specific information about a + config. The following example command outputs the creation time of the + config. - ```console - $ docker config inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97 + ```console + $ docker config inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97 - 2017-03-24 08:15:09.735271783 +0000 UTC - ``` + 2017-03-24 08:15:09.735271783 +0000 UTC + ``` deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_config_ls.yaml b/_data/engine-cli/docker_config_ls.yaml index d6934213c0..7d4b3a89d0 100644 --- a/_data/engine-cli/docker_config_ls.yaml +++ b/_data/engine-cli/docker_config_ls.yaml @@ -1,160 +1,182 @@ command: docker config ls -aliases: list +aliases: docker config ls, docker config list short: List configs long: |- - Run this command on a manager node to list the configs in the swarm. + Run this command on a manager node to list the configs in the swarm. - For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). + For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/). - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker config ls [OPTIONS] pname: docker config plink: docker_config.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print configs using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker config ls + ```console + $ docker config ls - ID NAME CREATED UPDATED - 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago - 9u9hk4br2ej0wgngkga6rp4hq my_config 5 weeks ago 5 weeks ago - mem02h8n73mybpgqjf0kfi1n0 test_config 3 seconds ago 3 seconds ago - ``` + ID NAME CREATED UPDATED + 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago + 9u9hk4br2ej0wgngkga6rp4hq my_config 5 weeks ago 5 weeks ago + mem02h8n73mybpgqjf0kfi1n0 test_config 3 seconds ago 3 seconds ago + ``` - ### Filtering (-f, --filter) + ### Filtering (-f, --filter) {#filter} - The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more - than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) - The currently supported filters are: + The currently supported filters are: - - [id](#id) (config's ID) - - [label](#label) (`label=` or `label==`) - - [name](#name) (config's name) + - [id](#id) (config's ID) + - [label](#label) (`label=` or `label==`) + - [name](#name) (config's name) - #### id + #### id - The `id` filter matches all or prefix of a config's id. + The `id` filter matches all or prefix of a config's id. - ```console - $ docker config ls -f "id=6697bflskwj1998km1gnnjr38" + ```console + $ docker config ls -f "id=6697bflskwj1998km1gnnjr38" - ID NAME CREATED UPDATED - 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago - ``` + ID NAME CREATED UPDATED + 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago + ``` - #### label + #### label - The `label` filter matches configs based on the presence of a `label` alone or - a `label` and a value. + The `label` filter matches configs based on the presence of a `label` alone or + a `label` and a value. - The following filter matches all configs with a `project` label regardless of - its value: + The following filter matches all configs with a `project` label regardless of + its value: - ```console - $ docker config ls --filter label=project + ```console + $ docker config ls --filter label=project - ID NAME CREATED UPDATED - mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago - ``` + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago + ``` - The following filter matches only services with the `project` label with the - `project-a` value. + The following filter matches only services with the `project` label with the + `project-a` value. - ```console - $ docker service ls --filter label=project=test + ```console + $ docker service ls --filter label=project=test - ID NAME CREATED UPDATED - mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago - ``` + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago + ``` - #### name + #### name - The `name` filter matches on all or prefix of a config's name. + The `name` filter matches on all or prefix of a config's name. - The following filter matches config with a name containing a prefix of `test`. + The following filter matches config with a name containing a prefix of `test`. - ```console - $ docker config ls --filter name=test_config + ```console + $ docker config ls --filter name=test_config - ID NAME CREATED UPDATED - mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago - ``` + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) pretty prints configs output - using a Go template. + The formatting option (`--format`) pretty prints configs output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |--------------|--------------------------------------------------------------------------------------| - | `.ID` | Config ID | - | `.Name` | Config name | - | `.CreatedAt` | Time when the config was created | - | `.UpdatedAt` | Time when the config was updated | - | `.Labels` | All labels assigned to the config | - | `.Label` | Value of a specific label for this config. For example `{{.Label "my-label"}}` | + | Placeholder | Description | + |--------------|--------------------------------------------------------------------------------------| + | `.ID` | Config ID | + | `.Name` | Config name | + | `.CreatedAt` | Time when the config was created | + | `.UpdatedAt` | Time when the config was updated | + | `.Labels` | All labels assigned to the config | + | `.Label` | Value of a specific label for this config. For example `{{.Label "my-label"}}` | - When using the `--format` option, the `config ls` command will either - output the data exactly as the template declares or, when using the - `table` directive, will include column headers as well. + When using the `--format` option, the `config ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, will include column headers as well. - The following example uses a template without headers and outputs the - `ID` and `Name` entries separated by a colon (`:`) for all images: + The following example uses a template without headers and outputs the + `ID` and `Name` entries separated by a colon (`:`) for all images: - ```console - $ docker config ls --format "{{.ID}}: {{.Name}}" + ```console + $ docker config ls --format "{{.ID}}: {{.Name}}" - 77af4d6b9913: config-1 - b6fa739cedf5: config-2 - 78a85c484f71: config-3 - ``` + 77af4d6b9913: config-1 + b6fa739cedf5: config-2 + 78a85c484f71: config-3 + ``` - To list all configs with their name and created date in a table format you - can use: + To list all configs with their name and created date in a table format you + can use: - ```console - $ docker config ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}" + ```console + $ docker config ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}" - ID NAME CREATED - 77af4d6b9913 config-1 5 minutes ago - b6fa739cedf5 config-2 3 hours ago - 78a85c484f71 config-3 10 days ago - ``` + ID NAME CREATED + 77af4d6b9913 config-1 5 minutes ago + b6fa739cedf5 config-2 3 hours ago + 78a85c484f71 config-3 10 days ago + ``` deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_config_rm.yaml b/_data/engine-cli/docker_config_rm.yaml index c29e1a3867..db718561b4 100644 --- a/_data/engine-cli/docker_config_rm.yaml +++ b/_data/engine-cli/docker_config_rm.yaml @@ -1,32 +1,43 @@ command: docker config rm -aliases: remove +aliases: docker config rm, docker config remove short: Remove one or more configs long: |- - Removes the specified configs from the swarm. + Removes the specified configs from the swarm. - For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). + For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/). - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker config rm CONFIG [CONFIG...] pname: docker config plink: docker_config.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - This example removes a config: + This example removes a config: - ```console - $ docker config rm my_config - sapth4csdo5b6wz2p5uimh5xg - ``` + ```console + $ docker config rm my_config + sapth4csdo5b6wz2p5uimh5xg + ``` - > **Warning** - > - > Unlike `docker rm`, this command does not ask for confirmation before removing - > a config. + > **Warning** + > + > Unlike `docker rm`, this command does not ask for confirmation before removing + > a config. deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_container.yaml b/_data/engine-cli/docker_container.yaml index 3c501b4487..28ef753a3a 100644 --- a/_data/engine-cli/docker_container.yaml +++ b/_data/engine-cli/docker_container.yaml @@ -5,57 +5,68 @@ usage: docker container pname: docker plink: docker.yaml cname: -- docker container attach -- docker container commit -- docker container cp -- docker container create -- docker container diff -- docker container exec -- docker container export -- docker container inspect -- docker container kill -- docker container logs -- docker container ls -- docker container pause -- docker container port -- docker container prune -- docker container rename -- docker container restart -- docker container rm -- docker container run -- docker container start -- docker container stats -- docker container stop -- docker container top -- docker container unpause -- docker container update -- docker container wait + - docker container attach + - docker container commit + - docker container cp + - docker container create + - docker container diff + - docker container exec + - docker container export + - docker container inspect + - docker container kill + - docker container logs + - docker container ls + - docker container pause + - docker container port + - docker container prune + - docker container rename + - docker container restart + - docker container rm + - docker container run + - docker container start + - docker container stats + - docker container stop + - docker container top + - docker container unpause + - docker container update + - docker container wait clink: -- docker_container_attach.yaml -- docker_container_commit.yaml -- docker_container_cp.yaml -- docker_container_create.yaml -- docker_container_diff.yaml -- docker_container_exec.yaml -- docker_container_export.yaml -- docker_container_inspect.yaml -- docker_container_kill.yaml -- docker_container_logs.yaml -- docker_container_ls.yaml -- docker_container_pause.yaml -- docker_container_port.yaml -- docker_container_prune.yaml -- docker_container_rename.yaml -- docker_container_restart.yaml -- docker_container_rm.yaml -- docker_container_run.yaml -- docker_container_start.yaml -- docker_container_stats.yaml -- docker_container_stop.yaml -- docker_container_top.yaml -- docker_container_unpause.yaml -- docker_container_update.yaml -- docker_container_wait.yaml + - docker_container_attach.yaml + - docker_container_commit.yaml + - docker_container_cp.yaml + - docker_container_create.yaml + - docker_container_diff.yaml + - docker_container_exec.yaml + - docker_container_export.yaml + - docker_container_inspect.yaml + - docker_container_kill.yaml + - docker_container_logs.yaml + - docker_container_ls.yaml + - docker_container_pause.yaml + - docker_container_port.yaml + - docker_container_prune.yaml + - docker_container_rename.yaml + - docker_container_restart.yaml + - docker_container_rm.yaml + - docker_container_run.yaml + - docker_container_start.yaml + - docker_container_stats.yaml + - docker_container_stop.yaml + - docker_container_top.yaml + - docker_container_unpause.yaml + - docker_container_update.yaml + - docker_container_wait.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_attach.yaml b/_data/engine-cli/docker_container_attach.yaml index 95b4d3ede8..eed5223945 100644 --- a/_data/engine-cli/docker_container_attach.yaml +++ b/_data/engine-cli/docker_container_attach.yaml @@ -1,36 +1,52 @@ command: docker container attach -short: Attach local standard input, output, and error streams to a running container -long: Attach local standard input, output, and error streams to a running container +aliases: docker container attach, docker attach +short: | + Attach local standard input, output, and error streams to a running container +long: See [docker attach](attach.md) for more information. usage: docker container attach [OPTIONS] CONTAINER pname: docker container plink: docker_container.yaml options: -- option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-stdin - value_type: bool - default_value: "false" - description: Do not attach STDIN - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sig-proxy - value_type: bool - default_value: "true" - description: Proxy all received signals to the process - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: detach-keys + value_type: string + description: Override the key sequence for detaching a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-stdin + value_type: bool + default_value: "false" + description: Do not attach STDIN + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sig-proxy + value_type: bool + default_value: "true" + description: Proxy all received signals to the process + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_commit.yaml b/_data/engine-cli/docker_container_commit.yaml index 8524a53a5b..1d39b8ed50 100644 --- a/_data/engine-cli/docker_container_commit.yaml +++ b/_data/engine-cli/docker_container_commit.yaml @@ -1,47 +1,63 @@ command: docker container commit +aliases: docker container commit, docker commit short: Create a new image from a container's changes -long: Create a new image from a container's changes +long: See [docker commit](commit.md) for more information. usage: docker container commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]] pname: docker container plink: docker_container.yaml options: -- option: author - shorthand: a - value_type: string - description: Author (e.g., "John Hannibal Smith ") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: change - shorthand: c - value_type: list - description: Apply Dockerfile instruction to the created image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: message - shorthand: m - value_type: string - description: Commit message - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pause - shorthand: p - value_type: bool - default_value: "true" - description: Pause container during commit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: author + shorthand: a + value_type: string + description: Author (e.g., `John Hannibal Smith `) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: change + shorthand: c + value_type: list + description: Apply Dockerfile instruction to the created image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: message + shorthand: m + value_type: string + description: Commit message + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pause + shorthand: p + value_type: bool + default_value: "true" + description: Pause container during commit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_cp.yaml b/_data/engine-cli/docker_container_cp.yaml index e308f4068a..9da8707c47 100644 --- a/_data/engine-cli/docker_container_cp.yaml +++ b/_data/engine-cli/docker_container_cp.yaml @@ -1,37 +1,58 @@ command: docker container cp +aliases: docker container cp, docker cp short: Copy files/folders between a container and the local filesystem -long: |- - Copy files/folders between a container and the local filesystem - - Use '-' as the source to read a tar archive from stdin - and extract it to a directory destination in a container. - Use '-' as the destination to stream a tar archive of a - container source to stdout. -usage: "docker container cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker cp - [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH" +long: See [docker cp](cp.md) for more information. +usage: |- + docker container cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|- + docker cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH pname: docker container plink: docker_container.yaml options: -- option: archive - shorthand: a - value_type: bool - default_value: "false" - description: Archive mode (copy all uid/gid information) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: follow-link - shorthand: L - value_type: bool - default_value: "false" - description: Always follow symbol link in SRC_PATH - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: archive + shorthand: a + value_type: bool + default_value: "false" + description: Archive mode (copy all uid/gid information) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: follow-link + shorthand: L + value_type: bool + default_value: "false" + description: Always follow symbol link in SRC_PATH + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: | + Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_create.yaml b/_data/engine-cli/docker_container_create.yaml index ece16dca1b..5020770013 100644 --- a/_data/engine-cli/docker_container_create.yaml +++ b/_data/engine-cli/docker_container_create.yaml @@ -1,891 +1,1000 @@ command: docker container create +aliases: docker container create, docker create short: Create a new container -long: Create a new container +long: See [docker create](create.md) for more information. usage: docker container create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker container plink: docker_container.yaml options: -- option: add-host - value_type: list - description: Add a custom host-to-IP mapping (host:ip) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: attach - shorthand: a - value_type: list - description: Attach to STDIN, STDOUT or STDERR - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: blkio-weight - value_type: uint16 - default_value: "0" - description: | - Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: blkio-weight-device - value_type: list - default_value: '[]' - description: Block IO weight (relative device weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-add - value_type: list - description: Add Linux capabilities - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-drop - value_type: list - description: Drop Linux capabilities - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroup-parent - value_type: string - description: Optional parent cgroup for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroupns - value_type: string - description: |- - Cgroup namespace to use (host|private) - 'host': Run the container in the Docker host's cgroup namespace - 'private': Run the container in its own private cgroup namespace - '': Use the cgroup namespace as configured by the - default-cgroupns-mode option on the daemon (default) - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cidfile - value_type: string - description: Write the container ID to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-count - value_type: int64 - default_value: "0" - description: CPU count (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: cpu-percent - value_type: int64 - default_value: "0" - description: CPU percent (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-period - value_type: int64 - default_value: "0" - description: Limit CPU real-time period in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-runtime - value_type: int64 - default_value: "0" - description: Limit CPU real-time runtime in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpus - value_type: decimal - description: Number of CPUs - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device - value_type: list - description: Add a host device to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-cgroup-rule - value_type: list - description: Add a rule to the cgroup allowed devices list - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-read-bps - value_type: list - default_value: '[]' - description: Limit read rate (bytes per second) from a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-read-iops - value_type: list - default_value: '[]' - description: Limit read rate (IO per second) from a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-write-bps - value_type: list - default_value: '[]' - description: Limit write rate (bytes per second) to a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-write-iops - value_type: list - default_value: '[]' - description: Limit write rate (IO per second) to a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns - value_type: list - description: Set custom DNS servers - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-opt - value_type: list - description: Set DNS options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-option - value_type: list - description: Set DNS options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-search - value_type: list - description: Set custom DNS search domains - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: domainname - value_type: string - description: Container NIS domain name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: entrypoint - value_type: string - description: Overwrite the default ENTRYPOINT of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env - shorthand: e - value_type: list - description: Set environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-file - value_type: list - description: Read in a file of environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: expose - value_type: list - description: Expose a port or a range of ports - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: gpus - value_type: gpu-request - description: GPU devices to add to the container ('all' to pass all GPUs) - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: group-add - value_type: list - description: Add additional groups to join - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-cmd - value_type: string - description: Command to run to check health - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-interval - value_type: duration - default_value: 0s - description: Time between running the check (ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-retries - value_type: int - default_value: "0" - description: Consecutive failures needed to report unhealthy - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-start-period - value_type: duration - default_value: 0s - description: | - Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-timeout - value_type: duration - default_value: 0s - description: | - Maximum time to allow one check to run (ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: help - value_type: bool - default_value: "false" - description: Print usage - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: hostname - shorthand: h - value_type: string - description: Container host name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: init - value_type: bool - default_value: "false" - description: | - Run an init inside the container that forwards signals and reaps processes - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Keep STDIN open even if not attached - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: io-maxbandwidth - value_type: bytes - default_value: "0" - description: | - Maximum IO bandwidth limit for the system drive (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: io-maxiops - value_type: uint64 - default_value: "0" - description: Maximum IOps limit for the system drive (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: ip - value_type: string - description: IPv4 address (e.g., 172.30.100.104) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ip6 - value_type: string - description: IPv6 address (e.g., 2001:db8::33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ipc - value_type: string - description: IPC mode to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Container isolation technology - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kernel-memory - value_type: bytes - default_value: "0" - description: Kernel memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - shorthand: l - value_type: list - description: Set meta data on a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label-file - value_type: list - description: Read in a line delimited file of labels - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link - value_type: list - description: Add link to another container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link-local-ip - value_type: list - description: Container IPv4/IPv6 link-local addresses - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-driver - value_type: string - description: Logging driver for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-opt - value_type: list - description: Log driver options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mac-address - value_type: string - description: Container MAC address (e.g., 92:d0:c6:0a:29:33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-reservation - value_type: bytes - default_value: "0" - description: Memory soft limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swappiness - value_type: int64 - default_value: "-1" - description: Tune container memory swappiness (0 to 100) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mount - value_type: mount - description: Attach a filesystem mount to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: name - value_type: string - description: Assign a name to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: net - value_type: network - description: Connect a container to a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: net-alias - value_type: list - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: network - description: Connect a container to a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network-alias - value_type: list - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-healthcheck - value_type: bool - default_value: "false" - description: Disable any container-specified HEALTHCHECK - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: oom-kill-disable - value_type: bool - default_value: "false" - description: Disable OOM Killer - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: oom-score-adj - value_type: int - default_value: "0" - description: Tune host's OOM preferences (-1000 to 1000) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pid - value_type: string - description: PID namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pids-limit - value_type: int64 - default_value: "0" - description: Tune container pids limit (set -1 for unlimited) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: privileged - value_type: bool - default_value: "false" - description: Give extended privileges to this container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish - shorthand: p - value_type: list - description: Publish a container's port(s) to the host - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish-all - shorthand: P - value_type: bool - default_value: "false" - description: Publish all exposed ports to random ports - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: string - default_value: missing - description: Pull image before creating ("always"|"missing"|"never") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: read-only - value_type: bool - default_value: "false" - description: Mount the container's root filesystem as read only - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart - value_type: string - default_value: "no" - description: Restart policy to apply when a container exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rm - value_type: bool - default_value: "false" - description: Automatically remove the container when it exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: runtime - value_type: string - description: Runtime to use for this container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: security-opt - value_type: list - description: Security Options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: shm-size - value_type: bytes - default_value: "0" - description: Size of /dev/shm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-signal - value_type: string - default_value: SIGTERM - description: Signal to stop a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-timeout - value_type: int - default_value: "0" - description: Timeout (in seconds) to stop a container - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: storage-opt - value_type: list - description: Storage driver options for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sysctl - value_type: map - default_value: map[] - description: Sysctl options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tmpfs - value_type: list - description: Mount a tmpfs directory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: ulimit - default_value: '[]' - description: Ulimit options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: userns - value_type: string - description: User namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: uts - value_type: string - description: UTS namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volume - shorthand: v - value_type: list - description: Bind mount a volume - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volume-driver - value_type: string - description: Optional volume driver for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volumes-from - value_type: list - description: Mount volumes from the specified container(s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: add-host + value_type: list + description: Add a custom host-to-IP mapping (host:ip) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: attach + shorthand: a + value_type: list + description: Attach to STDIN, STDOUT or STDERR + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: blkio-weight + value_type: uint16 + default_value: "0" + description: | + Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: blkio-weight-device + value_type: list + default_value: '[]' + description: Block IO weight (relative device weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-add + value_type: list + description: Add Linux capabilities + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-drop + value_type: list + description: Drop Linux capabilities + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroupns + value_type: string + description: |- + Cgroup namespace to use (host|private) + 'host': Run the container in the Docker host's cgroup namespace + 'private': Run the container in its own private cgroup namespace + '': Use the cgroup namespace as configured by the + default-cgroupns-mode option on the daemon (default) + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cidfile + value_type: string + description: Write the container ID to the file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-count + value_type: int64 + default_value: "0" + description: CPU count (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: cpu-percent + value_type: int64 + default_value: "0" + description: CPU percent (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-period + value_type: int64 + default_value: "0" + description: Limit CPU real-time period in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-runtime + value_type: int64 + default_value: "0" + description: Limit CPU real-time runtime in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpus + value_type: decimal + description: Number of CPUs + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device + value_type: list + description: Add a host device to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-cgroup-rule + value_type: list + description: Add a rule to the cgroup allowed devices list + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-read-bps + value_type: list + default_value: '[]' + description: Limit read rate (bytes per second) from a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-read-iops + value_type: list + default_value: '[]' + description: Limit read rate (IO per second) from a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-write-bps + value_type: list + default_value: '[]' + description: Limit write rate (bytes per second) to a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-write-iops + value_type: list + default_value: '[]' + description: Limit write rate (IO per second) to a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns + value_type: list + description: Set custom DNS servers + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-opt + value_type: list + description: Set DNS options + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-option + value_type: list + description: Set DNS options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-search + value_type: list + description: Set custom DNS search domains + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: domainname + value_type: string + description: Container NIS domain name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: entrypoint + value_type: string + description: Overwrite the default ENTRYPOINT of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env + shorthand: e + value_type: list + description: Set environment variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: expose + value_type: list + description: Expose a port or a range of ports + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: gpus + value_type: gpu-request + description: GPU devices to add to the container ('all' to pass all GPUs) + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: group-add + value_type: list + description: Add additional groups to join + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-cmd + value_type: string + description: Command to run to check health + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-interval + value_type: duration + default_value: 0s + description: Time between running the check (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-retries + value_type: int + default_value: "0" + description: Consecutive failures needed to report unhealthy + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-start-period + value_type: duration + default_value: 0s + description: | + Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-timeout + value_type: duration + default_value: 0s + description: Maximum time to allow one check to run (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: hostname + shorthand: h + value_type: string + description: Container host name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: init + value_type: bool + default_value: "false" + description: | + Run an init inside the container that forwards signals and reaps processes + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: interactive + shorthand: i + value_type: bool + default_value: "false" + description: Keep STDIN open even if not attached + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: io-maxbandwidth + value_type: bytes + default_value: "0" + description: Maximum IO bandwidth limit for the system drive (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: io-maxiops + value_type: uint64 + default_value: "0" + description: Maximum IOps limit for the system drive (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: ip + value_type: string + description: IPv4 address (e.g., 172.30.100.104) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ip6 + value_type: string + description: IPv6 address (e.g., 2001:db8::33) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ipc + value_type: string + description: IPC mode to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Container isolation technology + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: kernel-memory + value_type: bytes + default_value: "0" + description: Kernel memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + shorthand: l + value_type: list + description: Set meta data on a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label-file + value_type: list + description: Read in a line delimited file of labels + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link + value_type: list + description: Add link to another container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link-local-ip + value_type: list + description: Container IPv4/IPv6 link-local addresses + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-driver + value_type: string + description: Logging driver for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-opt + value_type: list + description: Log driver options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mac-address + value_type: string + description: Container MAC address (e.g., 92:d0:c6:0a:29:33) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-reservation + value_type: bytes + default_value: "0" + description: Memory soft limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: | + Swap limit equal to memory plus swap: '-1' to enable unlimited swap + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swappiness + value_type: int64 + default_value: "-1" + description: Tune container memory swappiness (0 to 100) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mount + value_type: mount + description: Attach a filesystem mount to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: name + value_type: string + description: Assign a name to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: net + value_type: network + description: Connect a container to a network + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: net-alias + value_type: list + description: Add network-scoped alias for the container + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: network + description: Connect a container to a network + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network-alias + value_type: list + description: Add network-scoped alias for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-healthcheck + value_type: bool + default_value: "false" + description: Disable any container-specified HEALTHCHECK + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: oom-kill-disable + value_type: bool + default_value: "false" + description: Disable OOM Killer + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: oom-score-adj + value_type: int + default_value: "0" + description: Tune host's OOM preferences (-1000 to 1000) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pid + value_type: string + description: PID namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pids-limit + value_type: int64 + default_value: "0" + description: Tune container pids limit (set -1 for unlimited) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: privileged + value_type: bool + default_value: "false" + description: Give extended privileges to this container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish + shorthand: p + value_type: list + description: Publish a container's port(s) to the host + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish-all + shorthand: P + value_type: bool + default_value: "false" + description: Publish all exposed ports to random ports + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pull + value_type: string + default_value: missing + description: Pull image before creating (`always`, `|missing`, `never`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the pull output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: read-only + value_type: bool + default_value: "false" + description: Mount the container's root filesystem as read only + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart + value_type: string + default_value: "no" + description: Restart policy to apply when a container exits + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rm + value_type: bool + default_value: "false" + description: Automatically remove the container when it exits + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: runtime + value_type: string + description: Runtime to use for this container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: security-opt + value_type: list + description: Security Options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: shm-size + value_type: bytes + default_value: "0" + description: Size of /dev/shm + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-signal + value_type: string + description: Signal to stop the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-timeout + value_type: int + default_value: "0" + description: Timeout (in seconds) to stop a container + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: storage-opt + value_type: list + description: Storage driver options for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sysctl + value_type: map + default_value: map[] + description: Sysctl options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tmpfs + value_type: list + description: Mount a tmpfs directory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tty + shorthand: t + value_type: bool + default_value: "false" + description: Allocate a pseudo-TTY + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: user + shorthand: u + value_type: string + description: 'Username or UID (format: [:])' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: userns + value_type: string + description: User namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: uts + value_type: string + description: UTS namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume + shorthand: v + value_type: list + description: Bind mount a volume + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume-driver + value_type: string + description: Optional volume driver for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volumes-from + value_type: list + description: Mount volumes from the specified container(s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workdir + shorthand: w + value_type: string + description: Working directory inside the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_diff.yaml b/_data/engine-cli/docker_container_diff.yaml index 48c1ccf5d3..80d309637a 100644 --- a/_data/engine-cli/docker_container_diff.yaml +++ b/_data/engine-cli/docker_container_diff.yaml @@ -1,9 +1,21 @@ command: docker container diff +aliases: docker container diff, docker diff short: Inspect changes to files or directories on a container's filesystem -long: Inspect changes to files or directories on a container's filesystem +long: See [docker diff](diff.md) for more information. usage: docker container diff CONTAINER pname: docker container plink: docker_container.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_exec.yaml b/_data/engine-cli/docker_container_exec.yaml index e5d38aee6f..88b049f203 100644 --- a/_data/engine-cli/docker_container_exec.yaml +++ b/_data/engine-cli/docker_container_exec.yaml @@ -1,95 +1,116 @@ command: docker container exec -short: Run a command in a running container -long: Run a command in a running container +aliases: docker container exec, docker exec +short: Execute a command in a running container +long: See [docker exec](exec.md) for more information. usage: docker container exec [OPTIONS] CONTAINER COMMAND [ARG...] pname: docker container plink: docker_container.yaml options: -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: 'Detached mode: run command in the background' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env - shorthand: e - value_type: list - description: Set environment variables - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-file - value_type: list - description: Read in a file of environment variables - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Keep STDIN open even if not attached - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: privileged - value_type: bool - default_value: "false" - description: Give extended privileges to the command - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - deprecated: false - min_api_version: "1.35" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: 'Detached mode: run command in the background' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach-keys + value_type: string + description: Override the key sequence for detaching a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env + shorthand: e + value_type: list + description: Set environment variables + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: interactive + shorthand: i + value_type: bool + default_value: "false" + description: Keep STDIN open even if not attached + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: privileged + value_type: bool + default_value: "false" + description: Give extended privileges to the command + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tty + shorthand: t + value_type: bool + default_value: "false" + description: Allocate a pseudo-TTY + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: user + shorthand: u + value_type: string + description: 'Username or UID (format: `[:]`)' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workdir + shorthand: w + value_type: string + description: Working directory inside the container + deprecated: false + hidden: false + min_api_version: "1.35" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_export.yaml b/_data/engine-cli/docker_container_export.yaml index e45c77d971..c2a7a52e5c 100644 --- a/_data/engine-cli/docker_container_export.yaml +++ b/_data/engine-cli/docker_container_export.yaml @@ -1,19 +1,32 @@ command: docker container export +aliases: docker container export, docker export short: Export a container's filesystem as a tar archive -long: Export a container's filesystem as a tar archive +long: See [docker export](export.md) for more information. usage: docker container export [OPTIONS] CONTAINER pname: docker container plink: docker_container.yaml options: -- option: output - shorthand: o - value_type: string - description: Write to a file, instead of STDOUT - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: output + shorthand: o + value_type: string + description: Write to a file, instead of STDOUT + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_inspect.yaml b/_data/engine-cli/docker_container_inspect.yaml index c27e4a4506..98a556750b 100644 --- a/_data/engine-cli/docker_container_inspect.yaml +++ b/_data/engine-cli/docker_container_inspect.yaml @@ -5,25 +5,42 @@ usage: docker container inspect [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: size - shorthand: s - value_type: bool - default_value: "false" - description: Display total file sizes - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: size + shorthand: s + value_type: bool + default_value: "false" + description: Display total file sizes + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_kill.yaml b/_data/engine-cli/docker_container_kill.yaml index 44c184add6..f069f0227c 100644 --- a/_data/engine-cli/docker_container_kill.yaml +++ b/_data/engine-cli/docker_container_kill.yaml @@ -1,20 +1,32 @@ command: docker container kill +aliases: docker container kill, docker kill short: Kill one or more running containers -long: Kill one or more running containers +long: See [docker kill](kill.md) for more information. usage: docker container kill [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml options: -- option: signal - shorthand: s - value_type: string - default_value: KILL - description: Signal to send to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: signal + shorthand: s + value_type: string + description: Signal to send to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_logs.yaml b/_data/engine-cli/docker_container_logs.yaml index f895b5c6af..b21f45a4ba 100644 --- a/_data/engine-cli/docker_container_logs.yaml +++ b/_data/engine-cli/docker_container_logs.yaml @@ -1,68 +1,86 @@ command: docker container logs +aliases: docker container logs, docker logs short: Fetch the logs of a container -long: Fetch the logs of a container +long: See [docker logs](logs.md) for more information. usage: docker container logs [OPTIONS] CONTAINER pname: docker container plink: docker_container.yaml options: -- option: details - value_type: bool - default_value: "false" - description: Show extra details provided to logs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: follow - shorthand: f - value_type: bool - default_value: "false" - description: Follow log output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: since - value_type: string - description: | - Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tail - shorthand: "n" - value_type: string - default_value: all - description: Number of lines to show from the end of the logs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: timestamps - shorthand: t - value_type: bool - default_value: "false" - description: Show timestamps - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: until - value_type: string - description: | - Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) - deprecated: false - min_api_version: "1.35" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: details + value_type: bool + default_value: "false" + description: Show extra details provided to logs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: follow + shorthand: f + value_type: bool + default_value: "false" + description: Follow log output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: since + value_type: string + description: | + Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tail + shorthand: "n" + value_type: string + default_value: all + description: Number of lines to show from the end of the logs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: timestamps + shorthand: t + value_type: bool + default_value: "false" + description: Show timestamps + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: until + value_type: string + description: | + Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) + deprecated: false + hidden: false + min_api_version: "1.35" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_ls.yaml b/_data/engine-cli/docker_container_ls.yaml index 3c7bd751c6..4a53f4b90e 100644 --- a/_data/engine-cli/docker_container_ls.yaml +++ b/_data/engine-cli/docker_container_ls.yaml @@ -1,87 +1,112 @@ command: docker container ls -aliases: ps, list +aliases: docker container ls, docker container list, docker container ps, docker ps short: List containers -long: List containers +long: See [docker ps](ps.md) for more information. usage: docker container ls [OPTIONS] pname: docker container plink: docker_container.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Show all containers (default shows just running) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print containers using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: last - shorthand: "n" - value_type: int - default_value: "-1" - description: Show n last created containers (includes all states) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: latest - shorthand: l - value_type: bool - default_value: "false" - description: Show the latest created container (includes all states) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display container IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: size - shorthand: s - value_type: bool - default_value: "false" - description: Display total file sizes - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Show all containers (default shows just running) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: last + shorthand: "n" + value_type: int + default_value: "-1" + description: Show n last created containers (includes all states) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: latest + shorthand: l + value_type: bool + default_value: "false" + description: Show the latest created container (includes all states) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display container IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: size + shorthand: s + value_type: bool + default_value: "false" + description: Display total file sizes + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_pause.yaml b/_data/engine-cli/docker_container_pause.yaml index dd28f672aa..2840a24484 100644 --- a/_data/engine-cli/docker_container_pause.yaml +++ b/_data/engine-cli/docker_container_pause.yaml @@ -1,9 +1,21 @@ command: docker container pause +aliases: docker container pause, docker pause short: Pause all processes within one or more containers -long: Pause all processes within one or more containers +long: See [docker pause](pause.md) for more information. usage: docker container pause CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_port.yaml b/_data/engine-cli/docker_container_port.yaml index e211a449a3..03c567fa2e 100644 --- a/_data/engine-cli/docker_container_port.yaml +++ b/_data/engine-cli/docker_container_port.yaml @@ -1,9 +1,21 @@ command: docker container port +aliases: docker container port, docker port short: List port mappings or a specific mapping for the container -long: List port mappings or a specific mapping for the container +long: See [docker port](port.md) for more information. usage: docker container port CONTAINER [PRIVATE_PORT[/PROTO]] pname: docker container plink: docker_container.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_prune.yaml b/_data/engine-cli/docker_container_prune.yaml index db52af03d1..8819637102 100644 --- a/_data/engine-cli/docker_container_prune.yaml +++ b/_data/engine-cli/docker_container_prune.yaml @@ -5,108 +5,122 @@ usage: docker container prune [OPTIONS] pname: docker container plink: docker_container.yaml options: -- option: filter - value_type: filter - description: Provide filter values (e.g. 'until=') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Do not prompt for confirmation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + value_type: filter + description: Provide filter values (e.g. `until=`) + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Do not prompt for confirmation + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Prune containers + ### Prune containers - ```console - $ docker container prune - WARNING! This will remove all stopped containers. - Are you sure you want to continue? [y/N] y - Deleted Containers: - 4a7f7eebae0f63178aff7eb0aa39cd3f0627a203ab2df258c1a00b456cf20063 - f98f9c2aa1eaf727e4ec9c0283bc7d4aa4762fbdba7f26191f26c97f64090360 + ```console + $ docker container prune + WARNING! This will remove all stopped containers. + Are you sure you want to continue? [y/N] y + Deleted Containers: + 4a7f7eebae0f63178aff7eb0aa39cd3f0627a203ab2df258c1a00b456cf20063 + f98f9c2aa1eaf727e4ec9c0283bc7d4aa4762fbdba7f26191f26c97f64090360 - Total reclaimed space: 212 B - ``` + Total reclaimed space: 212 B + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - 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 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: + The currently supported filters are: - * until (``) - only remove containers created before given timestamp - * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove containers with (or without, in case `label!=...` is used) the specified labels. + * until (``) - only remove containers created before given timestamp + * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove containers with (or without, in case `label!=...` is used) the specified labels. - The `until` filter can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed - relative to the daemon machine’s time. Supported formats for date - formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local - timezone on the daemon will be used if you do not provide either a `Z` or a - `+-00:00` timezone offset at the end of the timestamp. When providing Unix - timestamps enter seconds[.nanoseconds], where seconds is the number of seconds - that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap - seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a - fraction of a second no more than nine digits long. + The `until` filter can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the daemon machine’s time. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the daemon will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. - The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), - which removes containers with the specified labels. The other - format is the `label!=...` (`label!=` or `label!==`), which removes - containers without the specified labels. + The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), + which removes containers with the specified labels. The other + format is the `label!=...` (`label!=` or `label!==`), which removes + containers without the specified labels. - The following removes containers created more than 5 minutes ago: + The following removes containers created more than 5 minutes ago: - ```console - $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + ```console + $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' - CONTAINER ID IMAGE COMMAND CREATED AT STATUS - 61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 41 seconds ago - 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 12 minutes ago + CONTAINER ID IMAGE COMMAND CREATED AT STATUS + 61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 41 seconds ago + 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 12 minutes ago - $ docker container prune --force --filter "until=5m" + $ docker container prune --force --filter "until=5m" - Deleted Containers: - 53a9bc23a5168b6caa2bfbefddf1b30f93c7ad57f3dec271fd32707497cb9369 + Deleted Containers: + 53a9bc23a5168b6caa2bfbefddf1b30f93c7ad57f3dec271fd32707497cb9369 - Total reclaimed space: 25 B + Total reclaimed space: 25 B - $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' - CONTAINER ID IMAGE COMMAND CREATED AT STATUS - 61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 44 seconds ago - ``` + CONTAINER ID IMAGE COMMAND CREATED AT STATUS + 61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 44 seconds ago + ``` - The following removes containers created before `2017-01-04T13:10:00`: + The following removes containers created before `2017-01-04T13:10:00`: - ```console - $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + ```console + $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' - CONTAINER ID IMAGE COMMAND CREATED AT STATUS - 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 7 minutes ago - 4a75091a6d61 busybox "sh" 2017-01-04 13:09:53 -0800 PST Exited (0) 9 minutes ago + CONTAINER ID IMAGE COMMAND CREATED AT STATUS + 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 7 minutes ago + 4a75091a6d61 busybox "sh" 2017-01-04 13:09:53 -0800 PST Exited (0) 9 minutes ago - $ docker container prune --force --filter "until=2017-01-04T13:10:00" + $ docker container prune --force --filter "until=2017-01-04T13:10:00" - Deleted Containers: - 4a75091a6d618526fcd8b33ccd6e5928ca2a64415466f768a6180004b0c72c6c + Deleted Containers: + 4a75091a6d618526fcd8b33ccd6e5928ca2a64415466f768a6180004b0c72c6c - Total reclaimed space: 27 B + Total reclaimed space: 27 B - $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' - CONTAINER ID IMAGE COMMAND CREATED AT STATUS - 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 9 minutes ago - ``` + CONTAINER ID IMAGE COMMAND CREATED AT STATUS + 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 9 minutes ago + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_container_rename.yaml b/_data/engine-cli/docker_container_rename.yaml index 088cfe0119..c6a144fdef 100644 --- a/_data/engine-cli/docker_container_rename.yaml +++ b/_data/engine-cli/docker_container_rename.yaml @@ -1,9 +1,21 @@ command: docker container rename +aliases: docker container rename, docker rename short: Rename a container -long: Rename a container +long: See [docker rename](rename.md) for more information. usage: docker container rename CONTAINER NEW_NAME pname: docker container plink: docker_container.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_restart.yaml b/_data/engine-cli/docker_container_restart.yaml index 74d8bbac86..a63b75b3f5 100644 --- a/_data/engine-cli/docker_container_restart.yaml +++ b/_data/engine-cli/docker_container_restart.yaml @@ -1,20 +1,43 @@ command: docker container restart +aliases: docker container restart, docker restart short: Restart one or more containers -long: Restart one or more containers +long: See [docker restart](restart.md) for more information. usage: docker container restart [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml options: -- option: time - shorthand: t - value_type: int - default_value: "10" - description: Seconds to wait for stop before killing the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: signal + shorthand: s + value_type: string + description: Signal to send to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: time + shorthand: t + value_type: int + default_value: "0" + description: Seconds to wait before killing the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_rm.yaml b/_data/engine-cli/docker_container_rm.yaml index cce60569f6..933c3a5802 100644 --- a/_data/engine-cli/docker_container_rm.yaml +++ b/_data/engine-cli/docker_container_rm.yaml @@ -1,40 +1,55 @@ command: docker container rm +aliases: docker container rm, docker container remove, docker rm short: Remove one or more containers -long: Remove one or more containers +long: See [docker rm](rm.md) for more information. usage: docker container rm [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force the removal of a running container (uses SIGKILL) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link - shorthand: l - value_type: bool - default_value: "false" - description: Remove the specified link - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volumes - shorthand: v - value_type: bool - default_value: "false" - description: Remove anonymous volumes associated with the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force the removal of a running container (uses SIGKILL) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link + shorthand: l + value_type: bool + default_value: "false" + description: Remove the specified link + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volumes + shorthand: v + value_type: bool + default_value: "false" + description: Remove anonymous volumes associated with the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_run.yaml b/_data/engine-cli/docker_container_run.yaml index e98cfeec6d..bebe358087 100644 --- a/_data/engine-cli/docker_container_run.yaml +++ b/_data/engine-cli/docker_container_run.yaml @@ -1,918 +1,1030 @@ command: docker container run -short: Run a command in a new container -long: Run a command in a new container +aliases: docker container run, docker run +short: Create and run a new container from an image +long: See [docker run](run.md) for more information. usage: docker container run [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker container plink: docker_container.yaml options: -- option: add-host - value_type: list - description: Add a custom host-to-IP mapping (host:ip) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: attach - shorthand: a - value_type: list - description: Attach to STDIN, STDOUT or STDERR - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: blkio-weight - value_type: uint16 - default_value: "0" - description: | - Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: blkio-weight-device - value_type: list - default_value: '[]' - description: Block IO weight (relative device weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-add - value_type: list - description: Add Linux capabilities - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-drop - value_type: list - description: Drop Linux capabilities - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroup-parent - value_type: string - description: Optional parent cgroup for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroupns - value_type: string - description: |- - Cgroup namespace to use (host|private) - 'host': Run the container in the Docker host's cgroup namespace - 'private': Run the container in its own private cgroup namespace - '': Use the cgroup namespace as configured by the - default-cgroupns-mode option on the daemon (default) - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cidfile - value_type: string - description: Write the container ID to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-count - value_type: int64 - default_value: "0" - description: CPU count (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: cpu-percent - value_type: int64 - default_value: "0" - description: CPU percent (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-period - value_type: int64 - default_value: "0" - description: Limit CPU real-time period in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-runtime - value_type: int64 - default_value: "0" - description: Limit CPU real-time runtime in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpus - value_type: decimal - description: Number of CPUs - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: Run container in background and print container ID - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device - value_type: list - description: Add a host device to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-cgroup-rule - value_type: list - description: Add a rule to the cgroup allowed devices list - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-read-bps - value_type: list - default_value: '[]' - description: Limit read rate (bytes per second) from a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-read-iops - value_type: list - default_value: '[]' - description: Limit read rate (IO per second) from a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-write-bps - value_type: list - default_value: '[]' - description: Limit write rate (bytes per second) to a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-write-iops - value_type: list - default_value: '[]' - description: Limit write rate (IO per second) to a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns - value_type: list - description: Set custom DNS servers - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-opt - value_type: list - description: Set DNS options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-option - value_type: list - description: Set DNS options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-search - value_type: list - description: Set custom DNS search domains - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: domainname - value_type: string - description: Container NIS domain name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: entrypoint - value_type: string - description: Overwrite the default ENTRYPOINT of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env - shorthand: e - value_type: list - description: Set environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-file - value_type: list - description: Read in a file of environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: expose - value_type: list - description: Expose a port or a range of ports - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: gpus - value_type: gpu-request - description: GPU devices to add to the container ('all' to pass all GPUs) - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: group-add - value_type: list - description: Add additional groups to join - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-cmd - value_type: string - description: Command to run to check health - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-interval - value_type: duration - default_value: 0s - description: Time between running the check (ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-retries - value_type: int - default_value: "0" - description: Consecutive failures needed to report unhealthy - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-start-period - value_type: duration - default_value: 0s - description: | - Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-timeout - value_type: duration - default_value: 0s - description: | - Maximum time to allow one check to run (ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: help - value_type: bool - default_value: "false" - description: Print usage - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: hostname - shorthand: h - value_type: string - description: Container host name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: init - value_type: bool - default_value: "false" - description: | - Run an init inside the container that forwards signals and reaps processes - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Keep STDIN open even if not attached - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: io-maxbandwidth - value_type: bytes - default_value: "0" - description: | - Maximum IO bandwidth limit for the system drive (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: io-maxiops - value_type: uint64 - default_value: "0" - description: Maximum IOps limit for the system drive (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: ip - value_type: string - description: IPv4 address (e.g., 172.30.100.104) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ip6 - value_type: string - description: IPv6 address (e.g., 2001:db8::33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ipc - value_type: string - description: IPC mode to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Container isolation technology - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kernel-memory - value_type: bytes - default_value: "0" - description: Kernel memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - shorthand: l - value_type: list - description: Set meta data on a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label-file - value_type: list - description: Read in a line delimited file of labels - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link - value_type: list - description: Add link to another container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link-local-ip - value_type: list - description: Container IPv4/IPv6 link-local addresses - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-driver - value_type: string - description: Logging driver for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-opt - value_type: list - description: Log driver options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mac-address - value_type: string - description: Container MAC address (e.g., 92:d0:c6:0a:29:33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-reservation - value_type: bytes - default_value: "0" - description: Memory soft limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swappiness - value_type: int64 - default_value: "-1" - description: Tune container memory swappiness (0 to 100) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mount - value_type: mount - description: Attach a filesystem mount to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: name - value_type: string - description: Assign a name to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: net - value_type: network - description: Connect a container to a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: net-alias - value_type: list - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: network - description: Connect a container to a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network-alias - value_type: list - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-healthcheck - value_type: bool - default_value: "false" - description: Disable any container-specified HEALTHCHECK - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: oom-kill-disable - value_type: bool - default_value: "false" - description: Disable OOM Killer - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: oom-score-adj - value_type: int - default_value: "0" - description: Tune host's OOM preferences (-1000 to 1000) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pid - value_type: string - description: PID namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pids-limit - value_type: int64 - default_value: "0" - description: Tune container pids limit (set -1 for unlimited) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: privileged - value_type: bool - default_value: "false" - description: Give extended privileges to this container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish - shorthand: p - value_type: list - description: Publish a container's port(s) to the host - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish-all - shorthand: P - value_type: bool - default_value: "false" - description: Publish all exposed ports to random ports - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: string - default_value: missing - description: Pull image before running ("always"|"missing"|"never") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: read-only - value_type: bool - default_value: "false" - description: Mount the container's root filesystem as read only - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart - value_type: string - default_value: "no" - description: Restart policy to apply when a container exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rm - value_type: bool - default_value: "false" - description: Automatically remove the container when it exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: runtime - value_type: string - description: Runtime to use for this container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: security-opt - value_type: list - description: Security Options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: shm-size - value_type: bytes - default_value: "0" - description: Size of /dev/shm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sig-proxy - value_type: bool - default_value: "true" - description: Proxy received signals to the process - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-signal - value_type: string - default_value: SIGTERM - description: Signal to stop a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-timeout - value_type: int - default_value: "0" - description: Timeout (in seconds) to stop a container - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: storage-opt - value_type: list - description: Storage driver options for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sysctl - value_type: map - default_value: map[] - description: Sysctl options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tmpfs - value_type: list - description: Mount a tmpfs directory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: ulimit - default_value: '[]' - description: Ulimit options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: userns - value_type: string - description: User namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: uts - value_type: string - description: UTS namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volume - shorthand: v - value_type: list - description: Bind mount a volume - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volume-driver - value_type: string - description: Optional volume driver for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volumes-from - value_type: list - description: Mount volumes from the specified container(s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: add-host + value_type: list + description: Add a custom host-to-IP mapping (host:ip) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: attach + shorthand: a + value_type: list + description: Attach to STDIN, STDOUT or STDERR + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: blkio-weight + value_type: uint16 + default_value: "0" + description: | + Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: blkio-weight-device + value_type: list + default_value: '[]' + description: Block IO weight (relative device weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-add + value_type: list + description: Add Linux capabilities + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-drop + value_type: list + description: Drop Linux capabilities + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroupns + value_type: string + description: |- + Cgroup namespace to use (host|private) + 'host': Run the container in the Docker host's cgroup namespace + 'private': Run the container in its own private cgroup namespace + '': Use the cgroup namespace as configured by the + default-cgroupns-mode option on the daemon (default) + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cidfile + value_type: string + description: Write the container ID to the file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-count + value_type: int64 + default_value: "0" + description: CPU count (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: cpu-percent + value_type: int64 + default_value: "0" + description: CPU percent (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-period + value_type: int64 + default_value: "0" + description: Limit CPU real-time period in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-runtime + value_type: int64 + default_value: "0" + description: Limit CPU real-time runtime in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpus + value_type: decimal + description: Number of CPUs + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: Run container in background and print container ID + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach-keys + value_type: string + description: Override the key sequence for detaching a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device + value_type: list + description: Add a host device to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-cgroup-rule + value_type: list + description: Add a rule to the cgroup allowed devices list + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-read-bps + value_type: list + default_value: '[]' + description: Limit read rate (bytes per second) from a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-read-iops + value_type: list + default_value: '[]' + description: Limit read rate (IO per second) from a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-write-bps + value_type: list + default_value: '[]' + description: Limit write rate (bytes per second) to a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-write-iops + value_type: list + default_value: '[]' + description: Limit write rate (IO per second) to a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns + value_type: list + description: Set custom DNS servers + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-opt + value_type: list + description: Set DNS options + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-option + value_type: list + description: Set DNS options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-search + value_type: list + description: Set custom DNS search domains + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: domainname + value_type: string + description: Container NIS domain name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: entrypoint + value_type: string + description: Overwrite the default ENTRYPOINT of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env + shorthand: e + value_type: list + description: Set environment variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: expose + value_type: list + description: Expose a port or a range of ports + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: gpus + value_type: gpu-request + description: GPU devices to add to the container ('all' to pass all GPUs) + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: group-add + value_type: list + description: Add additional groups to join + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-cmd + value_type: string + description: Command to run to check health + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-interval + value_type: duration + default_value: 0s + description: Time between running the check (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-retries + value_type: int + default_value: "0" + description: Consecutive failures needed to report unhealthy + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-start-period + value_type: duration + default_value: 0s + description: | + Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-timeout + value_type: duration + default_value: 0s + description: Maximum time to allow one check to run (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: hostname + shorthand: h + value_type: string + description: Container host name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: init + value_type: bool + default_value: "false" + description: | + Run an init inside the container that forwards signals and reaps processes + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: interactive + shorthand: i + value_type: bool + default_value: "false" + description: Keep STDIN open even if not attached + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: io-maxbandwidth + value_type: bytes + default_value: "0" + description: Maximum IO bandwidth limit for the system drive (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: io-maxiops + value_type: uint64 + default_value: "0" + description: Maximum IOps limit for the system drive (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: ip + value_type: string + description: IPv4 address (e.g., 172.30.100.104) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ip6 + value_type: string + description: IPv6 address (e.g., 2001:db8::33) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ipc + value_type: string + description: IPC mode to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Container isolation technology + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: kernel-memory + value_type: bytes + default_value: "0" + description: Kernel memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + shorthand: l + value_type: list + description: Set meta data on a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label-file + value_type: list + description: Read in a line delimited file of labels + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link + value_type: list + description: Add link to another container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link-local-ip + value_type: list + description: Container IPv4/IPv6 link-local addresses + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-driver + value_type: string + description: Logging driver for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-opt + value_type: list + description: Log driver options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mac-address + value_type: string + description: Container MAC address (e.g., 92:d0:c6:0a:29:33) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-reservation + value_type: bytes + default_value: "0" + description: Memory soft limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: | + Swap limit equal to memory plus swap: '-1' to enable unlimited swap + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swappiness + value_type: int64 + default_value: "-1" + description: Tune container memory swappiness (0 to 100) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mount + value_type: mount + description: Attach a filesystem mount to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: name + value_type: string + description: Assign a name to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: net + value_type: network + description: Connect a container to a network + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: net-alias + value_type: list + description: Add network-scoped alias for the container + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: network + description: Connect a container to a network + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network-alias + value_type: list + description: Add network-scoped alias for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-healthcheck + value_type: bool + default_value: "false" + description: Disable any container-specified HEALTHCHECK + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: oom-kill-disable + value_type: bool + default_value: "false" + description: Disable OOM Killer + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: oom-score-adj + value_type: int + default_value: "0" + description: Tune host's OOM preferences (-1000 to 1000) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pid + value_type: string + description: PID namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pids-limit + value_type: int64 + default_value: "0" + description: Tune container pids limit (set -1 for unlimited) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: privileged + value_type: bool + default_value: "false" + description: Give extended privileges to this container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish + shorthand: p + value_type: list + description: Publish a container's port(s) to the host + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish-all + shorthand: P + value_type: bool + default_value: "false" + description: Publish all exposed ports to random ports + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pull + value_type: string + default_value: missing + description: Pull image before running (`always`, `missing`, `never`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the pull output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: read-only + value_type: bool + default_value: "false" + description: Mount the container's root filesystem as read only + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart + value_type: string + default_value: "no" + description: Restart policy to apply when a container exits + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rm + value_type: bool + default_value: "false" + description: Automatically remove the container when it exits + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: runtime + value_type: string + description: Runtime to use for this container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: security-opt + value_type: list + description: Security Options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: shm-size + value_type: bytes + default_value: "0" + description: Size of /dev/shm + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sig-proxy + value_type: bool + default_value: "true" + description: Proxy received signals to the process + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-signal + value_type: string + description: Signal to stop the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-timeout + value_type: int + default_value: "0" + description: Timeout (in seconds) to stop a container + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: storage-opt + value_type: list + description: Storage driver options for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sysctl + value_type: map + default_value: map[] + description: Sysctl options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tmpfs + value_type: list + description: Mount a tmpfs directory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tty + shorthand: t + value_type: bool + default_value: "false" + description: Allocate a pseudo-TTY + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: user + shorthand: u + value_type: string + description: 'Username or UID (format: [:])' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: userns + value_type: string + description: User namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: uts + value_type: string + description: UTS namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume + shorthand: v + value_type: list + description: Bind mount a volume + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume-driver + value_type: string + description: Optional volume driver for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volumes-from + value_type: list + description: Mount volumes from the specified container(s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workdir + shorthand: w + value_type: string + description: Working directory inside the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_start.yaml b/_data/engine-cli/docker_container_start.yaml index e31d6be262..e01f2b8612 100644 --- a/_data/engine-cli/docker_container_start.yaml +++ b/_data/engine-cli/docker_container_start.yaml @@ -1,56 +1,73 @@ command: docker container start +aliases: docker container start, docker start short: Start one or more stopped containers -long: Start one or more stopped containers +long: See [docker start](start.md) for more information. usage: docker container start [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml options: -- option: attach - shorthand: a - value_type: bool - default_value: "false" - description: Attach STDOUT/STDERR and forward signals - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: checkpoint - value_type: string - description: Restore from this checkpoint - deprecated: false - experimental: true - experimentalcli: false - kubernetes: false - swarm: false - os_type: linux -- option: checkpoint-dir - value_type: string - description: Use a custom checkpoint storage directory - deprecated: false - experimental: true - experimentalcli: false - kubernetes: false - swarm: false - os_type: linux -- option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Attach container's STDIN - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: attach + shorthand: a + value_type: bool + default_value: "false" + description: Attach STDOUT/STDERR and forward signals + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: checkpoint + value_type: string + description: Restore from this checkpoint + deprecated: false + hidden: false + experimental: true + experimentalcli: false + kubernetes: false + swarm: false + os_type: linux + - option: checkpoint-dir + value_type: string + description: Use a custom checkpoint storage directory + deprecated: false + hidden: false + experimental: true + experimentalcli: false + kubernetes: false + swarm: false + os_type: linux + - option: detach-keys + value_type: string + description: Override the key sequence for detaching a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: interactive + shorthand: i + value_type: bool + default_value: "false" + description: Attach container's STDIN + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_stats.yaml b/_data/engine-cli/docker_container_stats.yaml index d8f081e8b5..c0311eaee0 100644 --- a/_data/engine-cli/docker_container_stats.yaml +++ b/_data/engine-cli/docker_container_stats.yaml @@ -1,46 +1,68 @@ command: docker container stats +aliases: docker container stats, docker stats short: Display a live stream of container(s) resource usage statistics -long: Display a live stream of container(s) resource usage statistics +long: See [docker stats](stats.md) for more information. usage: docker container stats [OPTIONS] [CONTAINER...] pname: docker container plink: docker_container.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Show all containers (default shows just running) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print images using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-stream - value_type: bool - default_value: "false" - description: Disable streaming stats and only pull the first result - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Do not truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Show all containers (default shows just running) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-stream + value_type: bool + default_value: "false" + description: Disable streaming stats and only pull the first result + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Do not truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_stop.yaml b/_data/engine-cli/docker_container_stop.yaml index 80fa23dc99..5310d0df2f 100644 --- a/_data/engine-cli/docker_container_stop.yaml +++ b/_data/engine-cli/docker_container_stop.yaml @@ -1,20 +1,43 @@ command: docker container stop +aliases: docker container stop, docker stop short: Stop one or more running containers -long: Stop one or more running containers +long: See [docker stop](stop.md) for more information. usage: docker container stop [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml options: -- option: time - shorthand: t - value_type: int - default_value: "10" - description: Seconds to wait for stop before killing it - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: signal + shorthand: s + value_type: string + description: Signal to send to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: time + shorthand: t + value_type: int + default_value: "0" + description: Seconds to wait before killing the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_top.yaml b/_data/engine-cli/docker_container_top.yaml index c35656326d..59477cc37f 100644 --- a/_data/engine-cli/docker_container_top.yaml +++ b/_data/engine-cli/docker_container_top.yaml @@ -1,9 +1,21 @@ command: docker container top +aliases: docker container top, docker top short: Display the running processes of a container -long: Display the running processes of a container +long: See [docker top](top.md) for more information. usage: docker container top CONTAINER [ps OPTIONS] pname: docker container plink: docker_container.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_unpause.yaml b/_data/engine-cli/docker_container_unpause.yaml index fcd8612ee6..0c0fdf5dcc 100644 --- a/_data/engine-cli/docker_container_unpause.yaml +++ b/_data/engine-cli/docker_container_unpause.yaml @@ -1,9 +1,21 @@ command: docker container unpause +aliases: docker container unpause, docker unpause short: Unpause all processes within one or more containers -long: Unpause all processes within one or more containers +long: See [docker unpause](unpause.md) for more information. usage: docker container unpause CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_update.yaml b/_data/engine-cli/docker_container_update.yaml index 252ce31269..9bf0e67886 100644 --- a/_data/engine-cli/docker_container_update.yaml +++ b/_data/engine-cli/docker_container_update.yaml @@ -1,149 +1,175 @@ command: docker container update +aliases: docker container update, docker update short: Update configuration of one or more containers -long: Update configuration of one or more containers +long: See [docker update](update.md) for more information. usage: docker container update [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml options: -- option: blkio-weight - value_type: uint16 - default_value: "0" - description: | - Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-period - value_type: int64 - default_value: "0" - description: Limit the CPU real-time period in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-runtime - value_type: int64 - default_value: "0" - description: Limit the CPU real-time runtime in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpus - value_type: decimal - description: Number of CPUs - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kernel-memory - value_type: bytes - default_value: "0" - description: Kernel memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-reservation - value_type: bytes - default_value: "0" - description: Memory soft limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pids-limit - value_type: int64 - default_value: "0" - description: Tune container pids limit (set -1 for unlimited) - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart - value_type: string - description: Restart policy to apply when a container exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: blkio-weight + value_type: uint16 + default_value: "0" + description: | + Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-period + value_type: int64 + default_value: "0" + description: Limit the CPU real-time period in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-runtime + value_type: int64 + default_value: "0" + description: Limit the CPU real-time runtime in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpus + value_type: decimal + description: Number of CPUs + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: kernel-memory + value_type: bytes + default_value: "0" + description: Kernel memory limit (deprecated) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-reservation + value_type: bytes + default_value: "0" + description: Memory soft limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: 'Swap limit equal to memory plus swap: -1 to enable unlimited swap' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pids-limit + value_type: int64 + default_value: "0" + description: Tune container pids limit (set -1 for unlimited) + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart + value_type: string + description: Restart policy to apply when a container exits + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_wait.yaml b/_data/engine-cli/docker_container_wait.yaml index 9edf8772ba..5ea9ee5a81 100644 --- a/_data/engine-cli/docker_container_wait.yaml +++ b/_data/engine-cli/docker_container_wait.yaml @@ -1,9 +1,21 @@ command: docker container wait +aliases: docker container wait, docker wait short: Block until one or more containers stop, then print their exit codes -long: Block until one or more containers stop, then print their exit codes +long: See [docker wait](wait.md) for more information. usage: docker container wait CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context.yaml b/_data/engine-cli/docker_context.yaml index 720419555c..0cf548d585 100644 --- a/_data/engine-cli/docker_context.yaml +++ b/_data/engine-cli/docker_context.yaml @@ -5,23 +5,36 @@ usage: docker context pname: docker plink: docker.yaml cname: -- docker context create -- docker context export -- docker context import -- docker context inspect -- docker context ls -- docker context rm -- docker context update -- docker context use + - docker context create + - docker context export + - docker context import + - docker context inspect + - docker context ls + - docker context rm + - docker context show + - docker context update + - docker context use clink: -- docker_context_create.yaml -- docker_context_export.yaml -- docker_context_import.yaml -- docker_context_inspect.yaml -- docker_context_ls.yaml -- docker_context_rm.yaml -- docker_context_update.yaml -- docker_context_use.yaml + - docker_context_create.yaml + - docker_context_export.yaml + - docker_context_import.yaml + - docker_context_inspect.yaml + - docker_context_ls.yaml + - docker_context_rm.yaml + - docker_context_show.yaml + - docker_context_update.yaml + - docker_context_use.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context_create.yaml b/_data/engine-cli/docker_context_create.yaml index 562ee3c474..91fa827796 100644 --- a/_data/engine-cli/docker_context_create.yaml +++ b/_data/engine-cli/docker_context_create.yaml @@ -1,122 +1,124 @@ command: docker context create short: Create a context long: |- - Creates a new `context`. This allows you to quickly switch the cli - configuration to connect to different clusters or single nodes. + Creates a new `context`. This allows you to quickly switch the cli + configuration to connect to different clusters or single nodes. usage: docker context create [OPTIONS] CONTEXT pname: docker context plink: docker_context.yaml options: -- option: default-stack-orchestrator - value_type: string - description: | - Default orchestrator for stack operations to use with this context (swarm|kubernetes|all) - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: description - value_type: string - description: Description of the context - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: docker - value_type: stringToString - default_value: '[]' - description: set the docker endpoint - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: from - value_type: string - description: create context from a named context - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kubernetes - value_type: stringToString - default_value: '[]' - description: set the kubernetes endpoint - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false + - option: default-stack-orchestrator + value_type: string + description: | + Default orchestrator for stack operations to use with this context (`swarm`, `kubernetes`, `all`) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: description + value_type: string + description: Description of the context + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: docker + value_type: stringToString + default_value: '[]' + description: set the docker endpoint + details_url: '#docker' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: from + value_type: string + description: create context from a named context + details_url: '#from' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: kubernetes + value_type: stringToString + default_value: '[]' + description: set the kubernetes endpoint + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: true + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Create a context with a docker and kubernetes endpoint + ### Create a context with a docker endpoint (--docker) {#docker} - To create a context from scratch provide the docker and, if required, - kubernetes options. The example below creates the context `my-context` - with a docker endpoint of `/var/run/docker.sock` and a kubernetes configuration - sourced from the file `/home/me/my-kube-config`: + To create a context from scratch provide the docker and, if required, + kubernetes options. The example below creates the context `my-context` + with a docker endpoint of `/var/run/docker.sock`: - ```console - $ docker context create \ - --docker host=unix:///var/run/docker.sock \ - --kubernetes config-file=/home/me/my-kube-config \ - my-context - ``` + ```console + $ docker context create \ + --docker host=unix:///var/run/docker.sock \ + my-context + ``` - ### Create a context based on an existing context (--from) + ### Create a context based on an existing context (--from) {#from} - Use the `--from=` option to create a new context from - an existing context. The example below creates a new context named `my-context` - from the existing context `existing-context`: + Use the `--from=` option to create a new context from + an existing context. The example below creates a new context named `my-context` + from the existing context `existing-context`: - ```console - $ docker context create --from existing-context my-context - ``` + ```console + $ docker context create --from existing-context my-context + ``` - If the `--from` option is not set, the `context` is created from the current context: + If the `--from` option is not set, the `context` is created from the current context: - ```console - $ docker context create my-context - ``` + ```console + $ docker context create my-context + ``` - This can be used to create a context out of an existing `DOCKER_HOST` based script: + This can be used to create a context out of an existing `DOCKER_HOST` based script: - ```console - $ source my-setup-script.sh - $ docker context create my-context - ``` + ```console + $ source my-setup-script.sh + $ docker context create my-context + ``` - To source only the `docker` endpoint configuration from an existing context - use the `--docker from=` option. The example below creates a - new context named `my-context` using the docker endpoint configuration from - the existing context `existing-context` and a kubernetes configuration sourced - from the file `/home/me/my-kube-config`: + To source the `docker` endpoint configuration from an existing context + use the `--docker from=` option. The example below creates a + new context named `my-context` using the docker endpoint configuration from + the existing context `existing-context`: - ```console - $ docker context create \ - --docker from=existing-context \ - --kubernetes config-file=/home/me/my-kube-config \ - my-context - ``` + ```console + $ docker context create \ + --docker from=existing-context \ + my-context + ``` - To source only the `kubernetes` configuration from an existing context use the - `--kubernetes from=` option. The example below creates a new - context named `my-context` using the kuberentes configuration from the existing - context `existing-context` and a docker endpoint of `/var/run/docker.sock`: + Docker endpoints configurations, as well as the description can be modified with + `docker context update`. - ```console - $ docker context create \ - --docker host=unix:///var/run/docker.sock \ - --kubernetes from=existing-context \ - my-context - ``` - - Docker and Kubernetes endpoints configurations, as well as default stack - orchestrator and description can be modified with `docker context update`. - - Refer to the [`docker context update` reference](context_update.md) for details. + Refer to the [`docker context update` reference](context_update.md) for details. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context_export.yaml b/_data/engine-cli/docker_context_export.yaml index 551815559a..4971b08ae7 100644 --- a/_data/engine-cli/docker_context_export.yaml +++ b/_data/engine-cli/docker_context_export.yaml @@ -1,23 +1,39 @@ command: docker context export -short: Export a context to a tar or kubeconfig file +short: Export a context to a tar archive FILE or a tar stream on STDOUT. long: |- - Exports a context in a file that can then be used with `docker context import` - (or with `kubectl` if `--kubeconfig` is set). Default output filename is - `.dockercontext`, or `.kubeconfig` if `--kubeconfig` is set. - To export to `STDOUT`, you can run `docker context export my-context -`. + Exports a context to a file that can then be used with `docker context import`. + + The default output filename is `.dockercontext`. To export to `STDOUT`, + use `-` as filename, for example: + + ```console + $ docker context export my-context - + ``` usage: docker context export [OPTIONS] CONTEXT [FILE|-] pname: docker context plink: docker_context.yaml options: -- option: kubeconfig - value_type: bool - default_value: "false" - description: Export as a kubeconfig file - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false + - option: kubeconfig + value_type: bool + default_value: "false" + description: Export as a kubeconfig file + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: true + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context_import.yaml b/_data/engine-cli/docker_context_import.yaml index da71caefbe..357cf0566d 100644 --- a/_data/engine-cli/docker_context_import.yaml +++ b/_data/engine-cli/docker_context_import.yaml @@ -1,11 +1,22 @@ command: docker context import short: Import a context from a tar or zip file long: |- - Imports a context previously exported with `docker context export`. To import - from stdin, use a hyphen (`-`) as filename. + Imports a context previously exported with `docker context export`. To import + from stdin, use a hyphen (`-`) as filename. usage: docker context import CONTEXT FILE|- pname: docker context plink: docker_context.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context_inspect.yaml b/_data/engine-cli/docker_context_inspect.yaml index 6a4ef8809b..d78887930a 100644 --- a/_data/engine-cli/docker_context_inspect.yaml +++ b/_data/engine-cli/docker_context_inspect.yaml @@ -5,53 +5,58 @@ usage: docker context inspect [OPTIONS] [CONTEXT] [CONTEXT...] pname: docker context plink: docker_context.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Inspect a context by name + ### Inspect a context by name - ```console - $ docker context inspect "local+aks" + ```console + $ docker context inspect "local+aks" - [ - { - "Name": "local+aks", - "Metadata": { - "Description": "Local Docker Engine + Azure AKS endpoint", - "StackOrchestrator": "kubernetes" - }, - "Endpoints": { - "docker": { - "Host": "npipe:////./pipe/docker_engine", - "SkipTLSVerify": false + [ + { + "Name": "local+aks", + "Metadata": { + "Description": "Local Docker Engine", + "StackOrchestrator": "swarm" }, - "kubernetes": { - "Host": "https://simon-aks-***.hcp.uksouth.azmk8s.io:443", - "SkipTLSVerify": false, - "DefaultNamespace": "default" + "Endpoints": { + "docker": { + "Host": "npipe:////./pipe/docker_engine", + "SkipTLSVerify": false + } + }, + "TLSMaterial": {}, + "Storage": { + "MetadataPath": "C:\\Users\\simon\\.docker\\contexts\\meta\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee", + "TLSPath": "C:\\Users\\simon\\.docker\\contexts\\tls\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee" } - }, - "TLSMaterial": { - "kubernetes": [ - "ca.pem", - "cert.pem", - "key.pem" - ] - }, - "Storage": { - "MetadataPath": "C:\\Users\\simon\\.docker\\contexts\\meta\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee", - "TLSPath": "C:\\Users\\simon\\.docker\\contexts\\tls\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee" } - } - ] - ``` + ] + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context_ls.yaml b/_data/engine-cli/docker_context_ls.yaml index 54cce8be03..f5ee106c3b 100644 --- a/_data/engine-cli/docker_context_ls.yaml +++ b/_data/engine-cli/docker_context_ls.yaml @@ -1,41 +1,60 @@ command: docker context ls -aliases: list +aliases: docker context ls, docker context list short: List contexts long: List contexts usage: docker context ls [OPTIONS] pname: docker context plink: docker_context.yaml options: -- option: format - value_type: string - description: Pretty-print contexts using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only show context names - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only show context names + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Use `docker context ls` to print all contexts. The currently active context is - indicated with an `*`: + Use `docker context ls` to print all contexts. The currently active context is + indicated with an `*`: - ```console - $ docker context ls + ```console + $ docker context ls - NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR - default * Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm - production tcp:///prod.corp.example.com:2376 - staging tcp:///stage.corp.example.com:2376 - ``` + NAME DESCRIPTION DOCKER ENDPOINT ORCHESTRATOR + default * Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm + production tcp:///prod.corp.example.com:2376 + staging tcp:///stage.corp.example.com:2376 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context_rm.yaml b/_data/engine-cli/docker_context_rm.yaml index f690a2e5c9..09a0a0b28a 100644 --- a/_data/engine-cli/docker_context_rm.yaml +++ b/_data/engine-cli/docker_context_rm.yaml @@ -1,21 +1,33 @@ command: docker context rm -aliases: remove +aliases: docker context rm, docker context remove short: Remove one or more contexts long: Remove one or more contexts usage: docker context rm CONTEXT [CONTEXT...] pname: docker context plink: docker_context.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force the removal of a context in use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force the removal of a context in use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context_show.yaml b/_data/engine-cli/docker_context_show.yaml new file mode 100644 index 0000000000..40ee887b05 --- /dev/null +++ b/_data/engine-cli/docker_context_show.yaml @@ -0,0 +1,66 @@ +command: docker context show +short: Print the name of the current context +long: |- + Print the name of the current context, possibly set by `DOCKER_CONTEXT` environment + variable or `--context` global option. +usage: docker context show +pname: docker context +plink: docker_context.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +examples: |- + ### Print the current context + + The following example prints the currently used [`docker context`](context.md): + + ```console + $ docker context show' + default + ``` + + As an example, this output can be used to dynamically change your shell prompt + to indicate your active context. The example below illustrates how this output + could be used when using Bash as your shell. + + Declare a function to obtain the current context in your `~/.bashrc`, and set + this command as your `PROMPT_COMMAND` + + ```console + function docker_context_prompt() { + PS1="context: $(docker context show)> " + } + + PROMPT_COMMAND=docker_context_prompt + ``` + + After reloading the `~/.bashrc`, the prompt now shows the currently selected + `docker context`: + + ```console + $ source ~/.bashrc + context: default> docker context create --docker host=unix:///var/run/docker.sock my-context + my-context + Successfully created context "my-context" + context: default> docker context use my-context + my-context + Current context is now "my-context" + context: my-context> docker context use default + default + Current context is now "default" + context: default> + ``` +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_update.yaml b/_data/engine-cli/docker_context_update.yaml index 1fb7dcdfcd..336257cf15 100644 --- a/_data/engine-cli/docker_context_update.yaml +++ b/_data/engine-cli/docker_context_update.yaml @@ -1,56 +1,71 @@ command: docker context update short: Update a context long: |- - Updates an existing `context`. - See [context create](context_create.md). + Updates an existing `context`. + See [context create](context_create.md). usage: docker context update [OPTIONS] CONTEXT pname: docker context plink: docker_context.yaml options: -- option: default-stack-orchestrator - value_type: string - description: | - Default orchestrator for stack operations to use with this context (swarm|kubernetes|all) - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: description - value_type: string - description: Description of the context - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: docker - value_type: stringToString - default_value: '[]' - description: set the docker endpoint - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kubernetes - value_type: stringToString - default_value: '[]' - description: set the kubernetes endpoint - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false + - option: default-stack-orchestrator + value_type: string + description: | + Default orchestrator for stack operations to use with this context (swarm|kubernetes|all) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: description + value_type: string + description: Description of the context + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: docker + value_type: stringToString + default_value: '[]' + description: set the docker endpoint + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: kubernetes + value_type: stringToString + default_value: '[]' + description: set the kubernetes endpoint + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: true + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Update an existing context + ### Update an existing context - ```console - $ docker context update \ - --description "some description" \ - --docker "host=tcp://myserver:2376,ca=~/ca-file,cert=~/cert-file,key=~/key-file" \ - my-context - ``` + ```console + $ docker context update \ + --description "some description" \ + --docker "host=tcp://myserver:2376,ca=~/ca-file,cert=~/cert-file,key=~/key-file" \ + my-context + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_context_use.yaml b/_data/engine-cli/docker_context_use.yaml index 3a44c21b2f..f682c92606 100644 --- a/_data/engine-cli/docker_context_use.yaml +++ b/_data/engine-cli/docker_context_use.yaml @@ -1,12 +1,23 @@ command: docker context use short: Set the current docker context long: |- - Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment - variables and `--host`, `--context` global options are not set. - To disable usage of contexts, you can use the special `default` context. + Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment + variables and `--host`, `--context` global options are not set. + To disable usage of contexts, you can use the special `default` context. usage: docker context use CONTEXT pname: docker context plink: docker_context.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_cp.yaml b/_data/engine-cli/docker_cp.yaml index 12eb2d1201..df0e65b37d 100644 --- a/_data/engine-cli/docker_cp.yaml +++ b/_data/engine-cli/docker_cp.yaml @@ -1,133 +1,160 @@ command: docker cp +aliases: docker container cp, docker cp short: Copy files/folders between a container and the local filesystem long: |- - The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`. - You can copy from the container's file system to the local machine or the - reverse, from the local filesystem to the container. If `-` is specified for - either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from - `STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container. - The `SRC_PATH` or `DEST_PATH` can be a file or directory. + The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`. + You can copy from the container's file system to the local machine or the + reverse, from the local filesystem to the container. If `-` is specified for + either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from + `STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container. + The `SRC_PATH` or `DEST_PATH` can be a file or directory. - The `docker cp` command assumes container paths are relative to the container's - `/` (root) directory. This means supplying the initial forward slash is optional; - The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and - `compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can - be an absolute or relative value. The command interprets a local machine's - relative paths as relative to the current working directory where `docker cp` is - run. + The `docker cp` command assumes container paths are relative to the container's + `/` (root) directory. This means supplying the initial forward slash is optional; + The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and + `compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can + be an absolute or relative value. The command interprets a local machine's + relative paths as relative to the current working directory where `docker cp` is + run. - The `cp` command behaves like the Unix `cp -a` command in that directories are - copied recursively with permissions preserved if possible. Ownership is set to - the user and primary group at the destination. For example, files copied to a - container are created with `UID:GID` of the root user. Files copied to the local - machine are created with the `UID:GID` of the user which invoked the `docker cp` - command. However, if you specify the `-a` option, `docker cp` sets the ownership - to the user and primary group at the source. - If you specify the `-L` option, `docker cp` follows any symbolic link - in the `SRC_PATH`. `docker cp` does *not* create parent directories for - `DEST_PATH` if they do not exist. + The `cp` command behaves like the Unix `cp -a` command in that directories are + copied recursively with permissions preserved if possible. Ownership is set to + the user and primary group at the destination. For example, files copied to a + container are created with `UID:GID` of the root user. Files copied to the local + machine are created with the `UID:GID` of the user which invoked the `docker cp` + command. However, if you specify the `-a` option, `docker cp` sets the ownership + to the user and primary group at the source. + If you specify the `-L` option, `docker cp` follows any symbolic link + in the `SRC_PATH`. `docker cp` does *not* create parent directories for + `DEST_PATH` if they do not exist. - Assuming a path separator of `/`, a first argument of `SRC_PATH` and second - argument of `DEST_PATH`, the behavior is as follows: + Assuming a path separator of `/`, a first argument of `SRC_PATH` and second + argument of `DEST_PATH`, the behavior is as follows: - - `SRC_PATH` specifies a file - - `DEST_PATH` does not exist - - the file is saved to a file created at `DEST_PATH` - - `DEST_PATH` does not exist and ends with `/` - - Error condition: the destination directory must exist. - - `DEST_PATH` exists and is a file - - the destination is overwritten with the source file's contents - - `DEST_PATH` exists and is a directory - - the file is copied into this directory using the basename from - `SRC_PATH` - - `SRC_PATH` specifies a directory - - `DEST_PATH` does not exist - - `DEST_PATH` is created as a directory and the *contents* of the source - directory are copied into this directory - - `DEST_PATH` exists and is a file - - Error condition: cannot copy a directory to a file - - `DEST_PATH` exists and is a directory - - `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_) - - the source directory is copied into this directory - - `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_) - - the *content* of the source directory is copied into this - directory + - `SRC_PATH` specifies a file + - `DEST_PATH` does not exist + - the file is saved to a file created at `DEST_PATH` + - `DEST_PATH` does not exist and ends with `/` + - Error condition: the destination directory must exist. + - `DEST_PATH` exists and is a file + - the destination is overwritten with the source file's contents + - `DEST_PATH` exists and is a directory + - the file is copied into this directory using the basename from + `SRC_PATH` + - `SRC_PATH` specifies a directory + - `DEST_PATH` does not exist + - `DEST_PATH` is created as a directory and the *contents* of the source + directory are copied into this directory + - `DEST_PATH` exists and is a file + - Error condition: cannot copy a directory to a file + - `DEST_PATH` exists and is a directory + - `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_) + - the source directory is copied into this directory + - `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_) + - the *content* of the source directory is copied into this + directory - The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above - rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not - the target, is copied by default. To copy the link target and not the link, specify - the `-L` option. + The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above + rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not + the target, is copied by default. To copy the link target and not the link, specify + the `-L` option. - A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can - also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local - machine, for example `file:name.txt`. If you use a `:` in a local machine path, - you must be explicit with a relative or absolute path, for example: + A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can + also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local + machine, for example `file:name.txt`. If you use a `:` in a local machine path, + you must be explicit with a relative or absolute path, for example: - `/path/to/file:name.txt` or `./file:name.txt` -usage: "docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker cp [OPTIONS] - SRC_PATH|- CONTAINER:DEST_PATH" + `/path/to/file:name.txt` or `./file:name.txt` +usage: |- + docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|- + docker cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH pname: docker plink: docker.yaml options: -- option: archive - shorthand: a - value_type: bool - default_value: "false" - description: Archive mode (copy all uid/gid information) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: follow-link - shorthand: L - value_type: bool - default_value: "false" - description: Always follow symbol link in SRC_PATH - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: archive + shorthand: a + value_type: bool + default_value: "false" + description: Archive mode (copy all uid/gid information) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: follow-link + shorthand: L + value_type: bool + default_value: "false" + description: Always follow symbol link in SRC_PATH + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: | + Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Copy a local file into container + Copy a local file into container - ```console - $ docker cp ./some_file CONTAINER:/work - ``` + ```console + $ docker cp ./some_file CONTAINER:/work + ``` - Copy files from container to local path + Copy files from container to local path - ```console - $ docker cp CONTAINER:/var/logs/ /tmp/app_logs - ``` + ```console + $ docker cp CONTAINER:/var/logs/ /tmp/app_logs + ``` - Copy a file from container to stdout. Please note `cp` command produces a tar stream + Copy a file from container to stdout. Please note `cp` command produces a tar stream - ```console - $ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR" - ``` + ```console + $ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR" + ``` - ### Corner cases + ### Corner cases - It is not possible to copy certain system files such as resources under - `/proc`, `/sys`, `/dev`, [tmpfs](run.md#tmpfs), and mounts created by - the user in the container. However, you can still copy such files by manually - running `tar` in `docker exec`. Both of the following examples do the same thing - in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): + It is not possible to copy certain system files such as resources under + `/proc`, `/sys`, `/dev`, [tmpfs](run.md#tmpfs), and mounts created by + the user in the container. However, you can still copy such files by manually + running `tar` in `docker exec`. Both of the following examples do the same thing + in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): - ```console - $ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - - ``` + ```console + $ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - + ``` - ```console - $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH - - ``` + ```console + $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH - + ``` - Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive. - The command extracts the content of the tar to the `DEST_PATH` in container's - filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as - the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`. + Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive. + The command extracts the content of the tar to the `DEST_PATH` in container's + filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as + the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_create.yaml b/_data/engine-cli/docker_create.yaml index cc63bbef9e..ba2e23e39c 100644 --- a/_data/engine-cli/docker_create.yaml +++ b/_data/engine-cli/docker_create.yaml @@ -1,970 +1,1079 @@ command: docker create +aliases: docker container create, docker create short: Create a new container long: |- - The `docker container create` (or shorthand: `docker create`) command creates a - new container from the specified image, without starting it. + The `docker container create` (or shorthand: `docker create`) command creates a + new container from the specified image, without starting it. - When creating a container, the docker daemon creates a writeable container layer - over the specified image and prepares it for running the specified command. The - container ID is then printed to `STDOUT`. This is similar to `docker run -d` - except the container is never started. You can then use the `docker container start` - (or shorthand: `docker start`) command to start the container at any point. + When creating a container, the docker daemon creates a writeable container layer + over the specified image and prepares it for running the specified command. The + container ID is then printed to `STDOUT`. This is similar to `docker run -d` + except the container is never started. You can then use the `docker container start` + (or shorthand: `docker start`) command to start the container at any point. - This is useful when you want to set up a container configuration ahead of time - so that it is ready to start when you need it. The initial status of the - new container is `created`. + This is useful when you want to set up a container configuration ahead of time + so that it is ready to start when you need it. The initial status of the + new container is `created`. - The `docker create` command shares most of its options with the `docker run` - command (which performs a `docker create` before starting it). Refer to the - [`docker run` command](run.md) section and the [Docker run reference](../run.md) - for details on the available flags and options. + The `docker create` command shares most of its options with the `docker run` + command (which performs a `docker create` before starting it). Refer to the + [`docker run` command](run.md) section and the [Docker run reference](../run.md) + for details on the available flags and options. usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker plink: docker.yaml options: -- option: add-host - value_type: list - description: Add a custom host-to-IP mapping (host:ip) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: attach - shorthand: a - value_type: list - description: Attach to STDIN, STDOUT or STDERR - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: blkio-weight - value_type: uint16 - default_value: "0" - description: | - Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: blkio-weight-device - value_type: list - default_value: '[]' - description: Block IO weight (relative device weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-add - value_type: list - description: Add Linux capabilities - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-drop - value_type: list - description: Drop Linux capabilities - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroup-parent - value_type: string - description: Optional parent cgroup for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroupns - value_type: string - description: |- - Cgroup namespace to use (host|private) - 'host': Run the container in the Docker host's cgroup namespace - 'private': Run the container in its own private cgroup namespace - '': Use the cgroup namespace as configured by the - default-cgroupns-mode option on the daemon (default) - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cidfile - value_type: string - description: Write the container ID to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-count - value_type: int64 - default_value: "0" - description: CPU count (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: cpu-percent - value_type: int64 - default_value: "0" - description: CPU percent (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-period - value_type: int64 - default_value: "0" - description: Limit CPU real-time period in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-runtime - value_type: int64 - default_value: "0" - description: Limit CPU real-time runtime in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpus - value_type: decimal - description: Number of CPUs - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device - value_type: list - description: Add a host device to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-cgroup-rule - value_type: list - description: Add a rule to the cgroup allowed devices list - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-read-bps - value_type: list - default_value: '[]' - description: Limit read rate (bytes per second) from a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-read-iops - value_type: list - default_value: '[]' - description: Limit read rate (IO per second) from a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-write-bps - value_type: list - default_value: '[]' - description: Limit write rate (bytes per second) to a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-write-iops - value_type: list - default_value: '[]' - description: Limit write rate (IO per second) to a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns - value_type: list - description: Set custom DNS servers - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-opt - value_type: list - description: Set DNS options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-option - value_type: list - description: Set DNS options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-search - value_type: list - description: Set custom DNS search domains - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: domainname - value_type: string - description: Container NIS domain name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: entrypoint - value_type: string - description: Overwrite the default ENTRYPOINT of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env - shorthand: e - value_type: list - description: Set environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-file - value_type: list - description: Read in a file of environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: expose - value_type: list - description: Expose a port or a range of ports - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: gpus - value_type: gpu-request - description: GPU devices to add to the container ('all' to pass all GPUs) - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: group-add - value_type: list - description: Add additional groups to join - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-cmd - value_type: string - description: Command to run to check health - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-interval - value_type: duration - default_value: 0s - description: Time between running the check (ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-retries - value_type: int - default_value: "0" - description: Consecutive failures needed to report unhealthy - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-start-period - value_type: duration - default_value: 0s - description: | - Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-timeout - value_type: duration - default_value: 0s - description: | - Maximum time to allow one check to run (ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: help - value_type: bool - default_value: "false" - description: Print usage - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: hostname - shorthand: h - value_type: string - description: Container host name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: init - value_type: bool - default_value: "false" - description: | - Run an init inside the container that forwards signals and reaps processes - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Keep STDIN open even if not attached - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: io-maxbandwidth - value_type: bytes - default_value: "0" - description: | - Maximum IO bandwidth limit for the system drive (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: io-maxiops - value_type: uint64 - default_value: "0" - description: Maximum IOps limit for the system drive (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: ip - value_type: string - description: IPv4 address (e.g., 172.30.100.104) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ip6 - value_type: string - description: IPv6 address (e.g., 2001:db8::33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ipc - value_type: string - description: IPC mode to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Container isolation technology - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kernel-memory - value_type: bytes - default_value: "0" - description: Kernel memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - shorthand: l - value_type: list - description: Set meta data on a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label-file - value_type: list - description: Read in a line delimited file of labels - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link - value_type: list - description: Add link to another container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link-local-ip - value_type: list - description: Container IPv4/IPv6 link-local addresses - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-driver - value_type: string - description: Logging driver for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-opt - value_type: list - description: Log driver options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mac-address - value_type: string - description: Container MAC address (e.g., 92:d0:c6:0a:29:33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-reservation - value_type: bytes - default_value: "0" - description: Memory soft limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swappiness - value_type: int64 - default_value: "-1" - description: Tune container memory swappiness (0 to 100) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mount - value_type: mount - description: Attach a filesystem mount to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: name - value_type: string - description: Assign a name to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: net - value_type: network - description: Connect a container to a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: net-alias - value_type: list - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: network - description: Connect a container to a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network-alias - value_type: list - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-healthcheck - value_type: bool - default_value: "false" - description: Disable any container-specified HEALTHCHECK - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: oom-kill-disable - value_type: bool - default_value: "false" - description: Disable OOM Killer - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: oom-score-adj - value_type: int - default_value: "0" - description: Tune host's OOM preferences (-1000 to 1000) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pid - value_type: string - description: PID namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pids-limit - value_type: int64 - default_value: "0" - description: Tune container pids limit (set -1 for unlimited) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: privileged - value_type: bool - default_value: "false" - description: Give extended privileges to this container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish - shorthand: p - value_type: list - description: Publish a container's port(s) to the host - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish-all - shorthand: P - value_type: bool - default_value: "false" - description: Publish all exposed ports to random ports - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: string - default_value: missing - description: Pull image before creating ("always"|"missing"|"never") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: read-only - value_type: bool - default_value: "false" - description: Mount the container's root filesystem as read only - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart - value_type: string - default_value: "no" - description: Restart policy to apply when a container exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rm - value_type: bool - default_value: "false" - description: Automatically remove the container when it exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: runtime - value_type: string - description: Runtime to use for this container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: security-opt - value_type: list - description: Security Options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: shm-size - value_type: bytes - default_value: "0" - description: Size of /dev/shm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-signal - value_type: string - default_value: SIGTERM - description: Signal to stop a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-timeout - value_type: int - default_value: "0" - description: Timeout (in seconds) to stop a container - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: storage-opt - value_type: list - description: Storage driver options for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sysctl - value_type: map - default_value: map[] - description: Sysctl options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tmpfs - value_type: list - description: Mount a tmpfs directory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: ulimit - default_value: '[]' - description: Ulimit options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: userns - value_type: string - description: User namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: uts - value_type: string - description: UTS namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volume - shorthand: v - value_type: list - description: Bind mount a volume - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volume-driver - value_type: string - description: Optional volume driver for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volumes-from - value_type: list - description: Mount volumes from the specified container(s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: add-host + value_type: list + description: Add a custom host-to-IP mapping (host:ip) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: attach + shorthand: a + value_type: list + description: Attach to STDIN, STDOUT or STDERR + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: blkio-weight + value_type: uint16 + default_value: "0" + description: | + Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: blkio-weight-device + value_type: list + default_value: '[]' + description: Block IO weight (relative device weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-add + value_type: list + description: Add Linux capabilities + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-drop + value_type: list + description: Drop Linux capabilities + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroupns + value_type: string + description: |- + Cgroup namespace to use (host|private) + 'host': Run the container in the Docker host's cgroup namespace + 'private': Run the container in its own private cgroup namespace + '': Use the cgroup namespace as configured by the + default-cgroupns-mode option on the daemon (default) + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cidfile + value_type: string + description: Write the container ID to the file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-count + value_type: int64 + default_value: "0" + description: CPU count (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: cpu-percent + value_type: int64 + default_value: "0" + description: CPU percent (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-period + value_type: int64 + default_value: "0" + description: Limit CPU real-time period in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-runtime + value_type: int64 + default_value: "0" + description: Limit CPU real-time runtime in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpus + value_type: decimal + description: Number of CPUs + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device + value_type: list + description: Add a host device to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-cgroup-rule + value_type: list + description: Add a rule to the cgroup allowed devices list + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-read-bps + value_type: list + default_value: '[]' + description: Limit read rate (bytes per second) from a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-read-iops + value_type: list + default_value: '[]' + description: Limit read rate (IO per second) from a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-write-bps + value_type: list + default_value: '[]' + description: Limit write rate (bytes per second) to a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-write-iops + value_type: list + default_value: '[]' + description: Limit write rate (IO per second) to a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns + value_type: list + description: Set custom DNS servers + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-opt + value_type: list + description: Set DNS options + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-option + value_type: list + description: Set DNS options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-search + value_type: list + description: Set custom DNS search domains + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: domainname + value_type: string + description: Container NIS domain name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: entrypoint + value_type: string + description: Overwrite the default ENTRYPOINT of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env + shorthand: e + value_type: list + description: Set environment variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: expose + value_type: list + description: Expose a port or a range of ports + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: gpus + value_type: gpu-request + description: GPU devices to add to the container ('all' to pass all GPUs) + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: group-add + value_type: list + description: Add additional groups to join + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-cmd + value_type: string + description: Command to run to check health + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-interval + value_type: duration + default_value: 0s + description: Time between running the check (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-retries + value_type: int + default_value: "0" + description: Consecutive failures needed to report unhealthy + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-start-period + value_type: duration + default_value: 0s + description: | + Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-timeout + value_type: duration + default_value: 0s + description: Maximum time to allow one check to run (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: hostname + shorthand: h + value_type: string + description: Container host name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: init + value_type: bool + default_value: "false" + description: | + Run an init inside the container that forwards signals and reaps processes + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: interactive + shorthand: i + value_type: bool + default_value: "false" + description: Keep STDIN open even if not attached + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: io-maxbandwidth + value_type: bytes + default_value: "0" + description: Maximum IO bandwidth limit for the system drive (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: io-maxiops + value_type: uint64 + default_value: "0" + description: Maximum IOps limit for the system drive (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: ip + value_type: string + description: IPv4 address (e.g., 172.30.100.104) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ip6 + value_type: string + description: IPv6 address (e.g., 2001:db8::33) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ipc + value_type: string + description: IPC mode to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Container isolation technology + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: kernel-memory + value_type: bytes + default_value: "0" + description: Kernel memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + shorthand: l + value_type: list + description: Set meta data on a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label-file + value_type: list + description: Read in a line delimited file of labels + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link + value_type: list + description: Add link to another container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link-local-ip + value_type: list + description: Container IPv4/IPv6 link-local addresses + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-driver + value_type: string + description: Logging driver for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-opt + value_type: list + description: Log driver options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mac-address + value_type: string + description: Container MAC address (e.g., 92:d0:c6:0a:29:33) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-reservation + value_type: bytes + default_value: "0" + description: Memory soft limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: | + Swap limit equal to memory plus swap: '-1' to enable unlimited swap + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swappiness + value_type: int64 + default_value: "-1" + description: Tune container memory swappiness (0 to 100) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mount + value_type: mount + description: Attach a filesystem mount to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: name + value_type: string + description: Assign a name to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: net + value_type: network + description: Connect a container to a network + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: net-alias + value_type: list + description: Add network-scoped alias for the container + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: network + description: Connect a container to a network + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network-alias + value_type: list + description: Add network-scoped alias for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-healthcheck + value_type: bool + default_value: "false" + description: Disable any container-specified HEALTHCHECK + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: oom-kill-disable + value_type: bool + default_value: "false" + description: Disable OOM Killer + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: oom-score-adj + value_type: int + default_value: "0" + description: Tune host's OOM preferences (-1000 to 1000) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pid + value_type: string + description: PID namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pids-limit + value_type: int64 + default_value: "0" + description: Tune container pids limit (set -1 for unlimited) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: privileged + value_type: bool + default_value: "false" + description: Give extended privileges to this container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish + shorthand: p + value_type: list + description: Publish a container's port(s) to the host + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish-all + shorthand: P + value_type: bool + default_value: "false" + description: Publish all exposed ports to random ports + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pull + value_type: string + default_value: missing + description: Pull image before creating (`always`, `|missing`, `never`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the pull output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: read-only + value_type: bool + default_value: "false" + description: Mount the container's root filesystem as read only + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart + value_type: string + default_value: "no" + description: Restart policy to apply when a container exits + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rm + value_type: bool + default_value: "false" + description: Automatically remove the container when it exits + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: runtime + value_type: string + description: Runtime to use for this container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: security-opt + value_type: list + description: Security Options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: shm-size + value_type: bytes + default_value: "0" + description: Size of /dev/shm + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-signal + value_type: string + description: Signal to stop the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-timeout + value_type: int + default_value: "0" + description: Timeout (in seconds) to stop a container + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: storage-opt + value_type: list + description: Storage driver options for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sysctl + value_type: map + default_value: map[] + description: Sysctl options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tmpfs + value_type: list + description: Mount a tmpfs directory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tty + shorthand: t + value_type: bool + default_value: "false" + description: Allocate a pseudo-TTY + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: user + shorthand: u + value_type: string + description: 'Username or UID (format: [:])' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: userns + value_type: string + description: User namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: uts + value_type: string + description: UTS namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume + shorthand: v + value_type: list + description: Bind mount a volume + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume-driver + value_type: string + description: Optional volume driver for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volumes-from + value_type: list + description: Mount volumes from the specified container(s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workdir + shorthand: w + value_type: string + description: Working directory inside the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Create and start a container + ### Create and start a container - The following example creates an interactive container with a pseudo-TTY attached, - then starts the container and attaches to it: + The following example creates an interactive container with a pseudo-TTY attached, + then starts the container and attaches to it: - ```console - $ docker container create -i -t --name mycontainer alpine - 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 + ```console + $ docker container create -i -t --name mycontainer alpine + 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 - $ docker container start --attach -i mycontainer - / # echo hello world - hello world - ``` + $ docker container start --attach -i mycontainer + / # echo hello world + hello world + ``` - The above is the equivalent of a `docker run`: + The above is the equivalent of a `docker run`: - ```console - $ docker run -it --name mycontainer2 alpine - / # echo hello world - hello world - ``` + ```console + $ docker run -it --name mycontainer2 alpine + / # echo hello world + hello world + ``` - ### Initialize volumes + ### Initialize volumes - Container volumes are initialized during the `docker create` phase - (i.e., `docker run` too). For example, this allows you to `create` the `data` - volume container, and then use it from another container: + Container volumes are initialized during the `docker create` phase + (i.e., `docker run` too). For example, this allows you to `create` the `data` + volume container, and then use it from another container: - ```console - $ docker create -v /data --name data ubuntu + ```console + $ docker create -v /data --name data ubuntu - 240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57 + 240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57 - $ docker run --rm --volumes-from data ubuntu ls -la /data + $ docker run --rm --volumes-from data ubuntu ls -la /data - total 8 - drwxr-xr-x 2 root root 4096 Dec 5 04:10 . - drwxr-xr-x 48 root root 4096 Dec 5 04:11 .. - ``` + total 8 + drwxr-xr-x 2 root root 4096 Dec 5 04:10 . + drwxr-xr-x 48 root root 4096 Dec 5 04:11 .. + ``` - Similarly, `create` a host directory bind mounted volume container, which can - then be used from the subsequent container: + Similarly, `create` a host directory bind mounted volume container, which can + then be used from the subsequent container: - ```console - $ docker create -v /home/docker:/docker --name docker ubuntu + ```console + $ docker create -v /home/docker:/docker --name docker ubuntu - 9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03 + 9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03 - $ docker run --rm --volumes-from docker ubuntu ls -la /docker + $ docker run --rm --volumes-from docker ubuntu ls -la /docker - total 20 - drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 . - drwxr-xr-x 48 root root 4096 Dec 5 04:13 .. - -rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history - -rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc - -rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig - drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local - -rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile - drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh - drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker - ``` + total 20 + drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 . + drwxr-xr-x 48 root root 4096 Dec 5 04:13 .. + -rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history + -rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc + -rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig + drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local + -rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile + drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh + drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_diff.yaml b/_data/engine-cli/docker_diff.yaml index be40bf7cb3..1ad5f1c471 100644 --- a/_data/engine-cli/docker_diff.yaml +++ b/_data/engine-cli/docker_diff.yaml @@ -1,46 +1,58 @@ command: docker diff +aliases: docker container diff, docker diff short: Inspect changes to files or directories on a container's filesystem long: |- - List the changed files and directories in a container᾿s filesystem since the - container was created. Three different types of change are tracked: + List the changed files and directories in a container᾿s filesystem since the + container was created. Three different types of change are tracked: - | Symbol | Description | - |--------|---------------------------------| - | `A` | A file or directory was added | - | `D` | A file or directory was deleted | - | `C` | A file or directory was changed | + | Symbol | Description | + |--------|---------------------------------| + | `A` | A file or directory was added | + | `D` | A file or directory was deleted | + | `C` | A file or directory was changed | - You can use the full or shortened container ID or the container name set using - `docker run --name` option. + You can use the full or shortened container ID or the container name set using + `docker run --name` option. usage: docker diff CONTAINER pname: docker plink: docker.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Inspect the changes to an `nginx` container: + Inspect the changes to an `nginx` container: - ```console - $ docker diff 1fdfd1f54c1b + ```console + $ docker diff 1fdfd1f54c1b - C /dev - C /dev/console - C /dev/core - C /dev/stdout - C /dev/fd - C /dev/ptmx - C /dev/stderr - C /dev/stdin - C /run - A /run/nginx.pid - C /var/lib/nginx/tmp - A /var/lib/nginx/tmp/client_body - A /var/lib/nginx/tmp/fastcgi - A /var/lib/nginx/tmp/proxy - A /var/lib/nginx/tmp/scgi - A /var/lib/nginx/tmp/uwsgi - C /var/log/nginx - A /var/log/nginx/access.log - A /var/log/nginx/error.log - ``` + C /dev + C /dev/console + C /dev/core + C /dev/stdout + C /dev/fd + C /dev/ptmx + C /dev/stderr + C /dev/stdin + C /run + A /run/nginx.pid + C /var/lib/nginx/tmp + A /var/lib/nginx/tmp/client_body + A /var/lib/nginx/tmp/fastcgi + A /var/lib/nginx/tmp/proxy + A /var/lib/nginx/tmp/scgi + A /var/lib/nginx/tmp/uwsgi + C /var/log/nginx + A /var/log/nginx/access.log + A /var/log/nginx/error.log + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_events.yaml b/_data/engine-cli/docker_events.yaml index 45b9557f82..0758f841c1 100644 --- a/_data/engine-cli/docker_events.yaml +++ b/_data/engine-cli/docker_events.yaml @@ -1,430 +1,446 @@ command: docker events +aliases: docker system events, docker events short: Get real time events from the server long: |- - Use `docker events` to get real-time events from the server. These events differ - per Docker object type. Different event types have different scopes. Local - scoped events are only seen on the node they take place on, and swarm scoped - events are seen on all managers. + Use `docker events` to get real-time events from the server. These events differ + per Docker object type. Different event types have different scopes. Local + scoped events are only seen on the node they take place on, and swarm scoped + events are seen on all managers. - Only the last 1000 log events are returned. You can use filters to further limit - the number of events returned. + Only the last 1000 log events are returned. You can use filters to further limit + the number of events returned. - ### Object types + ### Object types - #### Containers + #### Containers - Docker containers report the following events: + Docker containers report the following events: - - `attach` - - `commit` - - `copy` - - `create` - - `destroy` - - `detach` - - `die` - - `exec_create` - - `exec_detach` - - `exec_die` - - `exec_start` - - `export` - - `health_status` - - `kill` - - `oom` - - `pause` - - `rename` - - `resize` - - `restart` - - `start` - - `stop` - - `top` - - `unpause` - - `update` + - `attach` + - `commit` + - `copy` + - `create` + - `destroy` + - `detach` + - `die` + - `exec_create` + - `exec_detach` + - `exec_die` + - `exec_start` + - `export` + - `health_status` + - `kill` + - `oom` + - `pause` + - `rename` + - `resize` + - `restart` + - `start` + - `stop` + - `top` + - `unpause` + - `update` - #### Images + #### Images - Docker images report the following events: + Docker images report the following events: - - `delete` - - `import` - - `load` - - `pull` - - `push` - - `save` - - `tag` - - `untag` + - `delete` + - `import` + - `load` + - `pull` + - `push` + - `save` + - `tag` + - `untag` - #### Plugins + #### Plugins - Docker plugins report the following events: + Docker plugins report the following events: - - `enable` - - `disable` - - `install` - - `remove` + - `enable` + - `disable` + - `install` + - `remove` - #### Volumes + #### Volumes - Docker volumes report the following events: + Docker volumes report the following events: - - `create` - - `destroy` - - `mount` - - `unmount` + - `create` + - `destroy` + - `mount` + - `unmount` - #### Networks + #### Networks - Docker networks report the following events: + Docker networks report the following events: - - `create` - - `connect` - - `destroy` - - `disconnect` - - `remove` + - `create` + - `connect` + - `destroy` + - `disconnect` + - `remove` - #### Daemons + #### Daemons - Docker daemons report the following events: + Docker daemons report the following events: - - `reload` + - `reload` - #### Services + #### Services - Docker services report the following events: + Docker services report the following events: - - `create` - - `remove` - - `update` + - `create` + - `remove` + - `update` - #### Nodes + #### Nodes - Docker nodes report the following events: + Docker nodes report the following events: - - `create` - - `remove` - - `update` + - `create` + - `remove` + - `update` - #### Secrets + #### Secrets - Docker secrets report the following events: + Docker secrets report the following events: - - `create` - - `remove` - - `update` + - `create` + - `remove` + - `update` - #### Configs + #### Configs - Docker configs report the following events: + Docker configs report the following events: - - `create` - - `remove` - - `update` + - `create` + - `remove` + - `update` - ### Limiting, filtering, and formatting the output + ### Limiting, filtering, and formatting the output - #### Limit events by time (--since, --until) + #### Limit events by time (--since, --until) {#since} - The `--since` and `--until` parameters can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed - relative to the client machine’s time. If you do not provide the `--since` option, - the command returns only new and/or live events. Supported formats for date - formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local - timezone on the client will be used if you do not provide either a `Z` or a - `+-00:00` timezone offset at the end of the timestamp. When providing Unix - timestamps enter seconds[.nanoseconds], where seconds is the number of seconds - that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap - seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a - fraction of a second no more than nine digits long. + The `--since` and `--until` parameters can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the client machine’s time. If you do not provide the `--since` option, + the command returns only new and/or live events. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the client will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. - Only the last 1000 log events are returned. You can use filters to further limit - the number of events returned. + Only the last 1000 log events are returned. You can use filters to further limit + the number of events returned. - #### Filtering (--filter) + #### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--filter`) format is of "key=value". If you would - like to use multiple filters, pass multiple flags (e.g., - `--filter "foo=bar" --filter "bif=baz"`) + The filtering flag (`-f` or `--filter`) format is of "key=value". If you would + like to use multiple filters, pass multiple flags (e.g., + `--filter "foo=bar" --filter "bif=baz"`) - Using the same filter multiple times will be handled as a *OR*; for example - `--filter container=588a23dac085 --filter container=a8f7720b8c22` will display - events for container 588a23dac085 *OR* container a8f7720b8c22 + Using the same filter multiple times will be handled as a *OR*; for example + `--filter container=588a23dac085 --filter container=a8f7720b8c22` will display + events for container 588a23dac085 *OR* container a8f7720b8c22 - Using multiple filters will be handled as a *AND*; for example - `--filter container=588a23dac085 --filter event=start` will display events for - container container 588a23dac085 *AND* the event type is *start* + Using multiple filters will be handled as a *AND*; for example + `--filter container=588a23dac085 --filter event=start` will display events for + container container 588a23dac085 *AND* the event type is *start* - The currently supported filters are: + The currently supported filters are: - * config (`config=`) - * container (`container=`) - * daemon (`daemon=`) - * event (`event=`) - * image (`image=`) - * label (`label=` or `label==`) - * network (`network=`) - * node (`node=`) - * plugin (`plugin=`) - * scope (`scope=`) - * secret (`secret=`) - * service (`service=`) - * type (`type=`) - * volume (`volume=`) + * config (`config=`) + * container (`container=`) + * daemon (`daemon=`) + * event (`event=`) + * image (`image=`) + * label (`label=` or `label==`) + * network (`network=`) + * node (`node=`) + * plugin (`plugin=`) + * scope (`scope=`) + * secret (`secret=`) + * service (`service=`) + * type (`type=`) + * volume (`volume=`) - #### Format the output (--format) + #### Format the output (--format) {#format} - If a format (`--format`) is specified, the given template will be executed - instead of the default - format. Go's [text/template](https://golang.org/pkg/text/template/) package - describes all the details of the format. + If a format (`--format`) is specified, the given template will be executed + instead of the default + format. Go's [text/template](https://golang.org/pkg/text/template/) package + describes all the details of the format. - If a format is set to `{{json .}}`, the events are streamed as valid JSON - Lines. For information about JSON Lines, please refer to https://jsonlines.org/. + If a format is set to `{{json .}}`, the events are streamed as valid JSON + Lines. For information about JSON Lines, please refer to https://jsonlines.org/. usage: docker events [OPTIONS] pname: docker plink: docker.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: since - value_type: string - description: Show all events created since timestamp - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: until - value_type: string - description: Stream events until this timestamp - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: Format the output using the given Go template + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: since + value_type: string + description: Show all events created since timestamp + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: until + value_type: string + description: Stream events until this timestamp + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Basic example + ### Basic example - You'll need two shells for this example. + You'll need two shells for this example. - **Shell 1: Listening for events:** + **Shell 1: Listening for events:** - ```console - $ docker events - ``` + ```console + $ docker events + ``` - **Shell 2: Start and Stop containers:** + **Shell 2: Start and Stop containers:** - ```console - $ docker create --name test alpine:latest top - $ docker start test - $ docker stop test - ``` + ```console + $ docker create --name test alpine:latest top + $ docker start test + $ docker stop test + ``` - **Shell 1: (Again .. now showing events):** + **Shell 1: (Again .. now showing events):** - ```console - 2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - ``` + ```console + 2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + ``` - To exit the `docker events` command, use `CTRL+C`. + To exit the `docker events` command, use `CTRL+C`. - ### Filter events by time + ### Filter events by time - You can filter the output by an absolute timestamp or relative time on the host - machine, using the following different time syntaxes: + You can filter the output by an absolute timestamp or relative time on the host + machine, using the following different time syntaxes: - ```console - $ docker events --since 1483283804 - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + ```console + $ docker events --since 1483283804 + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker events --since '2017-01-05' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + $ docker events --since '2017-01-05' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker events --since '2013-09-03T15:49:29' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + $ docker events --since '2013-09-03T15:49:29' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker events --since '10m' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + $ docker events --since '10m' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36:05' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - ``` + $ docker events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36:05' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + ``` - ### Filter events by criteria + ### Filter events by criteria - The following commands show several different ways to filter the `docker event` - output. + The following commands show several different ways to filter the `docker event` + output. - ```console - $ docker events --filter 'event=stop' + ```console + $ docker events --filter 'event=stop' - 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain) + 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain) - $ docker events --filter 'image=alpine' + $ docker events --filter 'image=alpine' - 2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15) - 2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9) - 2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner) - 2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15) + 2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9) + 2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner) + 2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner) - $ docker events --filter 'container=test' + $ docker events --filter 'container=test' - 2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8' + $ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8' - 2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9) - 2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test) - 2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9) + 2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test) + 2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test) - $ docker events --filter 'container=test' --filter 'event=stop' + $ docker events --filter 'container=test' --filter 'event=stop' - 2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) + 2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) - $ docker events --filter 'type=volume' + $ docker events --filter 'type=volume' - 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) - 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate) - 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local) - 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) + 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) + 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate) + 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local) + 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) - $ docker events --filter 'type=network' + $ docker events --filter 'type=network' - 2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge) - 2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge) + 2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge) + 2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge) - $ docker events --filter 'container=container_1' --filter 'container=container_2' + $ docker events --filter 'container=container_1' --filter 'container=container_2' - 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04) - 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04) - 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) - 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) + 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04) + 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04) + 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) + 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) - $ docker events --filter 'type=volume' + $ docker events --filter 'type=volume' - 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) - 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate) - 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local) - 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) + 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) + 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate) + 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local) + 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) - $ docker events --filter 'type=network' + $ docker events --filter 'type=network' - 2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge) - 2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge) + 2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge) + 2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge) - $ docker events --filter 'type=plugin' + $ docker events --filter 'type=plugin' - 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) - 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) + 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) + 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) - $ docker events -f type=service + $ docker events -f type=service - 2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani) - 2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani) + 2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani) + 2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani) - $ docker events -f type=node + $ docker events -f type=node - 2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown) + 2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown) - $ docker events -f type=secret + $ docker events -f type=secret - 2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret) - 2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret) + 2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret) + 2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret) - $ docker events -f type=config - 2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc) - 2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc) + $ docker events -f type=config + 2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc) + 2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc) - $ docker events --filter 'scope=swarm' + $ docker events --filter 'scope=swarm' - 2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson) - 2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret) - ``` + 2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson) + 2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret) + ``` - ### Format the output + ### Format the output - ```console - $ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' + ```console + $ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' - Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - ``` + Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + ``` - #### Format as JSON + #### Format as JSON - ```console - $ docker events --format '{{json .}}' + ```console + $ docker events --format '{{json .}}' - {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. - {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. - {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. - {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. - {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. - ``` + {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. + {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. + {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_exec.yaml b/_data/engine-cli/docker_exec.yaml index 7e20a0cf68..f510a65dfd 100644 --- a/_data/engine-cli/docker_exec.yaml +++ b/_data/engine-cli/docker_exec.yaml @@ -1,142 +1,226 @@ command: docker exec -short: Run a command in a running container +aliases: docker container exec, docker exec +short: Execute a command in a running container long: |- - The `docker exec` command runs a new command in a running container. + The `docker exec` command runs a new command in a running container. - The command started using `docker exec` only runs while the container's primary - process (`PID 1`) is running, and it is not restarted if the container is - restarted. + The command started using `docker exec` only runs while the container's primary + process (`PID 1`) is running, and it is not restarted if the container is + restarted. - COMMAND runs in the default directory of the container. If the underlying image - has a custom directory specified with the WORKDIR directive in its Dockerfile, - this directory is used instead. + COMMAND runs in the default directory of the container. If the underlying image + has a custom directory specified with the WORKDIR directive in its Dockerfile, + this directory is used instead. - COMMAND must be an executable. A chained or a quoted command does not work. - For example, `docker exec -it my_container sh -c "echo a && echo b"` works, - work, but `docker exec -it my_container "echo a && echo b"` does not. + COMMAND must be an executable. A chained or a quoted command does not work. + For example, `docker exec -it my_container sh -c "echo a && echo b"` does + work, but `docker exec -it my_container "echo a && echo b"` does not. usage: docker exec [OPTIONS] CONTAINER COMMAND [ARG...] pname: docker plink: docker.yaml options: -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: 'Detached mode: run command in the background' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env - shorthand: e - value_type: list - description: Set environment variables - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-file - value_type: list - description: Read in a file of environment variables - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Keep STDIN open even if not attached - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: privileged - value_type: bool - default_value: "false" - description: Give extended privileges to the command - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - deprecated: false - min_api_version: "1.35" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: "### Run `docker exec` on a running container\n\nFirst, start a container.\n\n```console\n$ - docker run --name mycontainer -d -i -t alpine /bin/sh\n```\n\nThis creates and starts - a container named `mycontainer` from an `alpine` image\nwith an `sh` shell as its - main process. The `-d` option (shorthand for `--detach`)\nsets the container to - run in the background, in detached mode, with a pseudo-TTY\nattached (`-t`). The - `-i` option is set to keep `STDIN` attached (`-i`), which\nprevents the `sh` process - from exiting immediately.\n\nNext, execute a command on the container.\n\n```console\n$ - docker exec -d mycontainer touch /tmp/execWorks\n```\n\nThis creates a new file - `/tmp/execWorks` inside the running container\n`mycontainer`, in the background.\n\nNext, - execute an interactive `sh` shell on the container.\n\n```console\n$ docker exec - -it mycontainer sh\n```\n\nThis starts a new shell session in the container `mycontainer`.\n\n### - Set environment variables for the exec process (--env, -e)\n\nNext, - set environment variables in the current bash session.\n\nBy default, the `docker - exec` command, inherits the environment variables that\nare set at the time the - container is created. Use the `--env` (or the `-e` shorthand)\nto override global - environment variables, or to set additional environment variables\nfor the process - started by `docker exec`.\n\nThe example below creates a new shell session in the - container `mycontainer` with\nenvironment variables `$VAR_A` and `$VAR_B` set to - \"1\" and \"2\" respectively.\nThese environment variables are only valid for the - `sh` process started by that\n`docker exec` command, and are not available to other - processes running inside\nthe container.\n\n```console\n$ docker exec -e VAR_A=1 - -e VAR_B=2 mycontainer env\nPATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\nHOSTNAME=f64a4851eb71\nVAR_A=1\nVAR_B=2\nHOME=/root\n```\n\n### - Set the working directory for the exec process (--workdir, - -w)\n\nBy default `docker exec` command runs in the same working directory set when - \nthe container was created.\n\n```console\n$ docker exec -it mycontainer pwd\n/\n```\n\nYou - can specify an alternative working directory for the command to execute \nusing - the `--workdir` option (or the `-w` shorthand):\n\n```console\n$ docker exec -it - -w /root mycontainer pwd\n/root\n```\n\n\n### Try to run `docker exec` on a paused - container\n\nIf the container is paused, then the `docker exec` command fails with - an error:\n\n```console\n$ docker pause mycontainer\nmycontainer\n\n$ docker ps\n\nCONTAINER - ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n482efdf39fac - \ alpine \"/bin/sh\" 17 seconds ago Up 16 seconds (Paused) mycontainer\n\n$ - docker exec mycontainer sh\n\nError response from daemon: Container mycontainer - is paused, unpause the container before exec\n\n$ echo $?\n1\n```" + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: 'Detached mode: run command in the background' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach-keys + value_type: string + description: Override the key sequence for detaching a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env + shorthand: e + value_type: list + description: Set environment variables + details_url: '#env' + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: interactive + shorthand: i + value_type: bool + default_value: "false" + description: Keep STDIN open even if not attached + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: privileged + value_type: bool + default_value: "false" + description: Give extended privileges to the command + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tty + shorthand: t + value_type: bool + default_value: "false" + description: Allocate a pseudo-TTY + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: user + shorthand: u + value_type: string + description: 'Username or UID (format: `[:]`)' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workdir + shorthand: w + value_type: string + description: Working directory inside the container + details_url: '#workdir' + deprecated: false + hidden: false + min_api_version: "1.35" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +examples: |- + ### Run `docker exec` on a running container + + First, start a container. + + ```console + $ docker run --name mycontainer -d -i -t alpine /bin/sh + ``` + + This creates and starts a container named `mycontainer` from an `alpine` image + with an `sh` shell as its main process. The `-d` option (shorthand for `--detach`) + sets the container to run in the background, in detached mode, with a pseudo-TTY + attached (`-t`). The `-i` option is set to keep `STDIN` attached (`-i`), which + prevents the `sh` process from exiting immediately. + + Next, execute a command on the container. + + ```console + $ docker exec -d mycontainer touch /tmp/execWorks + ``` + + This creates a new file `/tmp/execWorks` inside the running container + `mycontainer`, in the background. + + Next, execute an interactive `sh` shell on the container. + + ```console + $ docker exec -it mycontainer sh + ``` + + This starts a new shell session in the container `mycontainer`. + + ### Set environment variables for the exec process (--env, -e) {#env} + + Next, set environment variables in the current bash session. + + By default, the `docker exec` command, inherits the environment variables that + are set at the time the container is created. Use the `--env` (or the `-e` shorthand) + to override global environment variables, or to set additional environment variables + for the process started by `docker exec`. + + The example below creates a new shell session in the container `mycontainer` with + environment variables `$VAR_A` and `$VAR_B` set to "1" and "2" respectively. + These environment variables are only valid for the `sh` process started by that + `docker exec` command, and are not available to other processes running inside + the container. + + ```console + $ docker exec -e VAR_A=1 -e VAR_B=2 mycontainer env + PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + HOSTNAME=f64a4851eb71 + VAR_A=1 + VAR_B=2 + HOME=/root + ``` + + ### Set the working directory for the exec process (--workdir, -w) {#workdir} + + By default `docker exec` command runs in the same working directory set when + the container was created. + + ```console + $ docker exec -it mycontainer pwd + / + ``` + + You can specify an alternative working directory for the command to execute + using the `--workdir` option (or the `-w` shorthand): + + ```console + $ docker exec -it -w /root mycontainer pwd + /root + ``` + + + ### Try to run `docker exec` on a paused container + + If the container is paused, then the `docker exec` command fails with an error: + + ```console + $ docker pause mycontainer + mycontainer + + $ docker ps + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 482efdf39fac alpine "/bin/sh" 17 seconds ago Up 16 seconds (Paused) mycontainer + + $ docker exec mycontainer sh + + Error response from daemon: Container mycontainer is paused, unpause the container before exec + + $ echo $? + 1 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_export.yaml b/_data/engine-cli/docker_export.yaml index a5fd064131..1ba1846423 100644 --- a/_data/engine-cli/docker_export.yaml +++ b/_data/engine-cli/docker_export.yaml @@ -1,36 +1,49 @@ command: docker export +aliases: docker container export, docker export short: Export a container's filesystem as a tar archive long: |- - The `docker export` command does not export the contents of volumes associated - with the container. If a volume is mounted on top of an existing directory in - the container, `docker export` will export the contents of the *underlying* - directory, not the contents of the volume. + The `docker export` command does not export the contents of volumes associated + with the container. If a volume is mounted on top of an existing directory in + the container, `docker export` will export the contents of the *underlying* + directory, not the contents of the volume. - Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes) - in the user guide for examples on exporting data in a volume. + Refer to [Backup, restore, or migrate data volumes](/storage/volumes/#back-up-restore-or-migrate-data-volumes) + in the user guide for examples on exporting data in a volume. usage: docker export [OPTIONS] CONTAINER pname: docker plink: docker.yaml options: -- option: output - shorthand: o - value_type: string - description: Write to a file, instead of STDOUT - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: output + shorthand: o + value_type: string + description: Write to a file, instead of STDOUT + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Each of these commands has the same result. + Each of these commands has the same result. - ```console - $ docker export red_panda > latest.tar - ``` + ```console + $ docker export red_panda > latest.tar + ``` - ```console - $ docker export --output="latest.tar" red_panda - ``` + ```console + $ docker export --output="latest.tar" red_panda + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_history.yaml b/_data/engine-cli/docker_history.yaml index 9fa0f65fe1..e41d3b2a62 100644 --- a/_data/engine-cli/docker_history.yaml +++ b/_data/engine-cli/docker_history.yaml @@ -1,103 +1,126 @@ command: docker history +aliases: docker image history, docker history short: Show the history of an image long: Show the history of an image usage: docker history [OPTIONS] IMAGE pname: docker plink: docker.yaml options: -- option: format - value_type: string - description: Pretty-print images using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: human - shorthand: H - value_type: bool - default_value: "true" - description: Print sizes and dates in human readable format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only show image IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: human + shorthand: H + value_type: bool + default_value: "true" + description: Print sizes and dates in human readable format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only show image IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - To see how the `docker:latest` image was built: + To see how the `docker:latest` image was built: - ```console - $ docker history docker + ```console + $ docker history docker - IMAGE CREATED CREATED BY SIZE COMMENT - 3e23a5875458 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B - 8578938dd170 8 days ago /bin/sh -c dpkg-reconfigure locales && loc 1.245 MB - be51b77efb42 8 days ago /bin/sh -c apt-get update && apt-get install 338.3 MB - 4b137612be55 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB - 750d58736b4b 6 weeks ago /bin/sh -c #(nop) MAINTAINER Tianon Gravi Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) will pretty-prints history output - using a Go template. + The formatting option (`--format`) will pretty-prints history output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |-----------------|-----------------------------------------------------------------------------------------------------------| - | `.ID` | Image ID | - | `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created | - | `.CreatedAt` | Timestamp of when image was created | - | `.CreatedBy` | Command that was used to create the image | - | `.Size` | Image disk size | - | `.Comment` | Comment for image | + | Placeholder | Description | + |-----------------|-----------------------------------------------------------------------------------------------------------| + | `.ID` | Image ID | + | `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created | + | `.CreatedAt` | Timestamp of when image was created | + | `.CreatedBy` | Command that was used to create the image | + | `.Size` | Image disk size | + | `.Comment` | Comment for image | - When using the `--format` option, the `history` command will either - output the data exactly as the template declares or, when using the - `table` directive, will include column headers as well. + When using the `--format` option, the `history` command will either + output the data exactly as the template declares or, when using the + `table` directive, will include column headers as well. - The following example uses a template without headers and outputs the - `ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` - image: + The following example uses a template without headers and outputs the + `ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` + image: - ```console - $ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox + ```console + $ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox - f6e427c148a7: 4 weeks ago - : 4 weeks ago - ``` + f6e427c148a7: 4 weeks ago + : 4 weeks ago + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image.yaml b/_data/engine-cli/docker_image.yaml index c094b25a6f..6e3069ae7d 100644 --- a/_data/engine-cli/docker_image.yaml +++ b/_data/engine-cli/docker_image.yaml @@ -5,31 +5,42 @@ usage: docker image pname: docker plink: docker.yaml cname: -- docker image build -- docker image history -- docker image import -- docker image inspect -- docker image load -- docker image ls -- docker image prune -- docker image pull -- docker image push -- docker image rm -- docker image save -- docker image tag + - docker image build + - docker image history + - docker image import + - docker image inspect + - docker image load + - docker image ls + - docker image prune + - docker image pull + - docker image push + - docker image rm + - docker image save + - docker image tag clink: -- docker_image_build.yaml -- docker_image_history.yaml -- docker_image_import.yaml -- docker_image_inspect.yaml -- docker_image_load.yaml -- docker_image_ls.yaml -- docker_image_prune.yaml -- docker_image_pull.yaml -- docker_image_push.yaml -- docker_image_rm.yaml -- docker_image_save.yaml -- docker_image_tag.yaml + - docker_image_build.yaml + - docker_image_history.yaml + - docker_image_import.yaml + - docker_image_inspect.yaml + - docker_image_load.yaml + - docker_image_ls.yaml + - docker_image_prune.yaml + - docker_image_pull.yaml + - docker_image_push.yaml + - docker_image_rm.yaml + - docker_image_save.yaml + - docker_image_tag.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_build.yaml b/_data/engine-cli/docker_image_build.yaml index f203b67f3c..97d5599817 100644 --- a/_data/engine-cli/docker_image_build.yaml +++ b/_data/engine-cli/docker_image_build.yaml @@ -1,330 +1,318 @@ command: docker image build +aliases: docker image build, docker build, docker buildx build, docker builder build short: Build an image from a Dockerfile -long: Build an image from a Dockerfile +long: See [docker build](build.md) for more information. usage: docker image build [OPTIONS] PATH | URL | - pname: docker image plink: docker_image.yaml options: -- option: add-host - value_type: list - description: Add a custom host-to-IP mapping (host:ip) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: build-arg - value_type: list - description: Set build-time variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cache-from - value_type: stringSlice - default_value: '[]' - description: Images to consider as cache sources - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroup-parent - value_type: string - description: Optional parent cgroup for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: compress - value_type: bool - default_value: "false" - description: Compress the build context using gzip - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit the CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit the CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: file - shorthand: f - value_type: string - description: Name of the Dockerfile (Default is 'PATH/Dockerfile') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force-rm - value_type: bool - default_value: "false" - description: Always remove intermediate containers - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: iidfile - value_type: string - description: Write the image ID to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Container isolation technology - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - value_type: list - description: Set metadata for an image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: string - default_value: default - description: | - Set the networking mode for the RUN instructions during build - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-cache - value_type: bool - default_value: "false" - description: Do not use cache when building the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: output - shorthand: o - value_type: stringArray - default_value: '[]' - description: 'Output destination (format: type=local,dest=path)' - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.38" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: progress - value_type: string - default_value: auto - description: | - Set type of progress output (auto, plain, tty). Use plain to show container output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Always attempt to pull a newer version of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress the build output and print image ID on success - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rm - value_type: bool - default_value: "true" - description: Remove intermediate containers after a successful build - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: secret - value_type: stringArray - default_value: '[]' - description: | - Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret - deprecated: false - min_api_version: "1.39" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: security-opt - value_type: stringSlice - default_value: '[]' - description: Security options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: shm-size - value_type: bytes - default_value: "0" - description: Size of /dev/shm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: squash - value_type: bool - default_value: "false" - description: Squash newly built layers into a single new layer - deprecated: false - min_api_version: "1.25" - experimental: true - experimentalcli: false - kubernetes: false - swarm: false -- option: ssh - value_type: stringArray - default_value: '[]' - description: | - SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|[=|[,]]) - deprecated: false - min_api_version: "1.39" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stream - value_type: bool - default_value: "false" - description: Stream attaches to server to negotiate build context - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tag - shorthand: t - value_type: list - description: Name and optionally a tag in the 'name:tag' format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: target - value_type: string - description: Set the target build stage to build. - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: ulimit - default_value: '[]' - description: Ulimit options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: add-host + value_type: list + description: Add a custom host-to-IP mapping (`host:ip`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: build-arg + value_type: list + description: Set build-time variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cache-from + value_type: stringSlice + default_value: '[]' + description: Images to consider as cache sources + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: compress + value_type: bool + default_value: "false" + description: Compress the build context using gzip + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: file + shorthand: f + value_type: string + description: Name of the Dockerfile (Default is `PATH/Dockerfile`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force-rm + value_type: bool + default_value: "false" + description: Always remove intermediate containers + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: iidfile + value_type: string + description: Write the image ID to the file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Container isolation technology + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + value_type: list + description: Set metadata for an image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: 'Swap limit equal to memory plus swap: -1 to enable unlimited swap' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: string + default_value: default + description: Set the networking mode for the RUN instructions during build + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-cache + value_type: bool + default_value: "false" + description: Do not use cache when building the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.38" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pull + value_type: bool + default_value: "false" + description: Always attempt to pull a newer version of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the build output and print image ID on success + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rm + value_type: bool + default_value: "true" + description: Remove intermediate containers after a successful build + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: security-opt + value_type: stringSlice + default_value: '[]' + description: Security options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: shm-size + value_type: bytes + default_value: "0" + description: Size of `/dev/shm` + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: squash + value_type: bool + default_value: "false" + description: Squash newly built layers into a single new layer + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: true + experimentalcli: false + kubernetes: false + swarm: false + - option: tag + shorthand: t + value_type: list + description: Name and optionally a tag in the `name:tag` format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: target + value_type: string + description: Set the target build stage to build. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_history.yaml b/_data/engine-cli/docker_image_history.yaml index f27bf2d04d..8296b3a785 100644 --- a/_data/engine-cli/docker_image_history.yaml +++ b/_data/engine-cli/docker_image_history.yaml @@ -1,47 +1,69 @@ command: docker image history +aliases: docker image history, docker history short: Show the history of an image -long: Show the history of an image +long: See [docker history](history.md) for more information. usage: docker image history [OPTIONS] IMAGE pname: docker image plink: docker_image.yaml options: -- option: format - value_type: string - description: Pretty-print images using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: human - shorthand: H - value_type: bool - default_value: "true" - description: Print sizes and dates in human readable format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only show image IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: human + shorthand: H + value_type: bool + default_value: "true" + description: Print sizes and dates in human readable format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only show image IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_import.yaml b/_data/engine-cli/docker_image_import.yaml index f57a2cd39a..e394a81acc 100644 --- a/_data/engine-cli/docker_image_import.yaml +++ b/_data/engine-cli/docker_image_import.yaml @@ -1,37 +1,52 @@ command: docker image import +aliases: docker image import, docker import short: Import the contents from a tarball to create a filesystem image -long: Import the contents from a tarball to create a filesystem image +long: See [docker import](import.md) for more information. usage: docker image import [OPTIONS] file|URL|- [REPOSITORY[:TAG]] pname: docker image plink: docker_image.yaml options: -- option: change - shorthand: c - value_type: list - description: Apply Dockerfile instruction to the created image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: message - shorthand: m - value_type: string - description: Set commit message for imported image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: change + shorthand: c + value_type: list + description: Apply Dockerfile instruction to the created image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: message + shorthand: m + value_type: string + description: Set commit message for imported image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_inspect.yaml b/_data/engine-cli/docker_image_inspect.yaml index e79573128a..04b7b74ae7 100644 --- a/_data/engine-cli/docker_image_inspect.yaml +++ b/_data/engine-cli/docker_image_inspect.yaml @@ -5,15 +5,31 @@ usage: docker image inspect [OPTIONS] IMAGE [IMAGE...] pname: docker image plink: docker_image.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_load.yaml b/_data/engine-cli/docker_image_load.yaml index 61d47dab9b..a279c8d618 100644 --- a/_data/engine-cli/docker_image_load.yaml +++ b/_data/engine-cli/docker_image_load.yaml @@ -1,29 +1,43 @@ command: docker image load +aliases: docker image load, docker load short: Load an image from a tar archive or STDIN -long: Load an image from a tar archive or STDIN +long: See [docker load](load.md) for more information. usage: docker image load [OPTIONS] pname: docker image plink: docker_image.yaml options: -- option: input - shorthand: i - value_type: string - description: Read from tar archive file, instead of STDIN - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress the load output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: input + shorthand: i + value_type: string + description: Read from tar archive file, instead of STDIN + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the load output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_ls.yaml b/_data/engine-cli/docker_image_ls.yaml index 2cc8703bcc..d9abc72688 100644 --- a/_data/engine-cli/docker_image_ls.yaml +++ b/_data/engine-cli/docker_image_ls.yaml @@ -1,66 +1,89 @@ command: docker image ls -aliases: list +aliases: docker image ls, docker image list, docker images short: List images -long: List images +long: See [docker images](images.md) for more information. usage: docker image ls [OPTIONS] [REPOSITORY[:TAG]] pname: docker image plink: docker_image.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Show all images (default hides intermediate images) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: digests - value_type: bool - default_value: "false" - description: Show digests - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print images using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only show image IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Show all images (default hides intermediate images) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: digests + value_type: bool + default_value: "false" + description: Show digests + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only show image IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_prune.yaml b/_data/engine-cli/docker_image_prune.yaml index cea6ab0a76..536c610156 100644 --- a/_data/engine-cli/docker_image_prune.yaml +++ b/_data/engine-cli/docker_image_prune.yaml @@ -1,212 +1,227 @@ command: docker image prune short: Remove unused images -long: Remove all dangling images. If `-a` is specified, will also remove all images - not referenced by any container. +long: | + Remove all dangling images. If `-a` is specified, will also remove all images not referenced by any container. usage: docker image prune [OPTIONS] pname: docker image plink: docker_image.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Remove all unused images, not just dangling ones - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: filter - value_type: filter - description: Provide filter values (e.g. 'until=') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Do not prompt for confirmation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Remove all unused images, not just dangling ones + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: filter + value_type: filter + description: Provide filter values (e.g. `until=`) + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Do not prompt for confirmation + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Example output: + Example output: - ```console - $ docker image prune -a + ```console + $ docker image prune -a - WARNING! This will remove all images without at least one container associated to them. - Are you sure you want to continue? [y/N] y - Deleted Images: - untagged: alpine:latest - untagged: alpine@sha256:3dcdb92d7432d56604d4545cbd324b14e647b313626d99b889d0626de158f73a - deleted: sha256:4e38e38c8ce0b8d9041a9c4fefe786631d1416225e13b0bfe8cfa2321aec4bba - deleted: sha256:4fe15f8d0ae69e169824f25f1d4da3015a48feeeeebb265cd2e328e15c6a869f - untagged: alpine:3.3 - untagged: alpine@sha256:4fa633f4feff6a8f02acfc7424efd5cb3e76686ed3218abf4ca0fa4a2a358423 - untagged: my-jq:latest - deleted: sha256:ae67841be6d008a374eff7c2a974cde3934ffe9536a7dc7ce589585eddd83aff - deleted: sha256:34f6f1261650bc341eb122313372adc4512b4fceddc2a7ecbb84f0958ce5ad65 - deleted: sha256:cf4194e8d8db1cb2d117df33f2c75c0369c3a26d96725efb978cc69e046b87e7 - untagged: my-curl:latest - deleted: sha256:b2789dd875bf427de7f9f6ae001940073b3201409b14aba7e5db71f408b8569e - deleted: sha256:96daac0cb203226438989926fc34dd024f365a9a8616b93e168d303cfe4cb5e9 - deleted: sha256:5cbd97a14241c9cd83250d6b6fc0649833c4a3e84099b968dd4ba403e609945e - deleted: sha256:a0971c4015c1e898c60bf95781c6730a05b5d8a2ae6827f53837e6c9d38efdec - deleted: sha256:d8359ca3b681cc5396a4e790088441673ed3ce90ebc04de388bfcd31a0716b06 - deleted: sha256:83fc9ba8fb70e1da31dfcc3c88d093831dbd4be38b34af998df37e8ac538260c - deleted: sha256:ae7041a4cc625a9c8e6955452f7afe602b401f662671cea3613f08f3d9343b35 - deleted: sha256:35e0f43a37755b832f0bbea91a2360b025ee351d7309dae0d9737bc96b6d0809 - deleted: sha256:0af941dd29f00e4510195dd00b19671bc591e29d1495630e7e0f7c44c1e6a8c0 - deleted: sha256:9fc896fc2013da84f84e45b3096053eb084417b42e6b35ea0cce5a3529705eac - deleted: sha256:47cf20d8c26c46fff71be614d9f54997edacfe8d46d51769706e5aba94b16f2b - deleted: sha256:2c675ee9ed53425e31a13e3390bf3f539bf8637000e4bcfbb85ee03ef4d910a1 + WARNING! This will remove all images without at least one container associated to them. + Are you sure you want to continue? [y/N] y + Deleted Images: + untagged: alpine:latest + untagged: alpine@sha256:3dcdb92d7432d56604d4545cbd324b14e647b313626d99b889d0626de158f73a + deleted: sha256:4e38e38c8ce0b8d9041a9c4fefe786631d1416225e13b0bfe8cfa2321aec4bba + deleted: sha256:4fe15f8d0ae69e169824f25f1d4da3015a48feeeeebb265cd2e328e15c6a869f + untagged: alpine:3.3 + untagged: alpine@sha256:4fa633f4feff6a8f02acfc7424efd5cb3e76686ed3218abf4ca0fa4a2a358423 + untagged: my-jq:latest + deleted: sha256:ae67841be6d008a374eff7c2a974cde3934ffe9536a7dc7ce589585eddd83aff + deleted: sha256:34f6f1261650bc341eb122313372adc4512b4fceddc2a7ecbb84f0958ce5ad65 + deleted: sha256:cf4194e8d8db1cb2d117df33f2c75c0369c3a26d96725efb978cc69e046b87e7 + untagged: my-curl:latest + deleted: sha256:b2789dd875bf427de7f9f6ae001940073b3201409b14aba7e5db71f408b8569e + deleted: sha256:96daac0cb203226438989926fc34dd024f365a9a8616b93e168d303cfe4cb5e9 + deleted: sha256:5cbd97a14241c9cd83250d6b6fc0649833c4a3e84099b968dd4ba403e609945e + deleted: sha256:a0971c4015c1e898c60bf95781c6730a05b5d8a2ae6827f53837e6c9d38efdec + deleted: sha256:d8359ca3b681cc5396a4e790088441673ed3ce90ebc04de388bfcd31a0716b06 + deleted: sha256:83fc9ba8fb70e1da31dfcc3c88d093831dbd4be38b34af998df37e8ac538260c + deleted: sha256:ae7041a4cc625a9c8e6955452f7afe602b401f662671cea3613f08f3d9343b35 + deleted: sha256:35e0f43a37755b832f0bbea91a2360b025ee351d7309dae0d9737bc96b6d0809 + deleted: sha256:0af941dd29f00e4510195dd00b19671bc591e29d1495630e7e0f7c44c1e6a8c0 + deleted: sha256:9fc896fc2013da84f84e45b3096053eb084417b42e6b35ea0cce5a3529705eac + deleted: sha256:47cf20d8c26c46fff71be614d9f54997edacfe8d46d51769706e5aba94b16f2b + deleted: sha256:2c675ee9ed53425e31a13e3390bf3f539bf8637000e4bcfbb85ee03ef4d910a1 - Total reclaimed space: 16.43 MB - ``` + Total reclaimed space: 16.43 MB + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - 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 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: + The currently supported filters are: - * until (``) - only remove images created before given timestamp - * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove images with (or without, in case `label!=...` is used) the specified labels. + * until (``) - only remove images created before given timestamp + * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove images with (or without, in case `label!=...` is used) the specified labels. - The `until` filter can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed - relative to the daemon machine’s time. Supported formats for date - formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local - timezone on the daemon will be used if you do not provide either a `Z` or a - `+-00:00` timezone offset at the end of the timestamp. When providing Unix - timestamps enter seconds[.nanoseconds], where seconds is the number of seconds - that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap - seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a - fraction of a second no more than nine digits long. + The `until` filter can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the daemon machine’s time. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the daemon will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. - The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), - which removes images with the specified labels. The other - format is the `label!=...` (`label!=` or `label!==`), which removes - images without the specified labels. + The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), + which removes images with the specified labels. The other + format is the `label!=...` (`label!=` or `label!==`), which removes + images without the specified labels. - > **Predicting what will be removed** - > - > If you are using positive filtering (testing for the existence of a label or - > that a label has a specific value), you can use `docker image ls` with the - > same filtering syntax to see which images match your filter. - > - > However, if you are using negative filtering (testing for the absence of a - > label or that a label does *not* have a specific value), this type of filter - > does not work with `docker image ls` so you cannot easily predict which images - > will be removed. In addition, the confirmation prompt for `docker image prune` - > always warns that *all* dangling images will be removed, even if you are using - > `--filter`. + > **Predicting what will be removed** + > + > If you are using positive filtering (testing for the existence of a label or + > that a label has a specific value), you can use `docker image ls` with the + > same filtering syntax to see which images match your filter. + > + > However, if you are using negative filtering (testing for the absence of a + > label or that a label does *not* have a specific value), this type of filter + > does not work with `docker image ls` so you cannot easily predict which images + > will be removed. In addition, the confirmation prompt for `docker image prune` + > always warns that *all* dangling images will be removed, even if you are using + > `--filter`. - The following removes images created before `2017-01-04T00:00:00`: + The following removes images created before `2017-01-04T00:00:00`: - ```console - $ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}' - REPOSITORY TAG IMAGE ID CREATED AT SIZE - foo latest 2f287ac753da 2017-01-04 13:42:23 -0800 PST 3.98 MB - alpine latest 88e169ea8f46 2016-12-27 10:17:25 -0800 PST 3.98 MB - busybox latest e02e811dd08f 2016-10-07 14:03:58 -0700 PDT 1.09 MB + ```console + $ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}' + REPOSITORY TAG IMAGE ID CREATED AT SIZE + foo latest 2f287ac753da 2017-01-04 13:42:23 -0800 PST 3.98 MB + alpine latest 88e169ea8f46 2016-12-27 10:17:25 -0800 PST 3.98 MB + busybox latest e02e811dd08f 2016-10-07 14:03:58 -0700 PDT 1.09 MB - $ docker image prune -a --force --filter "until=2017-01-04T00:00:00" + $ docker image prune -a --force --filter "until=2017-01-04T00:00:00" - Deleted Images: - untagged: alpine:latest - untagged: alpine@sha256:dfbd4a3a8ebca874ebd2474f044a0b33600d4523d03b0df76e5c5986cb02d7e8 - untagged: busybox:latest - untagged: busybox@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 - deleted: sha256:e02e811dd08fd49e7f6032625495118e63f597eb150403d02e3238af1df240ba - deleted: sha256:e88b3f82283bc59d5e0df427c824e9f95557e661fcb0ea15fb0fb6f97760f9d9 + Deleted Images: + untagged: alpine:latest + untagged: alpine@sha256:dfbd4a3a8ebca874ebd2474f044a0b33600d4523d03b0df76e5c5986cb02d7e8 + untagged: busybox:latest + untagged: busybox@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 + deleted: sha256:e02e811dd08fd49e7f6032625495118e63f597eb150403d02e3238af1df240ba + deleted: sha256:e88b3f82283bc59d5e0df427c824e9f95557e661fcb0ea15fb0fb6f97760f9d9 - Total reclaimed space: 1.093 MB + Total reclaimed space: 1.093 MB - $ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}' + $ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}' - REPOSITORY TAG IMAGE ID CREATED AT SIZE - foo latest 2f287ac753da 2017-01-04 13:42:23 -0800 PST 3.98 MB - ``` + REPOSITORY TAG IMAGE ID CREATED AT SIZE + foo latest 2f287ac753da 2017-01-04 13:42:23 -0800 PST 3.98 MB + ``` - The following removes images created more than 10 days (`240h`) ago: + The following removes images created more than 10 days (`240h`) ago: - ```console - $ docker images + ```console + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - foo latest 2f287ac753da 14 seconds ago 3.98 MB - alpine latest 88e169ea8f46 8 days ago 3.98 MB - debian jessie 7b0a06c805e8 2 months ago 123 MB - busybox latest e02e811dd08f 2 months ago 1.09 MB - golang 1.7.0 138c2e655421 4 months ago 670 MB + REPOSITORY TAG IMAGE ID CREATED SIZE + foo latest 2f287ac753da 14 seconds ago 3.98 MB + alpine latest 88e169ea8f46 8 days ago 3.98 MB + debian jessie 7b0a06c805e8 2 months ago 123 MB + busybox latest e02e811dd08f 2 months ago 1.09 MB + golang 1.7.0 138c2e655421 4 months ago 670 MB - $ docker image prune -a --force --filter "until=240h" + $ docker image prune -a --force --filter "until=240h" - Deleted Images: - untagged: golang:1.7.0 - untagged: golang@sha256:6765038c2b8f407fd6e3ecea043b44580c229ccfa2a13f6d85866cf2b4a9628e - deleted: sha256:138c2e6554219de65614d88c15521bfb2da674cbb0bf840de161f89ff4264b96 - deleted: sha256:ec353c2e1a673f456c4b78906d0d77f9d9456cfb5229b78c6a960bfb7496b76a - deleted: sha256:fe22765feaf3907526b4921c73ea6643ff9e334497c9b7e177972cf22f68ee93 - deleted: sha256:ff845959c80148421a5c3ae11cc0e6c115f950c89bc949646be55ed18d6a2912 - deleted: sha256:a4320831346648c03db64149eafc83092e2b34ab50ca6e8c13112388f25899a7 - deleted: sha256:4c76020202ee1d9709e703b7c6de367b325139e74eebd6b55b30a63c196abaf3 - deleted: sha256:d7afd92fb07236c8a2045715a86b7d5f0066cef025018cd3ca9a45498c51d1d6 - deleted: sha256:9e63c5bce4585dd7038d830a1f1f4e44cb1a1515b00e620ac718e934b484c938 - untagged: debian:jessie - untagged: debian@sha256:c1af755d300d0c65bb1194d24bce561d70c98a54fb5ce5b1693beb4f7988272f - deleted: sha256:7b0a06c805e8f23807fb8856621c60851727e85c7bcb751012c813f122734c8d - deleted: sha256:f96222d75c5563900bc4dd852179b720a0885de8f7a0619ba0ac76e92542bbc8 + Deleted Images: + untagged: golang:1.7.0 + untagged: golang@sha256:6765038c2b8f407fd6e3ecea043b44580c229ccfa2a13f6d85866cf2b4a9628e + deleted: sha256:138c2e6554219de65614d88c15521bfb2da674cbb0bf840de161f89ff4264b96 + deleted: sha256:ec353c2e1a673f456c4b78906d0d77f9d9456cfb5229b78c6a960bfb7496b76a + deleted: sha256:fe22765feaf3907526b4921c73ea6643ff9e334497c9b7e177972cf22f68ee93 + deleted: sha256:ff845959c80148421a5c3ae11cc0e6c115f950c89bc949646be55ed18d6a2912 + deleted: sha256:a4320831346648c03db64149eafc83092e2b34ab50ca6e8c13112388f25899a7 + deleted: sha256:4c76020202ee1d9709e703b7c6de367b325139e74eebd6b55b30a63c196abaf3 + deleted: sha256:d7afd92fb07236c8a2045715a86b7d5f0066cef025018cd3ca9a45498c51d1d6 + deleted: sha256:9e63c5bce4585dd7038d830a1f1f4e44cb1a1515b00e620ac718e934b484c938 + untagged: debian:jessie + untagged: debian@sha256:c1af755d300d0c65bb1194d24bce561d70c98a54fb5ce5b1693beb4f7988272f + deleted: sha256:7b0a06c805e8f23807fb8856621c60851727e85c7bcb751012c813f122734c8d + deleted: sha256:f96222d75c5563900bc4dd852179b720a0885de8f7a0619ba0ac76e92542bbc8 - Total reclaimed space: 792.6 MB + Total reclaimed space: 792.6 MB - $ docker images + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - foo latest 2f287ac753da About a minute ago 3.98 MB - alpine latest 88e169ea8f46 8 days ago 3.98 MB - busybox latest e02e811dd08f 2 months ago 1.09 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + foo latest 2f287ac753da About a minute ago 3.98 MB + alpine latest 88e169ea8f46 8 days ago 3.98 MB + busybox latest e02e811dd08f 2 months ago 1.09 MB + ``` - The following example removes images with the label `deprecated`: + The following example removes images with the label `deprecated`: - ```console - $ docker image prune --filter="label=deprecated" - ``` + ```console + $ docker image prune --filter="label=deprecated" + ``` - The following example removes images with the label `maintainer` set to `john`: + The following example removes images with the label `maintainer` set to `john`: - ```console - $ docker image prune --filter="label=maintainer=john" - ``` + ```console + $ docker image prune --filter="label=maintainer=john" + ``` - This example removes images which have no `maintainer` label: + This example removes images which have no `maintainer` label: - ```console - $ docker image prune --filter="label!=maintainer" - ``` + ```console + $ docker image prune --filter="label!=maintainer" + ``` - This example removes images which have a maintainer label not set to `john`: + This example removes images which have a maintainer label not set to `john`: - ```console - $ docker image prune --filter="label!=maintainer=john" - ``` + ```console + $ docker image prune --filter="label!=maintainer=john" + ``` - > **Note** - > - > You are prompted for confirmation before the `prune` removes - > anything, but you are not shown a list of what will potentially be removed. - > In addition, `docker image ls` does not support negative filtering, so it - > difficult to predict what images will actually be removed. + > **Note** + > + > You are prompted for confirmation before the `prune` removes + > anything, but you are not shown a list of what will potentially be removed. + > In addition, `docker image ls` does not support negative filtering, so it + > difficult to predict what images will actually be removed. deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_image_pull.yaml b/_data/engine-cli/docker_image_pull.yaml index 038c6f91b2..a76ef51291 100644 --- a/_data/engine-cli/docker_image_pull.yaml +++ b/_data/engine-cli/docker_image_pull.yaml @@ -1,48 +1,64 @@ command: docker image pull -short: Pull an image or a repository from a registry -long: Pull an image or a repository from a registry +aliases: docker image pull, docker pull +short: Download an image from a registry +long: See [docker pull](pull.md) for more information. usage: docker image pull [OPTIONS] NAME[:TAG|@DIGEST] pname: docker image plink: docker_image.yaml options: -- option: all-tags - shorthand: a - value_type: bool - default_value: "false" - description: Download all tagged images in the repository - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress verbose output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all-tags + shorthand: a + value_type: bool + default_value: "false" + description: Download all tagged images in the repository + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_push.yaml b/_data/engine-cli/docker_image_push.yaml index cf9e6e77b8..9408c2ec8c 100644 --- a/_data/engine-cli/docker_image_push.yaml +++ b/_data/engine-cli/docker_image_push.yaml @@ -1,39 +1,54 @@ command: docker image push -short: Push an image or a repository to a registry -long: Push an image or a repository to a registry +aliases: docker image push, docker push +short: Upload an image to a registry +long: See [docker push](push.md) for more information. usage: docker image push [OPTIONS] NAME[:TAG] pname: docker image plink: docker_image.yaml options: -- option: all-tags - shorthand: a - value_type: bool - default_value: "false" - description: Push all tagged images in the repository - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image signing - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress verbose output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all-tags + shorthand: a + value_type: bool + default_value: "false" + description: Push all tags of an image to the repository + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image signing + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_rm.yaml b/_data/engine-cli/docker_image_rm.yaml index c60a498429..26af7d8e53 100644 --- a/_data/engine-cli/docker_image_rm.yaml +++ b/_data/engine-cli/docker_image_rm.yaml @@ -1,30 +1,43 @@ command: docker image rm -aliases: rmi, remove +aliases: docker image rm, docker image remove, docker rmi short: Remove one or more images -long: Remove one or more images +long: See [docker rmi](rmi.md) for more information. usage: docker image rm [OPTIONS] IMAGE [IMAGE...] pname: docker image plink: docker_image.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force removal of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-prune - value_type: bool - default_value: "false" - description: Do not delete untagged parents - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force removal of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-prune + value_type: bool + default_value: "false" + description: Do not delete untagged parents + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_save.yaml b/_data/engine-cli/docker_image_save.yaml index 1fbdbb1a05..bfc4988165 100644 --- a/_data/engine-cli/docker_image_save.yaml +++ b/_data/engine-cli/docker_image_save.yaml @@ -1,19 +1,32 @@ command: docker image save +aliases: docker image save, docker save short: Save one or more images to a tar archive (streamed to STDOUT by default) -long: Save one or more images to a tar archive (streamed to STDOUT by default) +long: See [docker save](save.md) for more information. usage: docker image save [OPTIONS] IMAGE [IMAGE...] pname: docker image plink: docker_image.yaml options: -- option: output - shorthand: o - value_type: string - description: Write to a file, instead of STDOUT - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: output + shorthand: o + value_type: string + description: Write to a file, instead of STDOUT + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_tag.yaml b/_data/engine-cli/docker_image_tag.yaml index 3830ef1b8d..fa8091a522 100644 --- a/_data/engine-cli/docker_image_tag.yaml +++ b/_data/engine-cli/docker_image_tag.yaml @@ -1,9 +1,21 @@ command: docker image tag +aliases: docker image tag, docker tag short: Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE -long: Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE +long: See [docker tag](tag.md) for more information. usage: docker image tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] pname: docker image plink: docker_image.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_images.yaml b/_data/engine-cli/docker_images.yaml index 4f1795e259..ecc60e853c 100644 --- a/_data/engine-cli/docker_images.yaml +++ b/_data/engine-cli/docker_images.yaml @@ -1,376 +1,412 @@ command: docker images +aliases: docker image ls, docker image list, docker images short: List images long: |- - The default `docker images` will show all top level - images, their repository and tags, and their size. + The default `docker images` will show all top level + images, their repository and tags, and their size. - Docker images have intermediate layers that increase reusability, - decrease disk usage, and speed up `docker build` by - allowing each step to be cached. These intermediate layers are not shown - by default. + Docker images have intermediate layers that increase reusability, + decrease disk usage, and speed up `docker build` by + allowing each step to be cached. These intermediate layers are not shown + by default. - The `SIZE` is the cumulative space taken up by the image and all - its parent images. This is also the disk space used by the contents of the - Tar file created when you `docker save` an image. + The `SIZE` is the cumulative space taken up by the image and all + its parent images. This is also the disk space used by the contents of the + Tar file created when you `docker save` an image. - An image will be listed more than once if it has multiple repository names - or tags. This single image (identifiable by its matching `IMAGE ID`) - uses up the `SIZE` listed only once. + An image will be listed more than once if it has multiple repository names + or tags. This single image (identifiable by its matching `IMAGE ID`) + uses up the `SIZE` listed only once. usage: docker images [OPTIONS] [REPOSITORY[:TAG]] pname: docker plink: docker.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Show all images (default hides intermediate images) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: digests - value_type: bool - default_value: "false" - description: Show digests - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print images using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only show image IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Show all images (default hides intermediate images) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: digests + value_type: bool + default_value: "false" + description: Show digests + details_url: '#digests' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + details_url: '#no-trunc' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only show image IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### List the most recently created images + ### List the most recently created images - ```console - $ docker images + ```console + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - 77af4d6b9913 19 hours ago 1.089 GB - committ latest b6fa739cedf5 19 hours ago 1.089 GB - 78a85c484f71 19 hours ago 1.089 GB - docker latest 30557a29d5ab 20 hours ago 1.089 GB - 5ed6274db6ce 24 hours ago 1.089 GB - postgres 9 746b819f315e 4 days ago 213.4 MB - postgres 9.3 746b819f315e 4 days ago 213.4 MB - postgres 9.3.5 746b819f315e 4 days ago 213.4 MB - postgres latest 746b819f315e 4 days ago 213.4 MB - ``` - - ### List images by name and tag + REPOSITORY TAG IMAGE ID CREATED SIZE + 77af4d6b9913 19 hours ago 1.089 GB + committ latest b6fa739cedf5 19 hours ago 1.089 GB + 78a85c484f71 19 hours ago 1.089 GB + docker latest 30557a29d5ab 20 hours ago 1.089 GB + 5ed6274db6ce 24 hours ago 1.089 GB + postgres 9 746b819f315e 4 days ago 213.4 MB + postgres 9.3 746b819f315e 4 days ago 213.4 MB + postgres 9.3.5 746b819f315e 4 days ago 213.4 MB + postgres latest 746b819f315e 4 days ago 213.4 MB + ``` + + ### List images by name and tag - The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument - that restricts the list to images that match the argument. If you specify - `REPOSITORY`but no `TAG`, the `docker images` command lists all images in the - given repository. - - For example, to list all images in the "java" repository, run this command : - - ```console - $ docker images java - - REPOSITORY TAG IMAGE ID CREATED SIZE - java 8 308e519aac60 6 days ago 824.5 MB - java 7 493d82594c15 3 months ago 656.3 MB - java latest 2711b1d6f3aa 5 months ago 603.9 MB - ``` - - The `[REPOSITORY[:TAG]]` value must be an "exact match". This means that, for example, - `docker images jav` does not match the image `java`. - - If both `REPOSITORY` and `TAG` are provided, only images matching that - repository and tag are listed. To find all local images in the "java" - repository with tag "8" you can use: + The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument + that restricts the list to images that match the argument. If you specify + `REPOSITORY`but no `TAG`, the `docker images` command lists all images in the + given repository. + + For example, to list all images in the "java" repository, run this command : + + ```console + $ docker images java + + REPOSITORY TAG IMAGE ID CREATED SIZE + java 8 308e519aac60 6 days ago 824.5 MB + java 7 493d82594c15 3 months ago 656.3 MB + java latest 2711b1d6f3aa 5 months ago 603.9 MB + ``` + + The `[REPOSITORY[:TAG]]` value must be an "exact match". This means that, for example, + `docker images jav` does not match the image `java`. + + If both `REPOSITORY` and `TAG` are provided, only images matching that + repository and tag are listed. To find all local images in the "java" + repository with tag "8" you can use: - ```console - $ docker images java:8 + ```console + $ docker images java:8 - REPOSITORY TAG IMAGE ID CREATED SIZE - java 8 308e519aac60 6 days ago 824.5 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + java 8 308e519aac60 6 days ago 824.5 MB + ``` - If nothing matches `REPOSITORY[:TAG]`, the list is empty. + If nothing matches `REPOSITORY[:TAG]`, the list is empty. - ```console - $ docker images java:0 + ```console + $ docker images java:0 - REPOSITORY TAG IMAGE ID CREATED SIZE - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + ``` - ### List the full length image IDs (--no-trunc) + ### List the full length image IDs (--no-trunc) {#no-trunc} - ```console - $ docker images --no-trunc + ```console + $ docker images --no-trunc - REPOSITORY TAG IMAGE ID CREATED SIZE - sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB - committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB - sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB - docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB - sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB - sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB - sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB - tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB - sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB + committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB + sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB + docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB + sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB + sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB + sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB + tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB + sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB + ``` - ### List image digests (--digests) + ### List image digests (--digests) {#digests} - Images that use the v2 or later format have a content-addressable identifier - called a `digest`. As long as the input used to generate the image is - unchanged, the digest value is predictable. To list image digest values, use - the `--digests` flag: + Images that use the v2 or later format have a content-addressable identifier + called a `digest`. As long as the input used to generate the image is + unchanged, the digest value is predictable. To list image digest values, use + the `--digests` flag: - ```console - $ docker images --digests - REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE - localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB - ``` + ```console + $ docker images --digests + REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE + localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB + ``` - When pushing or pulling to a 2.0 registry, the `push` or `pull` command - output includes the image digest. You can `pull` using a digest value. You can - also reference by digest in `create`, `run`, and `rmi` commands, as well as the - `FROM` image reference in a Dockerfile. + When pushing or pulling to a 2.0 registry, the `push` or `pull` command + output includes the image digest. You can `pull` using a digest value. You can + also reference by digest in `create`, `run`, and `rmi` commands, as well as the + `FROM` image reference in a Dockerfile. - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--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 filtering flag (`-f` or `--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: + The currently supported filters are: - * dangling (boolean - true or false) - * label (`label=` or `label==`) - * before (`[:]`, `` or ``) - filter images created before given id or references - * since (`[:]`, `` or ``) - filter images created since given id or references - * reference (pattern of an image reference) - filter images whose reference matches the specified pattern + * dangling (boolean - true or false) + * label (`label=` or `label==`) + * before (`[:]`, `` or ``) - filter images created before given id or references + * since (`[:]`, `` or ``) - filter images created since given id or references + * reference (pattern of an image reference) - filter images whose reference matches the specified pattern - #### Show untagged images (dangling) + #### Show untagged images (dangling) - ```console - $ docker images --filter "dangling=true" + ```console + $ docker images --filter "dangling=true" - REPOSITORY TAG IMAGE ID CREATED SIZE - 8abc22fbb042 4 weeks ago 0 B - 48e5f45168b9 4 weeks ago 2.489 MB - bf747efa0e2f 4 weeks ago 0 B - 980fe10e5736 12 weeks ago 101.4 MB - dea752e4e117 12 weeks ago 101.4 MB - 511136ea3c5a 8 months ago 0 B - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + 8abc22fbb042 4 weeks ago 0 B + 48e5f45168b9 4 weeks ago 2.489 MB + bf747efa0e2f 4 weeks ago 0 B + 980fe10e5736 12 weeks ago 101.4 MB + dea752e4e117 12 weeks ago 101.4 MB + 511136ea3c5a 8 months ago 0 B + ``` - This will display untagged images that are the leaves of the images tree (not - intermediary layers). These images occur when a new build of an image takes the - `repo:tag` away from the image ID, leaving it as `:` or untagged. - A warning will be issued if trying to remove an image when a container is presently - using it. By having this flag it allows for batch cleanup. + This will display untagged images that are the leaves of the images tree (not + intermediary layers). These images occur when a new build of an image takes the + `repo:tag` away from the image ID, leaving it as `:` or untagged. + A warning will be issued if trying to remove an image when a container is presently + using it. By having this flag it allows for batch cleanup. - You can use this in conjunction with `docker rmi ...`: + You can use this in conjunction with `docker rmi ...`: - ```console - $ docker rmi $(docker images -f "dangling=true" -q) + ```console + $ docker rmi $(docker images -f "dangling=true" -q) - 8abc22fbb042 - 48e5f45168b9 - bf747efa0e2f - 980fe10e5736 - dea752e4e117 - 511136ea3c5a - ``` + 8abc22fbb042 + 48e5f45168b9 + bf747efa0e2f + 980fe10e5736 + dea752e4e117 + 511136ea3c5a + ``` - Docker warns you if any containers exist that are using these untagged images. + Docker warns you if any containers exist that are using these untagged images. - #### Show images with a given label + #### Show images with a given label - The `label` filter matches images based on the presence of a `label` alone or a `label` and a - value. + The `label` filter matches images based on the presence of a `label` alone or a `label` and a + value. - The following filter matches images with the `com.example.version` label regardless of its value. + The following filter matches images with the `com.example.version` label regardless of its value. - ```console - $ docker images --filter "label=com.example.version" + ```console + $ docker images --filter "label=com.example.version" - REPOSITORY TAG IMAGE ID CREATED SIZE - match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB - match-me-2 latest dea752e4e117 About a minute ago 188.3 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB + match-me-2 latest dea752e4e117 About a minute ago 188.3 MB + ``` - The following filter matches images with the `com.example.version` label with the `1.0` value. + The following filter matches images with the `com.example.version` label with the `1.0` value. - ```console - $ docker images --filter "label=com.example.version=1.0" + ```console + $ docker images --filter "label=com.example.version=1.0" - REPOSITORY TAG IMAGE ID CREATED SIZE - match-me latest 511136ea3c5a About a minute ago 188.3 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + match-me latest 511136ea3c5a About a minute ago 188.3 MB + ``` - In this example, with the `0.1` value, it returns an empty set because no matches were found. + In this example, with the `0.1` value, it returns an empty set because no matches were found. - ```console - $ docker images --filter "label=com.example.version=0.1" - REPOSITORY TAG IMAGE ID CREATED SIZE - ``` + ```console + $ docker images --filter "label=com.example.version=0.1" + REPOSITORY TAG IMAGE ID CREATED SIZE + ``` - #### Filter images by time + #### Filter images by time - The `before` filter shows only images created before the image with - given id or reference. For example, having these images: + The `before` filter shows only images created before the image with + given id or reference. For example, having these images: - ```console - $ docker images + ```console + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - image1 latest eeae25ada2aa 4 minutes ago 188.3 MB - image2 latest dea752e4e117 9 minutes ago 188.3 MB - image3 latest 511136ea3c5a 25 minutes ago 188.3 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + image1 latest eeae25ada2aa 4 minutes ago 188.3 MB + image2 latest dea752e4e117 9 minutes ago 188.3 MB + image3 latest 511136ea3c5a 25 minutes ago 188.3 MB + ``` - Filtering with `before` would give: + Filtering with `before` would give: - ```console - $ docker images --filter "before=image1" + ```console + $ docker images --filter "before=image1" - REPOSITORY TAG IMAGE ID CREATED SIZE - image2 latest dea752e4e117 9 minutes ago 188.3 MB - image3 latest 511136ea3c5a 25 minutes ago 188.3 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + image2 latest dea752e4e117 9 minutes ago 188.3 MB + image3 latest 511136ea3c5a 25 minutes ago 188.3 MB + ``` - Filtering with `since` would give: + Filtering with `since` would give: - ```console - $ docker images --filter "since=image3" - REPOSITORY TAG IMAGE ID CREATED SIZE - image1 latest eeae25ada2aa 4 minutes ago 188.3 MB - image2 latest dea752e4e117 9 minutes ago 188.3 MB - ``` + ```console + $ docker images --filter "since=image3" + REPOSITORY TAG IMAGE ID CREATED SIZE + image1 latest eeae25ada2aa 4 minutes ago 188.3 MB + image2 latest dea752e4e117 9 minutes ago 188.3 MB + ``` - #### Filter images by reference + #### Filter images by reference - The `reference` filter shows only images whose reference matches - the specified pattern. + The `reference` filter shows only images whose reference matches + the specified pattern. - ```console - $ docker images + ```console + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox latest e02e811dd08f 5 weeks ago 1.09 MB - busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB - busybox musl 733eb3059dce 5 weeks ago 1.21 MB - busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox latest e02e811dd08f 5 weeks ago 1.09 MB + busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB + busybox musl 733eb3059dce 5 weeks ago 1.21 MB + busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB + ``` - Filtering with `reference` would give: + Filtering with `reference` would give: - ```console - $ docker images --filter=reference='busy*:*libc' + ```console + $ docker images --filter=reference='busy*:*libc' - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB - busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB + busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB + ``` - Filtering with multiple `reference` would give, either match A or B: + Filtering with multiple `reference` would give, either match A or B: - ```console - $ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc' + ```console + $ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc' - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB - busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB + busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) will pretty print container output - using a Go template. + The formatting option (`--format`) will pretty print container output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |-----------------|------------------------------------------| - | `.ID` | Image ID | - | `.Repository` | Image repository | - | `.Tag` | Image tag | - | `.Digest` | Image digest | - | `.CreatedSince` | Elapsed time since the image was created | - | `.CreatedAt` | Time when the image was created | - | `.Size` | Image disk size | + | Placeholder | Description | + |-----------------|------------------------------------------| + | `.ID` | Image ID | + | `.Repository` | Image repository | + | `.Tag` | Image tag | + | `.Digest` | Image digest | + | `.CreatedSince` | Elapsed time since the image was created | + | `.CreatedAt` | Time when the image was created | + | `.Size` | Image disk size | - When using the `--format` option, the `image` command will either - output the data exactly as the template declares or, when using the - `table` directive, will include column headers as well. + When using the `--format` option, the `image` command will either + output the data exactly as the template declares or, when using the + `table` directive, will include column headers as well. - The following example uses a template without headers and outputs the - `ID` and `Repository` entries separated by a colon (`:`) for all images: - - ```console - $ docker images --format "{{.ID}}: {{.Repository}}" - - 77af4d6b9913: - b6fa739cedf5: committ - 78a85c484f71: - 30557a29d5ab: docker - 5ed6274db6ce: - 746b819f315e: postgres - 746b819f315e: postgres - 746b819f315e: postgres - 746b819f315e: postgres - ``` - - To list all images with their repository and tag in a table format you - can use: - - ```console - $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" - - IMAGE ID REPOSITORY TAG - 77af4d6b9913 - b6fa739cedf5 committ latest - 78a85c484f71 - 30557a29d5ab docker latest - 5ed6274db6ce - 746b819f315e postgres 9 - 746b819f315e postgres 9.3 - 746b819f315e postgres 9.3.5 - 746b819f315e postgres latest - ``` + The following example uses a template without headers and outputs the + `ID` and `Repository` entries separated by a colon (`:`) for all images: + + ```console + $ docker images --format "{{.ID}}: {{.Repository}}" + + 77af4d6b9913: + b6fa739cedf5: committ + 78a85c484f71: + 30557a29d5ab: docker + 5ed6274db6ce: + 746b819f315e: postgres + 746b819f315e: postgres + 746b819f315e: postgres + 746b819f315e: postgres + ``` + + To list all images with their repository and tag in a table format you + can use: + + ```console + $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" + + IMAGE ID REPOSITORY TAG + 77af4d6b9913 + b6fa739cedf5 committ latest + 78a85c484f71 + 30557a29d5ab docker latest + 5ed6274db6ce + 746b819f315e postgres 9 + 746b819f315e postgres 9.3 + 746b819f315e postgres 9.3.5 + 746b819f315e postgres latest + ``` + + To list all images in JSON format, use the `json` directive: + + ```console + $ docker images --format json + {"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"72.9MB"} + {"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"5.613MB"} + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_import.yaml b/_data/engine-cli/docker_import.yaml index 69be47d194..80a14c4f9a 100644 --- a/_data/engine-cli/docker_import.yaml +++ b/_data/engine-cli/docker_import.yaml @@ -1,93 +1,108 @@ command: docker import +aliases: docker image import, docker import short: Import the contents from a tarball to create a filesystem image long: |- - You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The - `URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) - containing a filesystem or to an individual file on the Docker host. If you - specify an archive, Docker untars it in the container relative to the `/` - (root). If you specify an individual file, you must specify the full path within - the host. To import from a remote location, specify a `URI` that begins with the - `http://` or `https://` protocol. + You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The + `URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) + containing a filesystem or to an individual file on the Docker host. If you + specify an archive, Docker untars it in the container relative to the `/` + (root). If you specify an individual file, you must specify the full path within + the host. To import from a remote location, specify a `URI` that begins with the + `http://` or `https://` protocol. - The `--change` option applies `Dockerfile` instructions to the image that is - created. Supported `Dockerfile` instructions: - `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` + The `--change` option applies `Dockerfile` instructions to the image that is + created. Supported `Dockerfile` instructions: + `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` usage: docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]] pname: docker plink: docker.yaml options: -- option: change - shorthand: c - value_type: list - description: Apply Dockerfile instruction to the created image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: message - shorthand: m - value_type: string - description: Set commit message for imported image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: change + shorthand: c + value_type: list + description: Apply Dockerfile instruction to the created image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: message + shorthand: m + value_type: string + description: Set commit message for imported image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Import from a remote location + ### Import from a remote location - This creates a new untagged image. + This creates a new untagged image. - ```console - $ docker import https://example.com/exampleimage.tgz - ``` + ```console + $ docker import https://example.com/exampleimage.tgz + ``` - ### Import from a local file + ### Import from a local file - Import to docker via pipe and `STDIN`. + Import to docker via pipe and `STDIN`. - ```console - $ cat exampleimage.tgz | docker import - exampleimagelocal:new - ``` + ```console + $ cat exampleimage.tgz | docker import - exampleimagelocal:new + ``` - Import with a commit message. + Import with a commit message. - ```console - $ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new - ``` + ```console + $ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new + ``` - Import to docker from a local archive. + Import to docker from a local archive. - ```console - $ docker import /path/to/exampleimage.tgz - ``` + ```console + $ docker import /path/to/exampleimage.tgz + ``` - ### Import from a local directory + ### Import from a local directory - ```console - $ sudo tar -c . | docker import - exampleimagedir - ``` + ```console + $ sudo tar -c . | docker import - exampleimagedir + ``` - ### Import from a local directory with new configurations + ### Import from a local directory with new configurations - ```console - $ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir - ``` + ```console + $ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir + ``` - Note the `sudo` in this example – you must preserve - the ownership of the files (especially root ownership) during the - archiving with tar. If you are not root (or the sudo command) when you - tar, then the ownerships might not get preserved. + Note the `sudo` in this example – you must preserve + the ownership of the files (especially root ownership) during the + archiving with tar. If you are not root (or the sudo command) when you + tar, then the ownerships might not get preserved. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_info.yaml b/_data/engine-cli/docker_info.yaml index 7ba2f05360..4a105cf135 100644 --- a/_data/engine-cli/docker_info.yaml +++ b/_data/engine-cli/docker_info.yaml @@ -1,171 +1,185 @@ command: docker info +aliases: docker system info, docker info short: Display system-wide information long: |- - This command displays system wide information regarding the Docker installation. - Information displayed includes the kernel version, number of containers and images. - The number of images shown is the number of unique images. The same image tagged - under different names is counted only once. + This command displays system wide information regarding the Docker installation. + Information displayed includes the kernel version, number of containers and images. + The number of images shown is the number of unique images. The same image tagged + under different names is counted only once. - If a format is specified, the given template will be executed instead of the - default format. Go's [text/template](https://golang.org/pkg/text/template/) package - describes all the details of the format. + If a format is specified, the given template will be executed instead of the + default format. Go's [text/template](https://golang.org/pkg/text/template/) package + describes all the details of the format. - Depending on the storage driver in use, additional information can be shown, such - as pool name, data file, metadata file, data space used, total data space, metadata - space used, and total metadata space. + Depending on the storage driver in use, additional information can be shown, such + as pool name, data file, metadata file, data space used, total data space, metadata + space used, and total metadata space. - The data file is where the images are stored and the metadata file is where the - meta data regarding those images are stored. When run for the first time Docker - allocates a certain amount of data space and meta data space from the space - available on the volume where `/var/lib/docker` is mounted. + The data file is where the images are stored and the metadata file is where the + meta data regarding those images are stored. When run for the first time Docker + allocates a certain amount of data space and meta data space from the space + available on the volume where `/var/lib/docker` is mounted. usage: docker info [OPTIONS] pname: docker plink: docker.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: Format the output using the given Go template + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Show output + ### Show output - The example below shows the output for a daemon running on Ubuntu Linux, - using the `overlay2` storage driver. As can be seen in the output, additional - information about the `overlay2` storage driver is shown: + The example below shows the output for a daemon running on Ubuntu Linux, + using the `overlay2` storage driver. As can be seen in the output, additional + information about the `overlay2` storage driver is shown: - ```console - $ docker info + ```console + $ docker info - Client: - Context: default - Debug Mode: false - Plugins: - buildx: Docker Buildx (Docker Inc.) - Version: v0.8.2 - Path: /usr/libexec/docker/cli-plugins/docker-buildx - compose: Docker Compose (Docker Inc.) - Version: v2.6.0 - Path: /usr/libexec/docker/cli-plugins/docker-compose - scan: Docker Scan (Docker Inc.) - Version: v0.17.0 - Path: /usr/libexec/docker/cli-plugins/docker-scan + Client: + Context: default + Debug Mode: false + Plugins: + buildx: Docker Buildx (Docker Inc.) + Version: v0.8.2 + Path: /usr/libexec/docker/cli-plugins/docker-buildx + compose: Docker Compose (Docker Inc.) + Version: v2.6.0 + Path: /usr/libexec/docker/cli-plugins/docker-compose + scan: Docker Scan (Docker Inc.) + Version: v0.17.0 + Path: /usr/libexec/docker/cli-plugins/docker-scan - Server: - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 22.06.0 - Storage Driver: overlay2 - Backing Filesystem: extfs - Supports d_type: true - Using metacopy: false - Native Overlay Diff: true - userxattr: false - Logging Driver: json-file - Cgroup Driver: systemd - Cgroup Version: 2 - Plugins: - Volume: local - Network: bridge host ipvlan macvlan null overlay - Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog - Swarm: inactive - Runtimes: io.containerd.runc.v2 io.containerd.runtime.v1.linux runc - Default Runtime: runc - Init Binary: docker-init - containerd version: 212e8b6fa2f44b9c21b2798135fc6fb7c53efc16 - runc version: v1.1.1-0-g52de29d - init version: de40ad0 - Security Options: - apparmor - seccomp - Profile: builtin - cgroupns - Kernel Version: 5.15.0-25-generic - Operating System: Ubuntu 22.04 LTS - OSType: linux - Architecture: x86_64 - CPUs: 1 - Total Memory: 991.7 MiB - Name: ip-172-30-0-91.ec2.internal - ID: 4cee4408-10d2-4e17-891c-a41736ac4536 - Docker Root Dir: /var/lib/docker - Debug Mode: false - Username: gordontheturtle - Registry: https://index.docker.io/v1/ - Experimental: false - Insecure registries: - myinsecurehost:5000 - 127.0.0.0/8 - Live Restore Enabled: false - ``` + Server: + Containers: 14 + Running: 3 + Paused: 1 + Stopped: 10 + Images: 52 + Server Version: 22.06.0 + Storage Driver: overlay2 + Backing Filesystem: extfs + Supports d_type: true + Using metacopy: false + Native Overlay Diff: true + userxattr: false + Logging Driver: json-file + Cgroup Driver: systemd + Cgroup Version: 2 + Plugins: + Volume: local + Network: bridge host ipvlan macvlan null overlay + Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog + Swarm: inactive + Runtimes: io.containerd.runc.v2 io.containerd.runtime.v1.linux runc + Default Runtime: runc + Init Binary: docker-init + containerd version: 212e8b6fa2f44b9c21b2798135fc6fb7c53efc16 + runc version: v1.1.1-0-g52de29d + init version: de40ad0 + Security Options: + apparmor + seccomp + Profile: builtin + cgroupns + Kernel Version: 5.15.0-25-generic + Operating System: Ubuntu 22.04 LTS + OSType: linux + Architecture: x86_64 + CPUs: 1 + Total Memory: 991.7 MiB + Name: ip-172-30-0-91.ec2.internal + ID: 4cee4408-10d2-4e17-891c-a41736ac4536 + Docker Root Dir: /var/lib/docker + Debug Mode: false + Username: gordontheturtle + Registry: https://index.docker.io/v1/ + Experimental: false + Insecure registries: + myinsecurehost:5000 + 127.0.0.0/8 + Live Restore Enabled: false + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - You can also specify the output format: + You can also specify the output format: - ```console - $ docker info --format '{{json .}}' + ```console + $ docker info --format '{{json .}}' - {"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} - ``` + {"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} + ``` - ### Run `docker info` on Windows + ### Run `docker info` on Windows - Here is a sample output for a daemon running on Windows Server: + Here is a sample output for a daemon running on Windows Server: - ```console - C:\> docker info + ```console + C:\> docker info - Client: - Context: default - Debug Mode: false - Plugins: - buildx: Docker Buildx (Docker Inc., v0.8.2-docker) - compose: Docker Compose (Docker Inc., v2.6.0) - scan: Docker Scan (Docker Inc., v0.17.0) + Client: + Context: default + Debug Mode: false + Plugins: + buildx: Docker Buildx (Docker Inc., v0.8.2-docker) + compose: Docker Compose (Docker Inc., v2.6.0) + scan: Docker Scan (Docker Inc., v0.17.0) - Server: - Containers: 1 - Running: 0 - Paused: 0 - Stopped: 1 - Images: 17 - Server Version: 20.10.16 - Storage Driver: windowsfilter - Logging Driver: json-file - Plugins: - Volume: local - Network: ics internal l2bridge l2tunnel nat null overlay private transparent - Log: awslogs etwlogs fluentd gcplogs gelf json-file local logentries splunk syslog - Swarm: inactive - Default Isolation: process - Kernel Version: 10.0 20348 (20348.1.amd64fre.fe_release.210507-1500) - Operating System: Microsoft Windows Server Version 21H2 (OS Build 20348.707) - OSType: windows - Architecture: x86_64 - CPUs: 8 - Total Memory: 3.999 GiB - Name: WIN-V0V70C0LU5P - ID: 2880d38d-464e-4d01-91bd-c76f33ba3981 - Docker Root Dir: C:\ProgramData\docker - Debug Mode: false - Registry: https://index.docker.io/v1/ - Experimental: true - Insecure Registries: - myregistry:5000 - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ - Live Restore Enabled: false - ``` + Server: + Containers: 1 + Running: 0 + Paused: 0 + Stopped: 1 + Images: 17 + Server Version: 20.10.16 + Storage Driver: windowsfilter + Logging Driver: json-file + Plugins: + Volume: local + Network: ics internal l2bridge l2tunnel nat null overlay private transparent + Log: awslogs etwlogs fluentd gcplogs gelf json-file local logentries splunk syslog + Swarm: inactive + Default Isolation: process + Kernel Version: 10.0 20348 (20348.1.amd64fre.fe_release.210507-1500) + Operating System: Microsoft Windows Server Version 21H2 (OS Build 20348.707) + OSType: windows + Architecture: x86_64 + CPUs: 8 + Total Memory: 3.999 GiB + Name: WIN-V0V70C0LU5P + ID: 2880d38d-464e-4d01-91bd-c76f33ba3981 + Docker Root Dir: C:\ProgramData\docker + Debug Mode: false + Registry: https://index.docker.io/v1/ + Experimental: true + Insecure Registries: + myregistry:5000 + 127.0.0.0/8 + Registry Mirrors: + http://192.168.1.2/ + http://registry-mirror.example.com:5000/ + Live Restore Enabled: false + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_inspect.yaml b/_data/engine-cli/docker_inspect.yaml index 1415805542..c33a219573 100644 --- a/_data/engine-cli/docker_inspect.yaml +++ b/_data/engine-cli/docker_inspect.yaml @@ -1,151 +1,169 @@ command: docker inspect short: Return low-level information on Docker objects long: |- - Docker inspect provides detailed information on constructs controlled by Docker. + Docker inspect provides detailed information on constructs controlled by Docker. - By default, `docker inspect` will render results in a JSON array. + By default, `docker inspect` will render results in a JSON array. - ### Format the output (--format) + ### Format the output (--format) {#format} - If a format is specified, the given template will be executed for each result. + If a format is specified, the given template will be executed for each result. - Go's [text/template](https://golang.org/pkg/text/template/) package describes - all the details of the format. + Go's [text/template](https://golang.org/pkg/text/template/) package describes + all the details of the format. - ### Specify target type (--type) + ### Specify target type (--type) {#type} - `--type container|image|node|network|secret|service|volume|task|plugin` + `--type container|image|node|network|secret|service|volume|task|plugin` - The `docker inspect` command matches any type of object by either ID or name. In - some cases multiple type of objects (for example, a container and a volume) - exist with the same name, making the result ambiguous. + The `docker inspect` command matches any type of object by either ID or name. In + some cases multiple type of objects (for example, a container and a volume) + exist with the same name, making the result ambiguous. - To restrict `docker inspect` to a specific type of object, use the `--type` - option. + To restrict `docker inspect` to a specific type of object, use the `--type` + option. - The following example inspects a _volume_ named "myvolume" + The following example inspects a _volume_ named "myvolume" - ```console - $ docker inspect --type=volume myvolume - ``` + ```console + $ docker inspect --type=volume myvolume + ``` - ### Inspect the size of a container (-s, --size) + ### Inspect the size of a container (-s, --size) {#size} - The `--size`, or short-form `-s`, option adds two additional fields to the - `docker inspect` output. This option only works for containers. The container - doesn't have to be running, it also works for stopped containers. + The `--size`, or short-form `-s`, option adds two additional fields to the + `docker inspect` output. This option only works for containers. The container + doesn't have to be running, it also works for stopped containers. - ```console - $ docker inspect --size mycontainer - ``` + ```console + $ docker inspect --size mycontainer + ``` - The output includes the full output of a regular `docker inspect` command, with - the following additional fields: + The output includes the full output of a regular `docker inspect` command, with + the following additional fields: - - `SizeRootFs`: the total size of all the files in the container, in bytes. - - `SizeRw`: the size of the files that have been created or changed in the - container, compared to it's image, in bytes. + - `SizeRootFs`: the total size of all the files in the container, in bytes. + - `SizeRw`: the size of the files that have been created or changed in the + container, compared to it's image, in bytes. - ```console - $ docker run --name database -d redis - 3b2cbf074c99db4a0cad35966a9e24d7bc277f5565c17233386589029b7db273 - $ docker inspect --size database -f '{{ .SizeRootFs }}' - 123125760 - $ docker inspect --size database -f '{{ .SizeRw }}' - 8192 - $ docker exec database fallocate -l 1000 /newfile - $ docker inspect --size database -f '{{ .SizeRw }}' - 12288 - ``` + ```console + $ docker run --name database -d redis + 3b2cbf074c99db4a0cad35966a9e24d7bc277f5565c17233386589029b7db273 + $ docker inspect --size database -f '{{ .SizeRootFs }}' + 123125760 + $ docker inspect --size database -f '{{ .SizeRw }}' + 8192 + $ docker exec database fallocate -l 1000 /newfile + $ docker inspect --size database -f '{{ .SizeRw }}' + 12288 + ``` usage: docker inspect [OPTIONS] NAME|ID [NAME|ID...] pname: docker plink: docker.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: size - shorthand: s - value_type: bool - default_value: "false" - description: Display total file sizes if the type is container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: type - value_type: string - description: Return JSON for specified type - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: size + shorthand: s + value_type: bool + default_value: "false" + description: Display total file sizes if the type is container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: type + value_type: string + description: Return JSON for specified type + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Get an instance's IP address + ### Get an instance's IP address - For the most part, you can pick out any field from the JSON in a fairly - straightforward manner. + For the most part, you can pick out any field from the JSON in a fairly + straightforward manner. - ```console - $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID - ``` + ```console + $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID + ``` - ### Get an instance's MAC address + ### Get an instance's MAC address - ```console - $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID - ``` + ```console + $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID + ``` - ### Get an instance's log path + ### Get an instance's log path - ```console - $ docker inspect --format='{{.LogPath}}' $INSTANCE_ID - ``` + ```console + $ docker inspect --format='{{.LogPath}}' $INSTANCE_ID + ``` - ### Get an instance's image name + ### Get an instance's image name - ```console - $ docker inspect --format='{{.Config.Image}}' $INSTANCE_ID - ``` + ```console + $ docker inspect --format='{{.Config.Image}}' $INSTANCE_ID + ``` - ### List all port bindings + ### List all port bindings - You can loop over arrays and maps in the results to produce simple text output: + You can loop over arrays and maps in the results to produce simple text output: - ```console - $ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID - ``` + ```console + $ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID + ``` - ### Find a specific port mapping + ### Find a specific port mapping - The `.Field` syntax doesn't work when the field name begins with a number, but - the template language's `index` function does. The `.NetworkSettings.Ports` - section contains a map of the internal port mappings to a list of external - address/port objects. To grab just the numeric public port, you use `index` to - find the specific port map, and then `index` 0 contains the first object inside - of that. Then we ask for the `HostPort` field to get the public address. + The `.Field` syntax doesn't work when the field name begins with a number, but + the template language's `index` function does. The `.NetworkSettings.Ports` + section contains a map of the internal port mappings to a list of external + address/port objects. To grab just the numeric public port, you use `index` to + find the specific port map, and then `index` 0 contains the first object inside + of that. Then we ask for the `HostPort` field to get the public address. - ```console - $ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID - ``` + ```console + $ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID + ``` - ### Get a subsection in JSON format + ### Get a subsection in JSON format - If you request a field which is itself a structure containing other fields, by - default you get a Go-style dump of the inner values. Docker adds a template - function, `json`, which can be applied to get results in JSON format. + If you request a field which is itself a structure containing other fields, by + default you get a Go-style dump of the inner values. Docker adds a template + function, `json`, which can be applied to get results in JSON format. - ```console - $ docker inspect --format='{{json .Config}}' $INSTANCE_ID - ``` + ```console + $ docker inspect --format='{{json .Config}}' $INSTANCE_ID + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_kill.yaml b/_data/engine-cli/docker_kill.yaml index 6cda0bd0b3..627d1cfdad 100644 --- a/_data/engine-cli/docker_kill.yaml +++ b/_data/engine-cli/docker_kill.yaml @@ -1,71 +1,84 @@ command: docker kill +aliases: docker container kill, docker kill short: Kill one or more running containers long: |- - The `docker kill` subcommand kills one or more containers. The main process - inside the container is sent `SIGKILL` signal (default), or the signal that is - specified with the `--signal` option. You can reference a container by its - ID, ID-prefix, or name. + The `docker kill` subcommand kills one or more containers. The main process + inside the container is sent `SIGKILL` signal (default), or the signal that is + specified with the `--signal` option. You can reference a container by its + ID, ID-prefix, or name. - The `--signal` (or `-s` shorthand) flag sets the system call signal that is sent - to the container. This signal can be a signal name in the format `SIG`, for - instance `SIGINT`, or an unsigned number that matches a position in the kernel's - syscall table, for instance `2`. + The `--signal` flag sets the system call signal that is sent to the container. + This signal can be a signal name in the format `SIG`, for instance `SIGINT`, + or an unsigned number that matches a position in the kernel's syscall table, + for instance `2`. - While the default (`SIGKILL`) signal will terminate the container, the signal - set through `--signal` may be non-terminal, depending on the container's main - process. For example, the `SIGHUP` signal in most cases will be non-terminal, - and the container will continue running after receiving the signal. + While the default (`SIGKILL`) signal will terminate the container, the signal + set through `--signal` may be non-terminal, depending on the container's main + process. For example, the `SIGHUP` signal in most cases will be non-terminal, + and the container will continue running after receiving the signal. - > **Note** - > - > `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of - > `/bin/sh -c`, which does not pass signals. This means that the executable is - > not the container’s PID 1 and does not receive Unix signals. + > **Note** + > + > `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of + > `/bin/sh -c`, which does not pass signals. This means that the executable is + > not the container’s PID 1 and does not receive Unix signals. usage: docker kill [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml options: -- option: signal - shorthand: s - value_type: string - default_value: KILL - description: Signal to send to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: signal + shorthand: s + value_type: string + description: Signal to send to the container + details_url: '#signal' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Send a KILL signal to a container + ### Send a KILL signal to a container - The following example sends the default `SIGKILL` signal to the container named - `my_container`: + The following example sends the default `SIGKILL` signal to the container named + `my_container`: - ```console - $ docker kill my_container - ``` + ```console + $ docker kill my_container + ``` - ### Send a custom signal to a container (--signal) + ### Send a custom signal to a container (--signal) {#signal} - The following example sends a `SIGHUP` signal to the container named - `my_container`: + The following example sends a `SIGHUP` signal to the container named + `my_container`: - ```console - $ docker kill --signal=SIGHUP my_container - ``` + ```console + $ docker kill --signal=SIGHUP my_container + ``` - You can specify a custom signal either by _name_, or _number_. The `SIG` prefix - is optional, so the following examples are equivalent: + You can specify a custom signal either by _name_, or _number_. The `SIG` prefix + is optional, so the following examples are equivalent: - ```console - $ docker kill --signal=SIGHUP my_container - $ docker kill --signal=HUP my_container - $ docker kill --signal=1 my_container - ``` + ```console + $ docker kill --signal=SIGHUP my_container + $ docker kill --signal=HUP my_container + $ docker kill --signal=1 my_container + ``` - Refer to the [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html) - man-page for a list of standard Linux signals. + Refer to the [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html) + man-page for a list of standard Linux signals. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_load.yaml b/_data/engine-cli/docker_load.yaml index e29ed84a0b..a64df8e0bf 100644 --- a/_data/engine-cli/docker_load.yaml +++ b/_data/engine-cli/docker_load.yaml @@ -1,66 +1,81 @@ command: docker load +aliases: docker image load, docker load short: Load an image from a tar archive or STDIN long: |- - Load an image or repository from a tar archive (even if compressed with gzip, - bzip2, or xz) from a file or STDIN. It restores both images and tags. + Load an image or repository from a tar archive (even if compressed with gzip, + bzip2, or xz) from a file or STDIN. It restores both images and tags. usage: docker load [OPTIONS] pname: docker plink: docker.yaml options: -- option: input - shorthand: i - value_type: string - description: Read from tar archive file, instead of STDIN - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress the load output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: input + shorthand: i + value_type: string + description: Read from tar archive file, instead of STDIN + details_url: '#input' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the load output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker image ls + ```console + $ docker image ls - REPOSITORY TAG IMAGE ID CREATED SIZE - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + ``` - ### Load images from STDIN + ### Load images from STDIN - ```console - $ docker load < busybox.tar.gz + ```console + $ docker load < busybox.tar.gz - Loaded image: busybox:latest - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox latest 769b9341d937 7 weeks ago 2.489 MB - ``` + Loaded image: busybox:latest + $ docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox latest 769b9341d937 7 weeks ago 2.489 MB + ``` - ### Load images from a file (--input) + ### Load images from a file (--input) {#input} - ```console - $ docker load --input fedora.tar + ```console + $ docker load --input fedora.tar - Loaded image: fedora:rawhide - Loaded image: fedora:20 + Loaded image: fedora:rawhide + Loaded image: fedora:20 - $ docker images + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox latest 769b9341d937 7 weeks ago 2.489 MB - fedora rawhide 0d20aec6529d 7 weeks ago 387 MB - fedora 20 58394af37342 7 weeks ago 385.5 MB - fedora heisenbug 58394af37342 7 weeks ago 385.5 MB - fedora latest 58394af37342 7 weeks ago 385.5 MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox latest 769b9341d937 7 weeks ago 2.489 MB + fedora rawhide 0d20aec6529d 7 weeks ago 387 MB + fedora 20 58394af37342 7 weeks ago 385.5 MB + fedora heisenbug 58394af37342 7 weeks ago 385.5 MB + fedora latest 58394af37342 7 weeks ago 385.5 MB + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_login.yaml b/_data/engine-cli/docker_login.yaml index ac6593d520..4f597ef3ce 100644 --- a/_data/engine-cli/docker_login.yaml +++ b/_data/engine-cli/docker_login.yaml @@ -1,190 +1,205 @@ command: docker login -short: Log in to a Docker registry +short: Log in to a registry long: Login to a registry. usage: docker login [OPTIONS] [SERVER] pname: docker plink: docker.yaml options: -- option: password - shorthand: p - value_type: string - description: Password - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: password-stdin - value_type: bool - default_value: "false" - description: Take the password from stdin - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: username - shorthand: u - value_type: string - description: Username - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: password + shorthand: p + value_type: string + description: Password + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: password-stdin + value_type: bool + default_value: "false" + description: Take the password from stdin + details_url: '#password-stdin' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: username + shorthand: u + value_type: string + description: Username + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Login to a self-hosted registry + ### Login to a self-hosted registry - If you want to login to a self-hosted registry you can specify this by - adding the server name. + If you want to login to a self-hosted registry you can specify this by + adding the server name. - ```console - $ docker login localhost:8080 - ``` + ```console + $ docker login localhost:8080 + ``` - ### Provide a password using STDIN (--password-stdin) + ### Provide a password using STDIN (--password-stdin) {#password-stdin} - To run the `docker login` command non-interactively, you can set the - `--password-stdin` flag to provide a password through `STDIN`. Using - `STDIN` prevents the password from ending up in the shell's history, - or log-files. + To run the `docker login` command non-interactively, you can set the + `--password-stdin` flag to provide a password through `STDIN`. Using + `STDIN` prevents the password from ending up in the shell's history, + or log-files. - The following example reads a password from a file, and passes it to the - `docker login` command using `STDIN`: + The following example reads a password from a file, and passes it to the + `docker login` command using `STDIN`: - ```console - $ cat ~/my_password.txt | docker login --username foo --password-stdin - ``` + ```console + $ cat ~/my_password.txt | docker login --username foo --password-stdin + ``` - ### Privileged user requirement + ### Privileged user requirement - `docker login` requires user to use `sudo` or be `root`, except when: + `docker login` requires user to use `sudo` or be `root`, except when: - 1. connecting to a remote daemon, such as a `docker-machine` provisioned `docker engine`. - 2. user is added to the `docker` group. This will impact the security of your system; the `docker` group is `root` equivalent. See [Docker Daemon Attack Surface](https://docs.docker.com/engine/security/#docker-daemon-attack-surface) for details. + 1. connecting to a remote daemon, such as a `docker-machine` provisioned `docker engine`. + 2. user is added to the `docker` group. This will impact the security of your system; the `docker` group is `root` equivalent. See [Docker Daemon Attack Surface](/engine/security/#docker-daemon-attack-surface) for details. - You can log into any public or private repository for which you have - credentials. When you log in, the command stores credentials in - `$HOME/.docker/config.json` on Linux or `%USERPROFILE%/.docker/config.json` on - Windows, via the procedure described below. + You can log into any public or private repository for which you have + credentials. When you log in, the command stores credentials in + `$HOME/.docker/config.json` on Linux or `%USERPROFILE%/.docker/config.json` on + Windows, via the procedure described below. - ### Credentials store + ### Credentials store - The Docker Engine can keep user credentials in an external credentials store, - such as the native keychain of the operating system. Using an external store - is more secure than storing credentials in the Docker configuration file. + The Docker Engine can keep user credentials in an external credentials store, + such as the native keychain of the operating system. Using an external store + is more secure than storing credentials in the Docker configuration file. - To use a credentials store, you need an external helper program to interact - with a specific keychain or external store. Docker requires the helper - program to be in the client's host `$PATH`. + To use a credentials store, you need an external helper program to interact + with a specific keychain or external store. Docker requires the helper + program to be in the client's host `$PATH`. - This is the list of currently available credentials helpers and where - you can download them from: + This is the list of currently available credentials helpers and where + you can download them from: - - D-Bus Secret Service: https://github.com/docker/docker-credential-helpers/releases - - Apple macOS keychain: https://github.com/docker/docker-credential-helpers/releases - - Microsoft Windows Credential Manager: https://github.com/docker/docker-credential-helpers/releases - - [pass](https://www.passwordstore.org/): https://github.com/docker/docker-credential-helpers/releases + - D-Bus Secret Service: https://github.com/docker/docker-credential-helpers/releases + - Apple macOS keychain: https://github.com/docker/docker-credential-helpers/releases + - Microsoft Windows Credential Manager: https://github.com/docker/docker-credential-helpers/releases + - [pass](https://www.passwordstore.org/): https://github.com/docker/docker-credential-helpers/releases - #### Configure the credentials store + #### Configure the credentials store - You need to specify the credentials store in `$HOME/.docker/config.json` - to tell the docker engine to use it. The value of the config property should be - the suffix of the program to use (i.e. everything after `docker-credential-`). - For example, to use `docker-credential-osxkeychain`: + You need to specify the credentials store in `$HOME/.docker/config.json` + to tell the docker engine to use it. The value of the config property should be + the suffix of the program to use (i.e. everything after `docker-credential-`). + For example, to use `docker-credential-osxkeychain`: - ```json - { - "credsStore": "osxkeychain" - } - ``` - - If you are currently logged in, run `docker logout` to remove - the credentials from the file and run `docker login` again. - - #### Default behavior - - By default, Docker looks for the native binary on each of the platforms, i.e. - "osxkeychain" on macOS, "wincred" on windows, and "pass" on Linux. A special - case is that on Linux, Docker will fall back to the "secretservice" binary if - it cannot find the "pass" binary. If none of these binaries are present, it - stores the credentials (i.e. password) in base64 encoding in the config files - described above. - - #### Credential helper protocol - - Credential helpers can be any program or script that follows a very simple protocol. - This protocol is heavily inspired by Git, but it differs in the information shared. - - The helpers always use the first argument in the command to identify the action. - There are only three possible values for that argument: `store`, `get`, and `erase`. - - The `store` command takes a JSON payload from the standard input. That payload carries - the server address, to identify the credential, the user name, and either a password - or an identity token. - - ```json - { - "ServerURL": "https://index.docker.io/v1", - "Username": "david", - "Secret": "passw0rd1" - } - ``` - - If the secret being stored is an identity token, the Username should be set to - ``. - - The `store` command can write error messages to `STDOUT` that the docker engine - will show if there was an issue. - - The `get` command takes a string payload from the standard input. That payload carries - the server address that the docker engine needs credentials for. This is - an example of that payload: `https://index.docker.io/v1`. - - The `get` command writes a JSON payload to `STDOUT`. Docker reads the user name - and password from this payload: - - ```json - { - "Username": "david", - "Secret": "passw0rd1" - } - ``` - - The `erase` command takes a string payload from `STDIN`. That payload carries - the server address that the docker engine wants to remove credentials for. This is - an example of that payload: `https://index.docker.io/v1`. - - The `erase` command can write error messages to `STDOUT` that the docker engine - will show if there was an issue. - - ### Credential helpers - - Credential helpers are similar to the credential store above, but act as the - designated programs to handle credentials for *specific registries*. The default - credential store (`credsStore` or the config file itself) will not be used for - operations concerning credentials of the specified registries. - - #### Configure credential helpers - - If you are currently logged in, run `docker logout` to remove - the credentials from the default store. - - Credential helpers are specified in a similar way to `credsStore`, but - allow for multiple helpers to be configured at a time. Keys specify the - registry domain, and values specify the suffix of the program to use - (i.e. everything after `docker-credential-`). - For example: - - ```json - { - "credHelpers": { - "registry.example.com": "registryhelper", - "awesomereg.example.org": "hip-star", - "unicorn.example.io": "vcbait" + ```json + { + "credsStore": "osxkeychain" } - } - ``` + ``` + + If you are currently logged in, run `docker logout` to remove + the credentials from the file and run `docker login` again. + + #### Default behavior + + By default, Docker looks for the native binary on each of the platforms, i.e. + "osxkeychain" on macOS, "wincred" on windows, and "pass" on Linux. A special + case is that on Linux, Docker will fall back to the "secretservice" binary if + it cannot find the "pass" binary. If none of these binaries are present, it + stores the credentials (i.e. password) in base64 encoding in the config files + described above. + + #### Credential helper protocol + + Credential helpers can be any program or script that follows a very simple protocol. + This protocol is heavily inspired by Git, but it differs in the information shared. + + The helpers always use the first argument in the command to identify the action. + There are only three possible values for that argument: `store`, `get`, and `erase`. + + The `store` command takes a JSON payload from the standard input. That payload carries + the server address, to identify the credential, the user name, and either a password + or an identity token. + + ```json + { + "ServerURL": "https://index.docker.io/v1", + "Username": "david", + "Secret": "passw0rd1" + } + ``` + + If the secret being stored is an identity token, the Username should be set to + ``. + + The `store` command can write error messages to `STDOUT` that the docker engine + will show if there was an issue. + + The `get` command takes a string payload from the standard input. That payload carries + the server address that the docker engine needs credentials for. This is + an example of that payload: `https://index.docker.io/v1`. + + The `get` command writes a JSON payload to `STDOUT`. Docker reads the user name + and password from this payload: + + ```json + { + "Username": "david", + "Secret": "passw0rd1" + } + ``` + + The `erase` command takes a string payload from `STDIN`. That payload carries + the server address that the docker engine wants to remove credentials for. This is + an example of that payload: `https://index.docker.io/v1`. + + The `erase` command can write error messages to `STDOUT` that the docker engine + will show if there was an issue. + + ### Credential helpers + + Credential helpers are similar to the credential store above, but act as the + designated programs to handle credentials for *specific registries*. The default + credential store (`credsStore` or the config file itself) will not be used for + operations concerning credentials of the specified registries. + + #### Configure credential helpers + + If you are currently logged in, run `docker logout` to remove + the credentials from the default store. + + Credential helpers are specified in a similar way to `credsStore`, but + allow for multiple helpers to be configured at a time. Keys specify the + registry domain, and values specify the suffix of the program to use + (i.e. everything after `docker-credential-`). + For example: + + ```json + { + "credHelpers": { + "registry.example.com": "registryhelper", + "awesomereg.example.org": "hip-star", + "unicorn.example.io": "vcbait" + } + } + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_logout.yaml b/_data/engine-cli/docker_logout.yaml index 2f52a0816f..e8394f8ede 100644 --- a/_data/engine-cli/docker_logout.yaml +++ b/_data/engine-cli/docker_logout.yaml @@ -1,13 +1,26 @@ command: docker logout -short: Log out from a Docker registry -long: Log out from a Docker registry +short: Log out from a registry +long: |- + Log out from a registry. + If no server is specified, the default is defined by the daemon. usage: docker logout [SERVER] pname: docker plink: docker.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker logout localhost:8080 - ``` + ```console + $ docker logout localhost:8080 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_logs.yaml b/_data/engine-cli/docker_logs.yaml index 64158a28f7..320f0fe4de 100644 --- a/_data/engine-cli/docker_logs.yaml +++ b/_data/engine-cli/docker_logs.yaml @@ -1,114 +1,133 @@ command: docker logs +aliases: docker container logs, docker logs short: Fetch the logs of a container long: |- - The `docker logs` command batch-retrieves logs present at the time of execution. + The `docker logs` command batch-retrieves logs present at the time of execution. - For more information about selecting and configuring logging drivers, refer to - [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). + For more information about selecting and configuring logging drivers, refer to + [Configure logging drivers](/config/containers/logging/configure/). - The `docker logs --follow` command will continue streaming the new output from - the container's `STDOUT` and `STDERR`. + The `docker logs --follow` command will continue streaming the new output from + the container's `STDOUT` and `STDERR`. - Passing a negative number or a non-integer to `--tail` is invalid and the - value is set to `all` in that case. + Passing a negative number or a non-integer to `--tail` is invalid and the + value is set to `all` in that case. - The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants) - , for example `2014-09-16T06:17:46.000000000Z`, to each - log entry. To ensure that the timestamps are aligned the - nano-second part of the timestamp will be padded with zero when necessary. + The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants) + , for example `2014-09-16T06:17:46.000000000Z`, to each + log entry. To ensure that the timestamps are aligned the + nano-second part of the timestamp will be padded with zero when necessary. - The `docker logs --details` command will add on extra attributes, such as - environment variables and labels, provided to `--log-opt` when creating the - container. + The `docker logs --details` command will add on extra attributes, such as + environment variables and labels, provided to `--log-opt` when creating the + container. - The `--since` option shows only the container logs generated after - a given date. You can specify the date as an RFC 3339 date, a UNIX - timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date - format you may also use RFC3339Nano, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local - timezone on the client will be used if you do not provide either a `Z` or a - `+-00:00` timezone offset at the end of the timestamp. When providing Unix - timestamps enter seconds[.nanoseconds], where seconds is the number of seconds - that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap - seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a - fraction of a second no more than nine digits long. You can combine the - `--since` option with either or both of the `--follow` or `--tail` options. + The `--since` option shows only the container logs generated after + a given date. You can specify the date as an RFC 3339 date, a UNIX + timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date + format you may also use RFC3339Nano, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the client will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. You can combine the + `--since` option with either or both of the `--follow` or `--tail` options. usage: docker logs [OPTIONS] CONTAINER pname: docker plink: docker.yaml options: -- option: details - value_type: bool - default_value: "false" - description: Show extra details provided to logs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: follow - shorthand: f - value_type: bool - default_value: "false" - description: Follow log output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: since - value_type: string - description: | - Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tail - shorthand: "n" - value_type: string - default_value: all - description: Number of lines to show from the end of the logs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: timestamps - shorthand: t - value_type: bool - default_value: "false" - description: Show timestamps - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: until - value_type: string - description: | - Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) - deprecated: false - min_api_version: "1.35" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: details + value_type: bool + default_value: "false" + description: Show extra details provided to logs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: follow + shorthand: f + value_type: bool + default_value: "false" + description: Follow log output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: since + value_type: string + description: | + Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tail + shorthand: "n" + value_type: string + default_value: all + description: Number of lines to show from the end of the logs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: timestamps + shorthand: t + value_type: bool + default_value: "false" + description: Show timestamps + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: until + value_type: string + description: | + Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) + details_url: '#until' + deprecated: false + hidden: false + min_api_version: "1.35" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Retrieve logs until a specific point in time (--until) + ### Retrieve logs until a specific point in time (--until) {#until} - In order to retrieve logs before a specific point in time, run: + In order to retrieve logs before a specific point in time, run: - ```console - $ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done" - $ date - Tue 14 Nov 2017 16:40:00 CET - $ docker logs -f --until=2s test - Tue 14 Nov 2017 16:40:00 CET - Tue 14 Nov 2017 16:40:01 CET - Tue 14 Nov 2017 16:40:02 CET - ``` + ```console + $ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done" + $ date + Tue 14 Nov 2017 16:40:00 CET + $ docker logs -f --until=2s test + Tue 14 Nov 2017 16:40:00 CET + Tue 14 Nov 2017 16:40:01 CET + Tue 14 Nov 2017 16:40:02 CET + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_manifest.yaml b/_data/engine-cli/docker_manifest.yaml index 4ddb4e68bb..63b34707cd 100644 --- a/_data/engine-cli/docker_manifest.yaml +++ b/_data/engine-cli/docker_manifest.yaml @@ -1,280 +1,291 @@ command: docker manifest short: Manage Docker image manifests and manifest lists long: |- - The `docker manifest` command by itself performs no action. In order to operate - on a manifest or manifest list, one of the subcommands must be used. + The `docker manifest` command by itself performs no action. In order to operate + on a manifest or manifest list, one of the subcommands must be used. - A single manifest is information about an image, such as layers, size, and digest. - The docker manifest command also gives users additional information such as the os - and architecture an image was built for. + A single manifest is information about an image, such as layers, size, and digest. + The docker manifest command also gives users additional information such as the os + and architecture an image was built for. - A manifest list is a list of image layers that is created by specifying one or - more (ideally more than one) image names. It can then be used in the same way as - an image name in `docker pull` and `docker run` commands, for example. + A manifest list is a list of image layers that is created by specifying one or + more (ideally more than one) image names. It can then be used in the same way as + an image name in `docker pull` and `docker run` commands, for example. - Ideally a manifest list is created from images that are identical in function for - different os/arch combinations. For this reason, manifest lists are often referred - to as "multi-arch images". However, a user could create a manifest list that points - to two images -- one for windows on amd64, and one for darwin on amd64. + Ideally a manifest list is created from images that are identical in function for + different os/arch combinations. For this reason, manifest lists are often referred + to as "multi-arch images". However, a user could create a manifest list that points + to two images -- one for windows on amd64, and one for darwin on amd64. - ### manifest inspect + ### manifest inspect - ```console - $ docker manifest inspect --help + ```console + $ docker manifest inspect --help - Usage: docker manifest inspect [OPTIONS] [MANIFEST_LIST] MANIFEST + Usage: docker manifest inspect [OPTIONS] [MANIFEST_LIST] MANIFEST - Display an image manifest, or manifest list + Display an image manifest, or manifest list - Options: - --help Print usage - --insecure Allow communication with an insecure registry - -v, --verbose Output additional info including layers and platform - ``` + Options: + --help Print usage + --insecure Allow communication with an insecure registry + -v, --verbose Output additional info including layers and platform + ``` - ### manifest create + ### manifest create - ```console - Usage: docker manifest create MANIFEST_LIST MANIFEST [MANIFEST...] + ```console + Usage: docker manifest create MANIFEST_LIST MANIFEST [MANIFEST...] - Create a local manifest list for annotating and pushing to a registry + Create a local manifest list for annotating and pushing to a registry - Options: - -a, --amend Amend an existing manifest list - --insecure Allow communication with an insecure registry - --help Print usage - ``` + Options: + -a, --amend Amend an existing manifest list + --insecure Allow communication with an insecure registry + --help Print usage + ``` - ### manifest annotate + ### manifest annotate - ```console - Usage: docker manifest annotate [OPTIONS] MANIFEST_LIST MANIFEST + ```console + Usage: docker manifest annotate [OPTIONS] MANIFEST_LIST MANIFEST - Add additional information to a local image manifest + Add additional information to a local image manifest - Options: - --arch string Set architecture - --help Print usage - --os string Set operating system - --os-version string Set operating system version - --os-features stringSlice Set operating system feature - --variant string Set architecture variant + Options: + --arch string Set architecture + --help Print usage + --os string Set operating system + --os-version string Set operating system version + --os-features stringSlice Set operating system feature + --variant string Set architecture variant - ``` + ``` - ### manifest push + ### manifest push - ```console - Usage: docker manifest push [OPTIONS] MANIFEST_LIST + ```console + Usage: docker manifest push [OPTIONS] MANIFEST_LIST - Push a manifest list to a repository + Push a manifest list to a repository - Options: - --help Print usage - --insecure Allow push to an insecure registry - -p, --purge Remove the local manifest list after push - ``` + Options: + --help Print usage + --insecure Allow push to an insecure registry + -p, --purge Remove the local manifest list after push + ``` - ### Working with insecure registries + ### Working with insecure registries - The manifest command interacts solely with a Docker registry. Because of this, - it has no way to query the engine for the list of allowed insecure registries. - To allow the CLI to interact with an insecure registry, some `docker manifest` - commands have an `--insecure` flag. For each transaction, such as a `create`, - which queries a registry, the `--insecure` flag must be specified. This flag - tells the CLI that this registry call may ignore security concerns like missing - or self-signed certificates. Likewise, on a `manifest push` to an insecure - registry, the `--insecure` flag must be specified. If this is not used with an - insecure registry, the manifest command fails to find a registry that meets the - default requirements. + The manifest command interacts solely with a registry. Because of this, + it has no way to query the engine for the list of allowed insecure registries. + To allow the CLI to interact with an insecure registry, some `docker manifest` + commands have an `--insecure` flag. For each transaction, such as a `create`, + which queries a registry, the `--insecure` flag must be specified. This flag + tells the CLI that this registry call may ignore security concerns like missing + or self-signed certificates. Likewise, on a `manifest push` to an insecure + registry, the `--insecure` flag must be specified. If this is not used with an + insecure registry, the manifest command fails to find a registry that meets the + default requirements. usage: docker manifest COMMAND pname: docker plink: docker.yaml cname: -- docker manifest annotate -- docker manifest create -- docker manifest inspect -- docker manifest push -- docker manifest rm + - docker manifest annotate + - docker manifest create + - docker manifest inspect + - docker manifest push + - docker manifest rm clink: -- docker_manifest_annotate.yaml -- docker_manifest_create.yaml -- docker_manifest_inspect.yaml -- docker_manifest_push.yaml -- docker_manifest_rm.yaml + - docker_manifest_annotate.yaml + - docker_manifest_create.yaml + - docker_manifest_inspect.yaml + - docker_manifest_push.yaml + - docker_manifest_rm.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Inspect an image's manifest object + ### Inspect an image's manifest object - ```console - $ docker manifest inspect hello-world - { - "schemaVersion": 2, - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "config": { - "mediaType": "application/vnd.docker.container.image.v1+json", - "size": 1520, - "digest": "sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57" + ```console + $ docker manifest inspect hello-world + { + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "config": { + "mediaType": "application/vnd.docker.container.image.v1+json", + "size": 1520, + "digest": "sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57" + }, + "layers": [ + { + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "size": 972, + "digest": "sha256:b04784fba78d739b526e27edc02a5a8cd07b1052e9283f5fc155828f4b614c28" + } + ] + } + ``` + + ### Inspect an image's manifest and get the os/arch info + + The `docker manifest inspect` command takes an optional `--verbose` flag + that gives you the image's name (Ref), and architecture and os (Platform). + + Just as with other docker commands that take image names, you can refer to an image with or + without a tag, or by digest (e.g. `hello-world@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f`). + + Here is an example of inspecting an image's manifest with the `--verbose` flag: + + ```console + $ docker manifest inspect --verbose hello-world + { + "Ref": "docker.io/library/hello-world:latest", + "Digest": "sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f", + "SchemaV2Manifest": { + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "config": { + "mediaType": "application/vnd.docker.container.image.v1+json", + "size": 1520, + "digest": "sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57" + }, + "layers": [ + { + "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", + "size": 972, + "digest": "sha256:b04784fba78d739b526e27edc02a5a8cd07b1052e9283f5fc155828f4b614c28" + } + ] + }, + "Platform": { + "architecture": "amd64", + "os": "linux" + } + } + ``` + + ### Create and push a manifest list + + To create a manifest list, you first `create` the manifest list locally by + specifying the constituent images you would like to have included in your + manifest list. Keep in mind that this is pushed to a registry, so if you want to + push to a registry other than the docker registry, you need to create your + manifest list with the registry name or IP and port. + This is similar to tagging an image and pushing it to a foreign registry. + + After you have created your local copy of the manifest list, you may optionally + `annotate` it. Annotations allowed are the architecture and operating system + (overriding the image's current values), os features, and an architecture variant. + + Finally, you need to `push` your manifest list to the desired registry. Below are + descriptions of these three commands, and an example putting them all together. + + ```console + $ docker manifest create 45.55.81.106:5000/coolapp:v1 \ + 45.55.81.106:5000/coolapp-ppc64le-linux:v1 \ + 45.55.81.106:5000/coolapp-arm-linux:v1 \ + 45.55.81.106:5000/coolapp-amd64-linux:v1 \ + 45.55.81.106:5000/coolapp-amd64-windows:v1 + + Created manifest list 45.55.81.106:5000/coolapp:v1 + ``` + + ```console + $ docker manifest annotate 45.55.81.106:5000/coolapp:v1 45.55.81.106:5000/coolapp-arm-linux --arch arm + ``` + + ```console + $ docker manifest push 45.55.81.106:5000/coolapp:v1 + Pushed manifest 45.55.81.106:5000/coolapp@sha256:9701edc932223a66e49dd6c894a11db8c2cf4eccd1414f1ec105a623bf16b426 with digest: sha256:f67dcc5fc786f04f0743abfe0ee5dae9bd8caf8efa6c8144f7f2a43889dc513b + Pushed manifest 45.55.81.106:5000/coolapp@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f with digest: sha256:b64ca0b60356a30971f098c92200b1271257f100a55b351e6bbe985638352f3a + Pushed manifest 45.55.81.106:5000/coolapp@sha256:39dc41c658cf25f33681a41310372f02728925a54aac3598310bfb1770615fc9 with digest: sha256:df436846483aff62bad830b730a0d3b77731bcf98ba5e470a8bbb8e9e346e4e8 + Pushed manifest 45.55.81.106:5000/coolapp@sha256:f91b1145cd4ac800b28122313ae9e88ac340bb3f1e3a4cd3e59a3648650f3275 with digest: sha256:5bb8e50aa2edd408bdf3ddf61efb7338ff34a07b762992c9432f1c02fc0e5e62 + sha256:050b213d49d7673ba35014f21454c573dcbec75254a08f4a7c34f66a47c06aba + + ``` + + ### Inspect a manifest list + + ```console + $ docker manifest inspect coolapp:v1 + { + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", + "manifests": [ + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 424, + "digest": "sha256:f67dcc5fc786f04f0743abfe0ee5dae9bd8caf8efa6c8144f7f2a43889dc513b", + "platform": { + "architecture": "arm", + "os": "linux" + } }, - "layers": [ - { - "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", - "size": 972, - "digest": "sha256:b04784fba78d739b526e27edc02a5a8cd07b1052e9283f5fc155828f4b614c28" - } - ] - } - ``` - - ### Inspect an image's manifest and get the os/arch info - - The `docker manifest inspect` command takes an optional `--verbose` flag - that gives you the image's name (Ref), and architecture and os (Platform). - - Just as with other docker commands that take image names, you can refer to an image with or - without a tag, or by digest (e.g. `hello-world@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f`). - - Here is an example of inspecting an image's manifest with the `--verbose` flag: - - ```console - $ docker manifest inspect --verbose hello-world - { - "Ref": "docker.io/library/hello-world:latest", - "Digest": "sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f", - "SchemaV2Manifest": { - "schemaVersion": 2, - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "config": { - "mediaType": "application/vnd.docker.container.image.v1+json", - "size": 1520, - "digest": "sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57" - }, - "layers": [ - { - "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", - "size": 972, - "digest": "sha256:b04784fba78d739b526e27edc02a5a8cd07b1052e9283f5fc155828f4b614c28" - } - ] + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 424, + "digest": "sha256:b64ca0b60356a30971f098c92200b1271257f100a55b351e6bbe985638352f3a", + "platform": { + "architecture": "amd64", + "os": "linux" + } }, - "Platform": { - "architecture": "amd64", - "os": "linux" + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 425, + "digest": "sha256:df436846483aff62bad830b730a0d3b77731bcf98ba5e470a8bbb8e9e346e4e8", + "platform": { + "architecture": "ppc64le", + "os": "linux" + } + }, + { + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "size": 425, + "digest": "sha256:5bb8e50aa2edd408bdf3ddf61efb7338ff34a07b762992c9432f1c02fc0e5e62", + "platform": { + "architecture": "s390x", + "os": "linux" + } } - } - ``` + ] + } + ``` - ### Create and push a manifest list + ### Push to an insecure registry - To create a manifest list, you first `create` the manifest list locally by - specifying the constituent images you would like to have included in your - manifest list. Keep in mind that this is pushed to a registry, so if you want to - push to a registry other than the docker registry, you need to create your - manifest list with the registry name or IP and port. - This is similar to tagging an image and pushing it to a foreign registry. + Here is an example of creating and pushing a manifest list using a known + insecure registry. - After you have created your local copy of the manifest list, you may optionally - `annotate` it. Annotations allowed are the architecture and operating system - (overriding the image's current values), os features, and an architecture variant. + ```console + $ docker manifest create --insecure myprivateregistry.mycompany.com/repo/image:1.0 \ + myprivateregistry.mycompany.com/repo/image-linux-ppc64le:1.0 \ + myprivateregistry.mycompany.com/repo/image-linux-s390x:1.0 \ + myprivateregistry.mycompany.com/repo/image-linux-arm:1.0 \ + myprivateregistry.mycompany.com/repo/image-linux-armhf:1.0 \ + myprivateregistry.mycompany.com/repo/image-windows-amd64:1.0 \ + myprivateregistry.mycompany.com/repo/image-linux-amd64:1.0 - Finally, you need to `push` your manifest list to the desired registry. Below are - descriptions of these three commands, and an example putting them all together. + $ docker manifest push --insecure myprivateregistry.mycompany.com/repo/image:tag + ``` - ```console - $ docker manifest create 45.55.81.106:5000/coolapp:v1 \ - 45.55.81.106:5000/coolapp-ppc64le-linux:v1 \ - 45.55.81.106:5000/coolapp-arm-linux:v1 \ - 45.55.81.106:5000/coolapp-amd64-linux:v1 \ - 45.55.81.106:5000/coolapp-amd64-windows:v1 - - Created manifest list 45.55.81.106:5000/coolapp:v1 - ``` - - ```console - $ docker manifest annotate 45.55.81.106:5000/coolapp:v1 45.55.81.106:5000/coolapp-arm-linux --arch arm - ``` - - ```console - $ docker manifest push 45.55.81.106:5000/coolapp:v1 - Pushed manifest 45.55.81.106:5000/coolapp@sha256:9701edc932223a66e49dd6c894a11db8c2cf4eccd1414f1ec105a623bf16b426 with digest: sha256:f67dcc5fc786f04f0743abfe0ee5dae9bd8caf8efa6c8144f7f2a43889dc513b - Pushed manifest 45.55.81.106:5000/coolapp@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f with digest: sha256:b64ca0b60356a30971f098c92200b1271257f100a55b351e6bbe985638352f3a - Pushed manifest 45.55.81.106:5000/coolapp@sha256:39dc41c658cf25f33681a41310372f02728925a54aac3598310bfb1770615fc9 with digest: sha256:df436846483aff62bad830b730a0d3b77731bcf98ba5e470a8bbb8e9e346e4e8 - Pushed manifest 45.55.81.106:5000/coolapp@sha256:f91b1145cd4ac800b28122313ae9e88ac340bb3f1e3a4cd3e59a3648650f3275 with digest: sha256:5bb8e50aa2edd408bdf3ddf61efb7338ff34a07b762992c9432f1c02fc0e5e62 - sha256:050b213d49d7673ba35014f21454c573dcbec75254a08f4a7c34f66a47c06aba - - ``` - - ### Inspect a manifest list - - ```console - $ docker manifest inspect coolapp:v1 - { - "schemaVersion": 2, - "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", - "manifests": [ - { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "size": 424, - "digest": "sha256:f67dcc5fc786f04f0743abfe0ee5dae9bd8caf8efa6c8144f7f2a43889dc513b", - "platform": { - "architecture": "arm", - "os": "linux" - } - }, - { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "size": 424, - "digest": "sha256:b64ca0b60356a30971f098c92200b1271257f100a55b351e6bbe985638352f3a", - "platform": { - "architecture": "amd64", - "os": "linux" - } - }, - { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "size": 425, - "digest": "sha256:df436846483aff62bad830b730a0d3b77731bcf98ba5e470a8bbb8e9e346e4e8", - "platform": { - "architecture": "ppc64le", - "os": "linux" - } - }, - { - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "size": 425, - "digest": "sha256:5bb8e50aa2edd408bdf3ddf61efb7338ff34a07b762992c9432f1c02fc0e5e62", - "platform": { - "architecture": "s390x", - "os": "linux" - } - } - ] - } - ``` - - ### Push to an insecure registry - - Here is an example of creating and pushing a manifest list using a known - insecure registry. - - ```console - $ docker manifest create --insecure myprivateregistry.mycompany.com/repo/image:1.0 \ - myprivateregistry.mycompany.com/repo/image-linux-ppc64le:1.0 \ - myprivateregistry.mycompany.com/repo/image-linux-s390x:1.0 \ - myprivateregistry.mycompany.com/repo/image-linux-arm:1.0 \ - myprivateregistry.mycompany.com/repo/image-linux-armhf:1.0 \ - myprivateregistry.mycompany.com/repo/image-windows-amd64:1.0 \ - myprivateregistry.mycompany.com/repo/image-linux-amd64:1.0 - - $ docker manifest push --insecure myprivateregistry.mycompany.com/repo/image:tag - ``` - - > **Note** - > - > The `--insecure` flag is not required to annotate a manifest list, - > since annotations are to a locally-stored copy of a manifest list. You may also - > skip the `--insecure` flag if you are performing a `docker manifest inspect` - > on a locally-stored manifest list. Be sure to keep in mind that locally-stored - > manifest lists are never used by the engine on a `docker pull`. + > **Note** + > + > The `--insecure` flag is not required to annotate a manifest list, + > since annotations are to a locally-stored copy of a manifest list. You may also + > skip the `--insecure` flag if you are performing a `docker manifest inspect` + > on a locally-stored manifest list. Be sure to keep in mind that locally-stored + > manifest lists are never used by the engine on a `docker pull`. deprecated: false experimental: false experimentalcli: true diff --git a/_data/engine-cli/docker_manifest_annotate.yaml b/_data/engine-cli/docker_manifest_annotate.yaml index 9807caa1be..217f0c2343 100644 --- a/_data/engine-cli/docker_manifest_annotate.yaml +++ b/_data/engine-cli/docker_manifest_annotate.yaml @@ -5,47 +5,63 @@ usage: docker manifest annotate [OPTIONS] MANIFEST_LIST MANIFEST pname: docker manifest plink: docker_manifest.yaml options: -- option: arch - value_type: string - description: Set architecture - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: os - value_type: string - description: Set operating system - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: os-features - value_type: stringSlice - default_value: '[]' - description: Set operating system feature - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: os-version - value_type: string - description: Set operating system version - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: variant - value_type: string - description: Set architecture variant - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: arch + value_type: string + description: Set architecture + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: os + value_type: string + description: Set operating system + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: os-features + value_type: stringSlice + default_value: '[]' + description: Set operating system feature + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: os-version + value_type: string + description: Set operating system version + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: variant + value_type: string + description: Set architecture variant + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: true diff --git a/_data/engine-cli/docker_manifest_create.yaml b/_data/engine-cli/docker_manifest_create.yaml index 9bee33d6bd..792dbc52b7 100644 --- a/_data/engine-cli/docker_manifest_create.yaml +++ b/_data/engine-cli/docker_manifest_create.yaml @@ -5,25 +5,38 @@ usage: docker manifest create MANIFEST_LIST MANIFEST [MANIFEST...] pname: docker manifest plink: docker_manifest.yaml options: -- option: amend - shorthand: a - value_type: bool - default_value: "false" - description: Amend an existing manifest list - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: insecure - value_type: bool - default_value: "false" - description: Allow communication with an insecure registry - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: amend + shorthand: a + value_type: bool + default_value: "false" + description: Amend an existing manifest list + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: insecure + value_type: bool + default_value: "false" + description: Allow communication with an insecure registry + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: true diff --git a/_data/engine-cli/docker_manifest_inspect.yaml b/_data/engine-cli/docker_manifest_inspect.yaml index 8da0a57b6f..3d463f037d 100644 --- a/_data/engine-cli/docker_manifest_inspect.yaml +++ b/_data/engine-cli/docker_manifest_inspect.yaml @@ -5,25 +5,38 @@ usage: docker manifest inspect [OPTIONS] [MANIFEST_LIST] MANIFEST pname: docker manifest plink: docker_manifest.yaml options: -- option: insecure - value_type: bool - default_value: "false" - description: Allow communication with an insecure registry - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: verbose - shorthand: v - value_type: bool - default_value: "false" - description: Output additional info including layers and platform - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: insecure + value_type: bool + default_value: "false" + description: Allow communication with an insecure registry + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: verbose + shorthand: v + value_type: bool + default_value: "false" + description: Output additional info including layers and platform + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: true diff --git a/_data/engine-cli/docker_manifest_push.yaml b/_data/engine-cli/docker_manifest_push.yaml index e286da6aee..79e23f5dc3 100644 --- a/_data/engine-cli/docker_manifest_push.yaml +++ b/_data/engine-cli/docker_manifest_push.yaml @@ -5,25 +5,38 @@ usage: docker manifest push [OPTIONS] MANIFEST_LIST pname: docker manifest plink: docker_manifest.yaml options: -- option: insecure - value_type: bool - default_value: "false" - description: Allow push to an insecure registry - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: purge - shorthand: p - value_type: bool - default_value: "false" - description: Remove the local manifest list after push - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: insecure + value_type: bool + default_value: "false" + description: Allow push to an insecure registry + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: purge + shorthand: p + value_type: bool + default_value: "false" + description: Remove the local manifest list after push + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: true diff --git a/_data/engine-cli/docker_manifest_rm.yaml b/_data/engine-cli/docker_manifest_rm.yaml index 513d2a7b2c..fec8f6dfa0 100644 --- a/_data/engine-cli/docker_manifest_rm.yaml +++ b/_data/engine-cli/docker_manifest_rm.yaml @@ -4,6 +4,17 @@ long: Delete one or more manifest lists from local storage usage: docker manifest rm MANIFEST_LIST [MANIFEST_LIST...] pname: docker manifest plink: docker_manifest.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: true diff --git a/_data/engine-cli/docker_network.yaml b/_data/engine-cli/docker_network.yaml index bfaa8977fe..5f6306f307 100644 --- a/_data/engine-cli/docker_network.yaml +++ b/_data/engine-cli/docker_network.yaml @@ -1,27 +1,38 @@ command: docker network short: Manage networks long: |- - Manage networks. You can use subcommands to create, inspect, list, remove, - prune, connect, and disconnect networks. + Manage networks. You can use subcommands to create, inspect, list, remove, + prune, connect, and disconnect networks. usage: docker network pname: docker plink: docker.yaml cname: -- docker network connect -- docker network create -- docker network disconnect -- docker network inspect -- docker network ls -- docker network prune -- docker network rm + - docker network connect + - docker network create + - docker network disconnect + - docker network inspect + - docker network ls + - docker network prune + - docker network rm clink: -- docker_network_connect.yaml -- docker_network_create.yaml -- docker_network_disconnect.yaml -- docker_network_inspect.yaml -- docker_network_ls.yaml -- docker_network_prune.yaml -- docker_network_rm.yaml + - docker_network_connect.yaml + - docker_network_create.yaml + - docker_network_disconnect.yaml + - docker_network_inspect.yaml + - docker_network_ls.yaml + - docker_network_prune.yaml + - docker_network_rm.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_network_connect.yaml b/_data/engine-cli/docker_network_connect.yaml index 9224936676..dddc3e32e6 100644 --- a/_data/engine-cli/docker_network_connect.yaml +++ b/_data/engine-cli/docker_network_connect.yaml @@ -1,136 +1,156 @@ command: docker network connect short: Connect a container to a network long: |- - Connects a container to a network. You can connect a container by name - or by ID. Once connected, the container can communicate with other containers in - the same network. + Connects a container to a network. You can connect a container by name + or by ID. Once connected, the container can communicate with other containers in + the same network. usage: docker network connect [OPTIONS] NETWORK CONTAINER pname: docker network plink: docker_network.yaml options: -- option: alias - value_type: stringSlice - default_value: '[]' - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: driver-opt - value_type: stringSlice - default_value: '[]' - description: driver options for the network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ip - value_type: string - description: IPv4 address (e.g., 172.30.100.104) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ip6 - value_type: string - description: IPv6 address (e.g., 2001:db8::33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link - value_type: list - description: Add link to another container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link-local-ip - value_type: stringSlice - default_value: '[]' - description: Add a link-local address for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: alias + value_type: stringSlice + default_value: '[]' + description: Add network-scoped alias for the container + details_url: '#alias' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: driver-opt + value_type: stringSlice + default_value: '[]' + description: driver options for the network + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ip + value_type: string + description: IPv4 address (e.g., `172.30.100.104`) + details_url: '#ip' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ip6 + value_type: string + description: IPv6 address (e.g., `2001:db8::33`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link + value_type: list + description: Add link to another container + details_url: '#link' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link-local-ip + value_type: stringSlice + default_value: '[]' + description: Add a link-local address for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Connect a running container to a network + ### Connect a running container to a network - ```console - $ docker network connect multi-host-network container1 - ``` + ```console + $ docker network connect multi-host-network container1 + ``` - ### Connect a container to a network when it starts + ### Connect a container to a network when it starts - You can also use the `docker run --network=` option to start a - container and immediately connect it to a network. + You can also use the `docker run --network=` option to start a + container and immediately connect it to a network. - ```console - $ docker run -itd --network=multi-host-network busybox - ``` + ```console + $ docker run -itd --network=multi-host-network busybox + ``` - ### Specify the IP address a container will use on a given network (--ip) + ### Specify the IP address a container will use on a given network (--ip) {#ip} - You can specify the IP address you want to be assigned to the container's interface. + You can specify the IP address you want to be assigned to the container's interface. - ```console - $ docker network connect --ip 10.10.36.122 multi-host-network container2 - ``` + ```console + $ docker network connect --ip 10.10.36.122 multi-host-network container2 + ``` - ### Use the legacy `--link` option (--link) + ### Use the legacy `--link` option (--link) {#link} - You can use `--link` option to link another container with a preferred alias + You can use `--link` option to link another container with a preferred alias - ```console - $ docker network connect --link container1:c1 multi-host-network container2 - ``` + ```console + $ docker network connect --link container1:c1 multi-host-network container2 + ``` - ### Create a network alias for a container (--alias) + ### Create a network alias for a container (--alias) {#alias} - `--alias` option can be used to resolve the container by another name in the network - being connected to. + `--alias` option can be used to resolve the container by another name in the network + being connected to. - ```console - $ docker network connect --alias db --alias mysql multi-host-network container2 - ``` + ```console + $ docker network connect --alias db --alias mysql multi-host-network container2 + ``` - ### Network implications of stopping, pausing, or restarting containers + ### Network implications of stopping, pausing, or restarting containers - You can pause, restart, and stop containers that are connected to a network. - A container connects to its configured networks when it runs. + You can pause, restart, and stop containers that are connected to a network. + A container connects to its configured networks when it runs. - If specified, the container's IP address(es) is reapplied when a stopped - container is restarted. If the IP address is no longer available, the container - fails to start. One way to guarantee that the IP address is available is - to specify an `--ip-range` when creating the network, and choose the static IP - address(es) from outside that range. This ensures that the IP address is not - given to another container while this container is not on the network. + If specified, the container's IP address(es) is reapplied when a stopped + container is restarted. If the IP address is no longer available, the container + fails to start. One way to guarantee that the IP address is available is + to specify an `--ip-range` when creating the network, and choose the static IP + address(es) from outside that range. This ensures that the IP address is not + given to another container while this container is not on the network. - ```console - $ docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-host-network - ``` + ```console + $ docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-host-network + ``` - ```console - $ docker network connect --ip 172.20.128.2 multi-host-network container2 - ``` + ```console + $ docker network connect --ip 172.20.128.2 multi-host-network container2 + ``` - To verify the container is connected, use the `docker network inspect` command. - Use `docker network disconnect` to remove a container from the network. + To verify the container is connected, use the `docker network inspect` command. + Use `docker network disconnect` to remove a container from the network. - Once connected in network, containers can communicate using only another - container's IP address or name. For `overlay` networks or custom plugins that - support multi-host connectivity, containers connected to the same multi-host - network but launched from different Engines can also communicate in this way. + Once connected in network, containers can communicate using only another + container's IP address or name. For `overlay` networks or custom plugins that + support multi-host connectivity, containers connected to the same multi-host + network but launched from different Engines can also communicate in this way. - You can connect a container to one or more networks. The networks need not be - the same type. For example, you can connect a single container bridge and overlay - networks. + You can connect a container to one or more networks. The networks need not be + the same type. For example, you can connect a single container bridge and overlay + networks. deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_network_create.yaml b/_data/engine-cli/docker_network_create.yaml index 3795d69a1a..2c469e2d07 100644 --- a/_data/engine-cli/docker_network_create.yaml +++ b/_data/engine-cli/docker_network_create.yaml @@ -1,341 +1,397 @@ command: docker network create short: Create a network long: |- - Creates a new network. The `DRIVER` accepts `bridge` or `overlay` which are the - built-in network drivers. If you have installed a third party or your own custom - network driver you can specify that `DRIVER` here also. If you don't specify the - `--driver` option, the command automatically creates a `bridge` network for you. - When you install Docker Engine it creates a `bridge` network automatically. This - network corresponds to the `docker0` bridge that Engine has traditionally relied - on. When you launch a new container with `docker run` it automatically connects to - this bridge network. You cannot remove this default bridge network, but you can - create new ones using the `network create` command. + Creates a new network. The `DRIVER` accepts `bridge` or `overlay` which are the + built-in network drivers. If you have installed a third party or your own custom + network driver you can specify that `DRIVER` here also. If you don't specify the + `--driver` option, the command automatically creates a `bridge` network for you. + When you install Docker Engine it creates a `bridge` network automatically. This + network corresponds to the `docker0` bridge that Engine has traditionally relied + on. When you launch a new container with `docker run` it automatically connects to + this bridge network. You cannot remove this default bridge network, but you can + create new ones using the `network create` command. - ```console - $ docker network create -d bridge my-bridge-network - ``` + ```console + $ docker network create -d bridge my-bridge-network + ``` - Bridge networks are isolated networks on a single Engine installation. If you - want to create a network that spans multiple Docker hosts each running an - Engine, you must create an `overlay` network. Unlike `bridge` networks, overlay - networks require some pre-existing conditions before you can create one. These - conditions are: + Bridge networks are isolated networks on a single Engine installation. If you + want to create a network that spans multiple Docker hosts each running an + Engine, you must enable Swarm mode, and create an `overlay` network. To read more + about overlay networks with Swarm mode, see ["*use overlay networks*"](/network/overlay/). - * Access to a key-value store. Engine supports Consul, Etcd, and ZooKeeper (Distributed store) key-value stores. - * A cluster of hosts with connectivity to the key-value store. - * A properly configured Engine `daemon` on each host in the cluster. + Once you have enabled swarm mode, you can create a swarm-scoped overlay network: - The `dockerd` options that support the `overlay` network are: + ```console + $ docker network create --scope=swarm --attachable -d overlay my-multihost-network + ``` - * `--cluster-store` - * `--cluster-store-opt` - * `--cluster-advertise` + By default, swarm-scoped networks do not allow manually started containers to + be attached. This restriction is added to prevent someone that has access to + a non-manager node in the swarm cluster from running a container that is able + to access the network stack of a swarm service. - To read more about these options and how to configure them, see ["*Get started - with multi-host network*"](https://docs.docker.com/engine/userguide/networking/get-started-overlay). + The `--attachable` option used in the example above disables this restriction, + and allows for both swarm services and manually started containers to attach to + the oerlay network. - While not required, it is a good idea to install Docker Swarm to - manage the cluster that makes up your network. Swarm provides sophisticated - discovery and server management tools that can assist your implementation. + Network names must be unique. The Docker daemon attempts to identify naming + conflicts but this is not guaranteed. It is the user's responsibility to avoid + name conflicts. - Once you have prepared the `overlay` network prerequisites you simply choose a - Docker host in the cluster and issue the following to create the network: + ### Overlay network limitations - ```console - $ docker network create -d overlay my-multihost-network - ``` - - Network names must be unique. The Docker daemon attempts to identify naming - conflicts but this is not guaranteed. It is the user's responsibility to avoid - name conflicts. - - ### Overlay network limitations - - You should create overlay networks with `/24` blocks (the default), which limits - you to 256 IP addresses, when you create networks using the default VIP-based - endpoint-mode. This recommendation addresses - [limitations with swarm mode](https://github.com/moby/moby/issues/30820). If you - need more than 256 IP addresses, do not increase the IP block size. You can - either use `dnsrr` endpoint mode with an external load balancer, or use multiple - smaller overlay networks. See - [Configure service discovery](https://docs.docker.com/engine/swarm/networking/#configure-service-discovery) - for more information about different endpoint modes. + You should create overlay networks with `/24` blocks (the default), which limits + you to 256 IP addresses, when you create networks using the default VIP-based + endpoint-mode. This recommendation addresses + [limitations with swarm mode](https://github.com/moby/moby/issues/30820). If you + need more than 256 IP addresses, do not increase the IP block size. You can + either use `dnsrr` endpoint mode with an external load balancer, or use multiple + smaller overlay networks. See + [Configure service discovery](/engine/swarm/networking/#configure-service-discovery) + for more information about different endpoint modes. usage: docker network create [OPTIONS] NETWORK pname: docker network plink: docker_network.yaml options: -- option: attachable - value_type: bool - default_value: "false" - description: Enable manual container attachment - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: aux-address - value_type: map - default_value: map[] - description: Auxiliary IPv4 or IPv6 addresses used by Network driver - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: config-from - value_type: string - description: The network from which to copy the configuration - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: config-only - value_type: bool - default_value: "false" - description: Create a configuration only network - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: driver - shorthand: d - value_type: string - default_value: bridge - description: Driver to manage the Network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: gateway - value_type: stringSlice - default_value: '[]' - description: IPv4 or IPv6 Gateway for the master subnet - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ingress - value_type: bool - default_value: "false" - description: Create swarm routing-mesh network - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: internal - value_type: bool - default_value: "false" - description: Restrict external access to the network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ip-range - value_type: stringSlice - default_value: '[]' - description: Allocate container ip from a sub-range - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ipam-driver - value_type: string - default_value: default - description: IP Address Management Driver - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ipam-opt - value_type: map - default_value: map[] - description: Set IPAM driver specific options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ipv6 - value_type: bool - default_value: "false" - description: Enable IPv6 networking - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - value_type: list - description: Set metadata on a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: opt - shorthand: o - value_type: map - default_value: map[] - description: Set driver specific options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: scope - value_type: string - description: Control the network's scope - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: subnet - value_type: stringSlice - default_value: '[]' - description: Subnet in CIDR format that represents a network segment - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: attachable + value_type: bool + default_value: "false" + description: Enable manual container attachment + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: aux-address + value_type: map + default_value: map[] + description: Auxiliary IPv4 or IPv6 addresses used by Network driver + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: config-from + value_type: string + description: The network from which to copy the configuration + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: config-only + value_type: bool + default_value: "false" + description: Create a configuration only network + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: driver + shorthand: d + value_type: string + default_value: bridge + description: Driver to manage the Network + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: gateway + value_type: stringSlice + default_value: '[]' + description: IPv4 or IPv6 Gateway for the master subnet + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ingress + value_type: bool + default_value: "false" + description: Create swarm routing-mesh network + details_url: '#ingress' + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: internal + value_type: bool + default_value: "false" + description: Restrict external access to the network + details_url: '#internal' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ip-range + value_type: stringSlice + default_value: '[]' + description: Allocate container ip from a sub-range + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ipam-driver + value_type: string + default_value: default + description: IP Address Management Driver + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ipam-opt + value_type: map + default_value: map[] + description: Set IPAM driver specific options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ipv6 + value_type: bool + default_value: "false" + description: Enable IPv6 networking + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + value_type: list + description: Set metadata on a network + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: opt + shorthand: o + value_type: map + default_value: map[] + description: Set driver specific options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: scope + value_type: string + description: Control the network's scope + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: subnet + value_type: stringSlice + default_value: '[]' + description: Subnet in CIDR format that represents a network segment + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Connect containers + ### Connect containers - When you start a container, use the `--network` flag to connect it to a network. - This example adds the `busybox` container to the `mynet` network: + When you start a container, use the `--network` flag to connect it to a network. + This example adds the `busybox` container to the `mynet` network: - ```console - $ docker run -itd --network=mynet busybox - ``` + ```console + $ docker run -itd --network=mynet busybox + ``` - If you want to add a container to a network after the container is already - running, use the `docker network connect` subcommand. + If you want to add a container to a network after the container is already + running, use the `docker network connect` subcommand. - You can connect multiple containers to the same network. Once connected, the - containers can communicate using only another container's IP address or name. - For `overlay` networks or custom plugins that support multi-host connectivity, - containers connected to the same multi-host network but launched from different - Engines can also communicate in this way. + You can connect multiple containers to the same network. Once connected, the + containers can communicate using only another container's IP address or name. + For `overlay` networks or custom plugins that support multi-host connectivity, + containers connected to the same multi-host network but launched from different + Engines can also communicate in this way. - You can disconnect a container from a network using the `docker network - disconnect` command. + You can disconnect a container from a network using the `docker network + disconnect` command. - ### Specify advanced options + ### Specify advanced options - When you create a network, Engine creates a non-overlapping subnetwork for the - network by default. This subnetwork is not a subdivision of an existing - network. It is purely for ip-addressing purposes. You can override this default - and specify subnetwork values directly using the `--subnet` option. On a - `bridge` network you can only create a single subnet: + When you create a network, Engine creates a non-overlapping subnetwork for the + network by default. This subnetwork is not a subdivision of an existing network. + It is purely for ip-addressing purposes. You can override this default and + specify subnetwork values directly using the `--subnet` option. On a + `bridge` network you can only create a single subnet: - ```console - $ docker network create --driver=bridge --subnet=192.168.0.0/16 br0 - ``` + ```console + $ docker network create --driver=bridge --subnet=192.168.0.0/16 br0 + ``` - Additionally, you also specify the `--gateway` `--ip-range` and `--aux-address` - options. + Additionally, you also specify the `--gateway` `--ip-range` and `--aux-address` + options. - ```console - $ docker network create \ - --driver=bridge \ - --subnet=172.28.0.0/16 \ - --ip-range=172.28.5.0/24 \ - --gateway=172.28.5.254 \ - br0 - ``` + ```console + $ docker network create \ + --driver=bridge \ + --subnet=172.28.0.0/16 \ + --ip-range=172.28.5.0/24 \ + --gateway=172.28.5.254 \ + br0 + ``` - If you omit the `--gateway` flag the Engine selects one for you from inside a - preferred pool. For `overlay` networks and for network driver plugins that - support it you can create multiple subnetworks. This example uses two `/25` - subnet mask to adhere to the current guidance of not having more than 256 IPs in - a single overlay network. Each of the subnetworks has 126 usable addresses. + If you omit the `--gateway` flag the Engine selects one for you from inside a + preferred pool. For `overlay` networks and for network driver plugins that + support it you can create multiple subnetworks. This example uses two `/25` + subnet mask to adhere to the current guidance of not having more than 256 IPs in + a single overlay network. Each of the subnetworks has 126 usable addresses. - ```console - $ docker network create -d overlay \ - --subnet=192.168.10.0/25 \ - --subnet=192.168.20.0/25 \ - --gateway=192.168.10.100 \ - --gateway=192.168.20.100 \ - --aux-address="my-router=192.168.10.5" --aux-address="my-switch=192.168.10.6" \ - --aux-address="my-printer=192.168.20.5" --aux-address="my-nas=192.168.20.6" \ - my-multihost-network - ``` + ```console + $ docker network create -d overlay \ + --subnet=192.168.10.0/25 \ + --subnet=192.168.20.0/25 \ + --gateway=192.168.10.100 \ + --gateway=192.168.20.100 \ + --aux-address="my-router=192.168.10.5" --aux-address="my-switch=192.168.10.6" \ + --aux-address="my-printer=192.168.20.5" --aux-address="my-nas=192.168.20.6" \ + my-multihost-network + ``` - Be sure that your subnetworks do not overlap. If they do, the network create - fails and Engine returns an error. + Be sure that your subnetworks do not overlap. If they do, the network create + fails and Engine returns an error. - ### Bridge driver options + ### Bridge driver options - When creating a custom network, the default network driver (i.e. `bridge`) has - additional options that can be passed. The following are those options and the - equivalent docker daemon flags used for docker0 bridge: + When creating a custom network, the default network driver (i.e. `bridge`) has + additional options that can be passed. The following are those options and the + equivalent docker daemon flags used for docker0 bridge: - | Option | Equivalent | Description | - |--------------------------------------------------|-------------|-------------------------------------------------------| - | `com.docker.network.bridge.name` | - | Bridge name to be used when creating the Linux bridge | - | `com.docker.network.bridge.enable_ip_masquerade` | `--ip-masq` | Enable IP masquerading | - | `com.docker.network.bridge.enable_icc` | `--icc` | Enable or Disable Inter Container Connectivity | - | `com.docker.network.bridge.host_binding_ipv4` | `--ip` | Default IP when binding container ports | - | `com.docker.network.driver.mtu` | `--mtu` | Set the containers network MTU | - | `com.docker.network.container_iface_prefix` | - | Set a custom prefix for container interfaces | + | Option | Equivalent | Description | + |--------------------------------------------------|-------------|-------------------------------------------------------| + | `com.docker.network.bridge.name` | - | Bridge name to be used when creating the Linux bridge | + | `com.docker.network.bridge.enable_ip_masquerade` | `--ip-masq` | Enable IP masquerading | + | `com.docker.network.bridge.enable_icc` | `--icc` | Enable or Disable Inter Container Connectivity | + | `com.docker.network.bridge.host_binding_ipv4` | `--ip` | Default IP when binding container ports | + | `com.docker.network.driver.mtu` | `--mtu` | Set the containers network MTU | + | `com.docker.network.container_iface_prefix` | - | Set a custom prefix for container interfaces | - The following arguments can be passed to `docker network create` for any - network driver, again with their approximate equivalents to `docker daemon`. + The following arguments can be passed to `docker network create` for any + network driver, again with their approximate equivalents to `docker daemon`. - | Argument | Equivalent | Description | - |--------------|----------------|--------------------------------------------| - | `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | - | `--ip-range` | `--fixed-cidr` | Allocate IPs from a range | - | `--internal` | - | Restrict external access to the network | - | `--ipv6` | `--ipv6` | Enable IPv6 networking | - | `--subnet` | `--bip` | Subnet for network | + | Argument | Equivalent | Description | + |--------------|----------------|--------------------------------------------| + | `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | + | `--ip-range` | `--fixed-cidr` | Allocate IPs from a range | + | `--internal` | - | Restrict external access to the network | + | `--ipv6` | `--ipv6` | Enable IPv6 networking | + | `--subnet` | `--bip` | Subnet for network | - For example, let's use `-o` or `--opt` options to specify an IP address binding - when publishing ports: + For example, let's use `-o` or `--opt` options to specify an IP address binding + when publishing ports: - ```console - $ docker network create \ - -o "com.docker.network.bridge.host_binding_ipv4"="172.19.0.1" \ - simple-network - ``` + ```console + $ docker network create \ + -o "com.docker.network.bridge.host_binding_ipv4"="172.19.0.1" \ + simple-network + ``` - ### Network internal mode (--internal) + ### Network internal mode (--internal) {#internal} - By default, when you connect a container to an `overlay` network, Docker also - connects a bridge network to it to provide external connectivity. If you want - to create an externally isolated `overlay` network, you can specify the - `--internal` option. + By default, when you connect a container to an `overlay` network, Docker also + connects a bridge network to it to provide external connectivity. If you want + to create an externally isolated `overlay` network, you can specify the + `--internal` option. - ### Network ingress mode (--ingress) + ### Network ingress mode (--ingress) {#ingress} - You can create the network which will be used to provide the routing-mesh in the - swarm cluster. You do so by specifying `--ingress` when creating the network. Only - one ingress network can be created at the time. The network can be removed only - if no services depend on it. Any option available when creating an overlay network - is also available when creating the ingress network, besides the `--attachable` option. + You can create the network which will be used to provide the routing-mesh in the + swarm cluster. You do so by specifying `--ingress` when creating the network. Only + one ingress network can be created at the time. The network can be removed only + if no services depend on it. Any option available when creating an overlay network + is also available when creating the ingress network, besides the `--attachable` option. - ```console - $ docker network create -d overlay \ - --subnet=10.11.0.0/16 \ - --ingress \ - --opt com.docker.network.driver.mtu=9216 \ - --opt encrypted=true \ - my-ingress-network - ``` + ```console + $ docker network create -d overlay \ + --subnet=10.11.0.0/16 \ + --ingress \ + --opt com.docker.network.driver.mtu=9216 \ + --opt encrypted=true \ + my-ingress-network + ``` + + ### Run services on predefined networks + + You can create services on the predefined docker networks `bridge` and `host`. + + ```console + $ docker service create --name my-service \ + --network host \ + --replicas 2 \ + busybox top + ``` + + ### Swarm networks with local scope drivers + + You can create a swarm network with local scope network drivers. You do so + by promoting the network scope to `swarm` during the creation of the network. + You will then be able to use this network when creating services. + + ```console + $ docker network create -d bridge \ + --scope swarm \ + --attachable \ + swarm-network + ``` + + For network drivers which provide connectivity across hosts (ex. macvlan), if + node specific configurations are needed in order to plumb the network on each + host, you will supply that configuration via a configuration only network. + When you create the swarm scoped network, you will then specify the name of the + network which contains the configuration. + + + ```console + node1$ docker network create --config-only --subnet 192.168.100.0/24 --gateway 192.168.100.115 mv-config + node2$ docker network create --config-only --subnet 192.168.200.0/24 --gateway 192.168.200.202 mv-config + node1$ docker network create -d macvlan --scope swarm --config-from mv-config --attachable swarm-network + ``` deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_network_disconnect.yaml b/_data/engine-cli/docker_network_disconnect.yaml index 44793ab1a6..b5f8ada2c3 100644 --- a/_data/engine-cli/docker_network_disconnect.yaml +++ b/_data/engine-cli/docker_network_disconnect.yaml @@ -1,26 +1,38 @@ command: docker network disconnect short: Disconnect a container from a network long: |- - Disconnects a container from a network. The container must be running to - disconnect it from the network. + Disconnects a container from a network. The container must be running to + disconnect it from the network. usage: docker network disconnect [OPTIONS] NETWORK CONTAINER pname: docker network plink: docker_network.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force the container to disconnect from a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force the container to disconnect from a network + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker network disconnect multi-host-network container1 - ``` + ```console + $ docker network disconnect multi-host-network container1 + ``` deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_network_inspect.yaml b/_data/engine-cli/docker_network_inspect.yaml index 8c83d1940b..1bc4d4723f 100644 --- a/_data/engine-cli/docker_network_inspect.yaml +++ b/_data/engine-cli/docker_network_inspect.yaml @@ -1,31 +1,48 @@ command: docker network inspect short: Display detailed information on one or more networks long: |- - Returns information about one or more networks. By default, this command renders - all results in a JSON object. + Returns information about one or more networks. By default, this command renders + all results in a JSON object. usage: docker network inspect [OPTIONS] NETWORK [NETWORK...] pname: docker network plink: docker_network.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: verbose - shorthand: v - value_type: bool - default_value: "false" - description: Verbose output for diagnostics - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: verbose + shorthand: v + value_type: bool + default_value: "false" + description: Verbose output for diagnostics + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_network_ls.yaml b/_data/engine-cli/docker_network_ls.yaml index 0f234253b7..c38c234b8a 100644 --- a/_data/engine-cli/docker_network_ls.yaml +++ b/_data/engine-cli/docker_network_ls.yaml @@ -1,250 +1,282 @@ command: docker network ls -aliases: list +aliases: docker network ls, docker network list short: List networks long: |- - Lists all the networks the Engine `daemon` knows about. This includes the - networks that span across multiple hosts in a cluster. + Lists all the networks the Engine `daemon` knows about. This includes the + networks that span across multiple hosts in a cluster. usage: docker network ls [OPTIONS] pname: docker network plink: docker_network.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Provide filter values (e.g. 'driver=bridge') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print networks using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Do not truncate the output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display network IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Provide filter values (e.g. `driver=bridge`) + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Do not truncate the output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display network IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### List all networks + ### List all networks - ```console - $ docker network ls - NETWORK ID NAME DRIVER SCOPE - 7fca4eb8c647 bridge bridge local - 9f904ee27bf5 none null local - cf03ee007fb4 host host local - 78b03ee04fc4 multi-host overlay swarm - ``` + ```console + $ docker network ls + NETWORK ID NAME DRIVER SCOPE + 7fca4eb8c647 bridge bridge local + 9f904ee27bf5 none null local + cf03ee007fb4 host host local + 78b03ee04fc4 multi-host overlay swarm + ``` - Use the `--no-trunc` option to display the full network id: + Use the `--no-trunc` option to display the full network id: - ```console - $ docker network ls --no-trunc - NETWORK ID NAME DRIVER SCOPE - 18a2866682b85619a026c81b98a5e375bd33e1b0936a26cc497c283d27bae9b3 none null local - c288470c46f6c8949c5f7e5099b5b7947b07eabe8d9a27d79a9cbf111adcbf47 host host local - 7b369448dccbf865d397c8d2be0cda7cf7edc6b0945f77d2529912ae917a0185 bridge bridge local - 95e74588f40db048e86320c6526440c504650a1ff3e9f7d60a497c4d2163e5bd foo bridge local - 63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 dev bridge local - ``` + ```console + $ docker network ls --no-trunc + NETWORK ID NAME DRIVER SCOPE + 18a2866682b85619a026c81b98a5e375bd33e1b0936a26cc497c283d27bae9b3 none null local + c288470c46f6c8949c5f7e5099b5b7947b07eabe8d9a27d79a9cbf111adcbf47 host host local + 7b369448dccbf865d397c8d2be0cda7cf7edc6b0945f77d2529912ae917a0185 bridge bridge local + 95e74588f40db048e86320c6526440c504650a1ff3e9f7d60a497c4d2163e5bd foo bridge local + 63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 dev bridge local + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there - is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). - Multiple filter flags are combined as an `OR` filter. For example, - `-f type=custom -f type=builtin` returns both `custom` and `builtin` networks. + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there + is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). + Multiple filter flags are combined as an `OR` filter. For example, + `-f type=custom -f type=builtin` returns both `custom` and `builtin` networks. - The currently supported filters are: + The currently supported filters are: - * driver - * id (network's id) - * label (`label=` or `label==`) - * name (network's name) - * scope (`swarm|global|local`) - * type (`custom|builtin`) + * driver + * id (network's id) + * label (`label=` or `label==`) + * name (network's name) + * scope (`swarm|global|local`) + * type (`custom|builtin`) - #### Driver + #### Driver - The `driver` filter matches networks based on their driver. + The `driver` filter matches networks based on their driver. - The following example matches networks with the `bridge` driver: + The following example matches networks with the `bridge` driver: - ```console - $ docker network ls --filter driver=bridge - NETWORK ID NAME DRIVER SCOPE - db9db329f835 test1 bridge local - f6e212da9dfd test2 bridge local - ``` + ```console + $ docker network ls --filter driver=bridge + NETWORK ID NAME DRIVER SCOPE + db9db329f835 test1 bridge local + f6e212da9dfd test2 bridge local + ``` - #### ID + #### ID - The `id` filter matches on all or part of a network's ID. + The `id` filter matches on all or part of a network's ID. - The following filter matches all networks with an ID containing the - `63d1ff1f77b0...` string. + The following filter matches all networks with an ID containing the + `63d1ff1f77b0...` string. - ```console - $ docker network ls --filter id=63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 - NETWORK ID NAME DRIVER SCOPE - 63d1ff1f77b0 dev bridge local - ``` + ```console + $ docker network ls --filter id=63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 + NETWORK ID NAME DRIVER SCOPE + 63d1ff1f77b0 dev bridge local + ``` - You can also filter for a substring in an ID as this shows: + You can also filter for a substring in an ID as this shows: - ```console - $ docker network ls --filter id=95e74588f40d - NETWORK ID NAME DRIVER SCOPE - 95e74588f40d foo bridge local + ```console + $ docker network ls --filter id=95e74588f40d + NETWORK ID NAME DRIVER SCOPE + 95e74588f40d foo bridge local - $ docker network ls --filter id=95e - NETWORK ID NAME DRIVER SCOPE - 95e74588f40d foo bridge local - ``` + $ docker network ls --filter id=95e + NETWORK ID NAME DRIVER SCOPE + 95e74588f40d foo bridge local + ``` - #### Label + #### Label - The `label` filter matches networks based on the presence of a `label` alone or a `label` and a - value. + The `label` filter matches networks based on the presence of a `label` alone or a `label` and a + value. - The following filter matches networks with the `usage` label regardless of its value. + The following filter matches networks with the `usage` label regardless of its value. - ```console - $ docker network ls -f "label=usage" - NETWORK ID NAME DRIVER SCOPE - db9db329f835 test1 bridge local - f6e212da9dfd test2 bridge local - ``` + ```console + $ docker network ls -f "label=usage" + NETWORK ID NAME DRIVER SCOPE + db9db329f835 test1 bridge local + f6e212da9dfd test2 bridge local + ``` - The following filter matches networks with the `usage` label with the `prod` value. + The following filter matches networks with the `usage` label with the `prod` value. - ```console - $ docker network ls -f "label=usage=prod" - NETWORK ID NAME DRIVER SCOPE - f6e212da9dfd test2 bridge local - ``` + ```console + $ docker network ls -f "label=usage=prod" + NETWORK ID NAME DRIVER SCOPE + f6e212da9dfd test2 bridge local + ``` - #### Name + #### Name - The `name` filter matches on all or part of a network's name. + The `name` filter matches on all or part of a network's name. - The following filter matches all networks with a name containing the `foobar` string. + The following filter matches all networks with a name containing the `foobar` string. - ```console - $ docker network ls --filter name=foobar - NETWORK ID NAME DRIVER SCOPE - 06e7eef0a170 foobar bridge local - ``` + ```console + $ docker network ls --filter name=foobar + NETWORK ID NAME DRIVER SCOPE + 06e7eef0a170 foobar bridge local + ``` - You can also filter for a substring in a name as this shows: + You can also filter for a substring in a name as this shows: - ```console - $ docker network ls --filter name=foo - NETWORK ID NAME DRIVER SCOPE - 95e74588f40d foo bridge local - 06e7eef0a170 foobar bridge local - ``` + ```console + $ docker network ls --filter name=foo + NETWORK ID NAME DRIVER SCOPE + 95e74588f40d foo bridge local + 06e7eef0a170 foobar bridge local + ``` - #### Scope + #### Scope - The `scope` filter matches networks based on their scope. + The `scope` filter matches networks based on their scope. - The following example matches networks with the `swarm` scope: + The following example matches networks with the `swarm` scope: - ```console - $ docker network ls --filter scope=swarm - NETWORK ID NAME DRIVER SCOPE - xbtm0v4f1lfh ingress overlay swarm - ic6r88twuu92 swarmnet overlay swarm - ``` + ```console + $ docker network ls --filter scope=swarm + NETWORK ID NAME DRIVER SCOPE + xbtm0v4f1lfh ingress overlay swarm + ic6r88twuu92 swarmnet overlay swarm + ``` - The following example matches networks with the `local` scope: + The following example matches networks with the `local` scope: - ```console - $ docker network ls --filter scope=local - NETWORK ID NAME DRIVER SCOPE - e85227439ac7 bridge bridge local - 0ca0e19443ed host host local - ca13cc149a36 localnet bridge local - f9e115d2de35 none null local - ``` + ```console + $ docker network ls --filter scope=local + NETWORK ID NAME DRIVER SCOPE + e85227439ac7 bridge bridge local + 0ca0e19443ed host host local + ca13cc149a36 localnet bridge local + f9e115d2de35 none null local + ``` - #### Type + #### Type - The `type` filter supports two values; `builtin` displays predefined networks - (`bridge`, `none`, `host`), whereas `custom` displays user defined networks. + The `type` filter supports two values; `builtin` displays predefined networks + (`bridge`, `none`, `host`), whereas `custom` displays user defined networks. - The following filter matches all user defined networks: + The following filter matches all user defined networks: - ```console - $ docker network ls --filter type=custom - NETWORK ID NAME DRIVER SCOPE - 95e74588f40d foo bridge local - 63d1ff1f77b0 dev bridge local - ``` + ```console + $ docker network ls --filter type=custom + NETWORK ID NAME DRIVER SCOPE + 95e74588f40d foo bridge local + 63d1ff1f77b0 dev bridge local + ``` - By having this flag it allows for batch cleanup. For example, use this filter - to delete all user defined networks: + By having this flag it allows for batch cleanup. For example, use this filter + to delete all user defined networks: - ```console - $ docker network rm `docker network ls --filter type=custom -q` - ``` + ```console + $ docker network rm `docker network ls --filter type=custom -q` + ``` - A warning will be issued when trying to remove a network that has containers - attached. + A warning will be issued when trying to remove a network that has containers + attached. - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints networks output - using a Go template. + The formatting options (`--format`) pretty-prints networks output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |--------------|----------------------------------------------------------------------------------------| - | `.ID` | Network ID | - | `.Name` | Network name | - | `.Driver` | Network driver | - | `.Scope` | Network scope (local, global) | - | `.IPv6` | Whether IPv6 is enabled on the network or not. | - | `.Internal` | Whether the network is internal or not. | - | `.Labels` | All labels assigned to the network. | - | `.Label` | Value of a specific label for this network. For example `{{.Label "project.version"}}` | - | `.CreatedAt` | Time when the network was created | + | Placeholder | Description | + |--------------|----------------------------------------------------------------------------------------| + | `.ID` | Network ID | + | `.Name` | Network name | + | `.Driver` | Network driver | + | `.Scope` | Network scope (local, global) | + | `.IPv6` | Whether IPv6 is enabled on the network or not. | + | `.Internal` | Whether the network is internal or not. | + | `.Labels` | All labels assigned to the network. | + | `.Label` | Value of a specific label for this network. For example `{{.Label "project.version"}}` | + | `.CreatedAt` | Time when the network was created | - When using the `--format` option, the `network ls` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `network ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `ID` and `Driver` entries separated by a colon (`:`) for all networks: + The following example uses a template without headers and outputs the + `ID` and `Driver` entries separated by a colon (`:`) for all networks: - ```console - $ docker network ls --format "{{.ID}}: {{.Driver}}" - afaaab448eb2: bridge - d1584f8dc718: host - 391df270dc66: null - ``` + ```console + $ docker network ls --format "{{.ID}}: {{.Driver}}" + afaaab448eb2: bridge + d1584f8dc718: host + 391df270dc66: null + ``` + + To list all networks in JSON format, use the `json` directive: + + ```console + $ docker network ls --format json + {"CreatedAt":"2021-03-09 21:41:29.798999529 +0000 UTC","Driver":"bridge","ID":"f33ba176dd8e","IPv6":"false","Internal":"false","Labels":"","Name":"bridge","Scope":"local"} + {"CreatedAt":"2021-03-09 21:41:29.772806592 +0000 UTC","Driver":"host","ID":"caf47bb3ac70","IPv6":"false","Internal":"false","Labels":"","Name":"host","Scope":"local"} + {"CreatedAt":"2021-03-09 21:41:29.752212603 +0000 UTC","Driver":"null","ID":"9d096c122066","IPv6":"false","Internal":"false","Labels":"","Name":"none","Scope":"local"} + ``` deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_network_prune.yaml b/_data/engine-cli/docker_network_prune.yaml index 7434b05464..4b71242fec 100644 --- a/_data/engine-cli/docker_network_prune.yaml +++ b/_data/engine-cli/docker_network_prune.yaml @@ -1,94 +1,108 @@ command: docker network prune short: Remove all unused networks long: |- - Remove all unused networks. Unused networks are those which are not referenced - by any containers. + Remove all unused networks. Unused networks are those which are not referenced + by any containers. usage: docker network prune [OPTIONS] pname: docker network plink: docker_network.yaml options: -- option: filter - value_type: filter - description: Provide filter values (e.g. 'until=') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Do not prompt for confirmation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + value_type: filter + description: Provide filter values (e.g. `until=`) + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Do not prompt for confirmation + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker network prune + ```console + $ docker network prune - WARNING! This will remove all custom networks not used by at least one container. - Are you sure you want to continue? [y/N] y - Deleted Networks: - n1 - n2 - ``` + WARNING! This will remove all custom networks not used by at least one container. + Are you sure you want to continue? [y/N] y + Deleted Networks: + n1 + n2 + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - 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 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: + The currently supported filters are: - * until (``) - only remove networks created before given timestamp - * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove networks with (or without, in case `label!=...` is used) the specified labels. + * until (``) - only remove networks created before given timestamp + * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove networks with (or without, in case `label!=...` is used) the specified labels. - The `until` filter can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed - relative to the daemon machine’s time. Supported formats for date - formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local - timezone on the daemon will be used if you do not provide either a `Z` or a - `+-00:00` timezone offset at the end of the timestamp. When providing Unix - timestamps enter seconds[.nanoseconds], where seconds is the number of seconds - that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap - seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a - fraction of a second no more than nine digits long. + The `until` filter can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the daemon machine’s time. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the daemon will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. - The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), - which removes networks with the specified labels. The other - format is the `label!=...` (`label!=` or `label!==`), which removes - networks without the specified labels. + The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), + which removes networks with the specified labels. The other + format is the `label!=...` (`label!=` or `label!==`), which removes + networks without the specified labels. - The following removes networks created more than 5 minutes ago. Note that - system networks such as `bridge`, `host`, and `none` will never be pruned: + The following removes networks created more than 5 minutes ago. Note that + system networks such as `bridge`, `host`, and `none` will never be pruned: - ```console - $ docker network ls + ```console + $ docker network ls - NETWORK ID NAME DRIVER SCOPE - 7430df902d7a bridge bridge local - ea92373fd499 foo-1-day-ago bridge local - ab53663ed3c7 foo-1-min-ago bridge local - 97b91972bc3b host host local - f949d337b1f5 none null local + NETWORK ID NAME DRIVER SCOPE + 7430df902d7a bridge bridge local + ea92373fd499 foo-1-day-ago bridge local + ab53663ed3c7 foo-1-min-ago bridge local + 97b91972bc3b host host local + f949d337b1f5 none null local - $ docker network prune --force --filter until=5m + $ docker network prune --force --filter until=5m - Deleted Networks: - foo-1-day-ago + Deleted Networks: + foo-1-day-ago - $ docker network ls + $ docker network ls - NETWORK ID NAME DRIVER SCOPE - 7430df902d7a bridge bridge local - ab53663ed3c7 foo-1-min-ago bridge local - 97b91972bc3b host host local - f949d337b1f5 none null local - ``` + NETWORK ID NAME DRIVER SCOPE + 7430df902d7a bridge bridge local + ab53663ed3c7 foo-1-min-ago bridge local + 97b91972bc3b host host local + f949d337b1f5 none null local + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_network_rm.yaml b/_data/engine-cli/docker_network_rm.yaml index c2cfe3f1cc..6c8986f39d 100644 --- a/_data/engine-cli/docker_network_rm.yaml +++ b/_data/engine-cli/docker_network_rm.yaml @@ -1,35 +1,58 @@ command: docker network rm -aliases: remove +aliases: docker network rm, docker network remove short: Remove one or more networks long: |- - Removes one or more networks by name or identifier. To remove a network, - you must first disconnect any containers connected to it. + Removes one or more networks by name or identifier. To remove a network, + you must first disconnect any containers connected to it. usage: docker network rm NETWORK [NETWORK...] pname: docker network plink: docker_network.yaml +options: + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Do not error if the network does not exist + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Remove a network + ### Remove a network - To remove the network named 'my-network': + To remove the network named 'my-network': - ```console - $ docker network rm my-network - ``` + ```console + $ docker network rm my-network + ``` - ### Remove multiple networks + ### Remove multiple networks - To delete multiple networks in a single `docker network rm` command, provide - multiple network names or ids. The following example deletes a network with id - `3695c422697f` and a network named `my-network`: + To delete multiple networks in a single `docker network rm` command, provide + multiple network names or ids. The following example deletes a network with id + `3695c422697f` and a network named `my-network`: - ```console - $ docker network rm 3695c422697f my-network - ``` + ```console + $ docker network rm 3695c422697f my-network + ``` - When you specify multiple networks, the command attempts to delete each in turn. - If the deletion of one network fails, the command continues to the next on the - list and tries to delete that. The command reports success or failure for each - deletion. + When you specify multiple networks, the command attempts to delete each in turn. + If the deletion of one network fails, the command continues to the next on the + list and tries to delete that. The command reports success or failure for each + deletion. deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_node.yaml b/_data/engine-cli/docker_node.yaml index ca3e52bf5f..5549905d70 100644 --- a/_data/engine-cli/docker_node.yaml +++ b/_data/engine-cli/docker_node.yaml @@ -5,21 +5,32 @@ usage: docker node pname: docker plink: docker.yaml cname: -- docker node demote -- docker node inspect -- docker node ls -- docker node promote -- docker node ps -- docker node rm -- docker node update + - docker node demote + - docker node inspect + - docker node ls + - docker node promote + - docker node ps + - docker node rm + - docker node update clink: -- docker_node_demote.yaml -- docker_node_inspect.yaml -- docker_node_ls.yaml -- docker_node_promote.yaml -- docker_node_ps.yaml -- docker_node_rm.yaml -- docker_node_update.yaml + - docker_node_demote.yaml + - docker_node_inspect.yaml + - docker_node_ls.yaml + - docker_node_promote.yaml + - docker_node_ps.yaml + - docker_node_rm.yaml + - docker_node_update.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_node_demote.yaml b/_data/engine-cli/docker_node_demote.yaml index 8f879c4b6f..d44713d90c 100644 --- a/_data/engine-cli/docker_node_demote.yaml +++ b/_data/engine-cli/docker_node_demote.yaml @@ -1,20 +1,31 @@ command: docker node demote short: Demote one or more nodes from manager in the swarm long: |- - Demotes an existing manager so that it is no longer a manager. + Demotes an existing manager so that it is no longer a manager. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the [Swarm mode - > section](https://docs.docker.com/engine/swarm/) in the documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the [Swarm mode + > section](/engine/swarm/) in the documentation. usage: docker node demote NODE [NODE...] pname: docker node plink: docker_node.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker node demote - ``` + ```console + $ docker node demote + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_node_inspect.yaml b/_data/engine-cli/docker_node_inspect.yaml index bcf540e9e3..fd2ffd1847 100644 --- a/_data/engine-cli/docker_node_inspect.yaml +++ b/_data/engine-cli/docker_node_inspect.yaml @@ -1,168 +1,186 @@ command: docker node inspect short: Display detailed information on one or more nodes long: |- - Returns information about a node. By default, this command renders all results - in a JSON array. You can specify an alternate format to execute a - given template for each result. Go's - [text/template](https://golang.org/pkg/text/template/) package describes all the - details of the format. + Returns information about a node. By default, this command renders all results + in a JSON array. You can specify an alternate format to execute a + given template for each result. Go's + [text/template](https://golang.org/pkg/text/template/) package describes all the + details of the format. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker node inspect [OPTIONS] self|NODE [NODE...] pname: docker node plink: docker_node.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pretty - value_type: bool - default_value: "false" - description: Print the information in a human friendly format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pretty + value_type: bool + default_value: "false" + description: Print the information in a human friendly format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Inspect a node + ### Inspect a node - ```console - $ docker node inspect swarm-manager - ``` + ```console + $ docker node inspect swarm-manager + ``` - ```json - [ - { - "ID": "e216jshn25ckzbvmwlnh5jr3g", - "Version": { - "Index": 10 - }, - "CreatedAt": "2017-05-16T22:52:44.9910662Z", - "UpdatedAt": "2017-05-16T22:52:45.230878043Z", - "Spec": { - "Role": "manager", - "Availability": "active" - }, - "Description": { - "Hostname": "swarm-manager", - "Platform": { - "Architecture": "x86_64", - "OS": "linux" + ```json + [ + { + "ID": "e216jshn25ckzbvmwlnh5jr3g", + "Version": { + "Index": 10 }, - "Resources": { - "NanoCPUs": 1000000000, - "MemoryBytes": 1039843328 + "CreatedAt": "2017-05-16T22:52:44.9910662Z", + "UpdatedAt": "2017-05-16T22:52:45.230878043Z", + "Spec": { + "Role": "manager", + "Availability": "active" }, - "Engine": { - "EngineVersion": "17.06.0-ce", - "Plugins": [ - { - "Type": "Volume", - "Name": "local" - }, - { - "Type": "Network", - "Name": "overlay" - }, - { - "Type": "Network", - "Name": "null" - }, - { - "Type": "Network", - "Name": "host" - }, - { - "Type": "Network", - "Name": "bridge" - }, - { - "Type": "Network", - "Name": "overlay" - } - ] + "Description": { + "Hostname": "swarm-manager", + "Platform": { + "Architecture": "x86_64", + "OS": "linux" + }, + "Resources": { + "NanoCPUs": 1000000000, + "MemoryBytes": 1039843328 + }, + "Engine": { + "EngineVersion": "17.06.0-ce", + "Plugins": [ + { + "Type": "Volume", + "Name": "local" + }, + { + "Type": "Network", + "Name": "overlay" + }, + { + "Type": "Network", + "Name": "null" + }, + { + "Type": "Network", + "Name": "host" + }, + { + "Type": "Network", + "Name": "bridge" + }, + { + "Type": "Network", + "Name": "overlay" + } + ] + }, + "TLSInfo": { + "TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBazCCARCgAwIBAgIUOzgqU4tA2q5Yv1HnkzhSIwGyIBswCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAyMDAyNDAwWhcNMzcwNDI3MDAy\nNDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABMbiAmET+HZyve35ujrnL2kOLBEQhFDZ5MhxAuYs96n796sFlfxTxC1lM/2g\nAh8DI34pm3JmHgZxeBPKUURJHKWjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBS3sjTJOcXdkls6WSY2rTx1KIJueTAKBggqhkjO\nPQQDAgNJADBGAiEAoeVWkaXgSUAucQmZ3Yhmx22N/cq1EPBgYHOBZmHt0NkCIQC3\nzONcJ/+WA21OXtb+vcijpUOXtNjyHfcox0N8wsLDqQ==\n-----END CERTIFICATE-----\n", + "CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh", + "CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExuICYRP4dnK97fm6OucvaQ4sERCEUNnkyHEC5iz3qfv3qwWV/FPELWUz/aACHwMjfimbcmYeBnF4E8pRREkcpQ==" + } }, - "TLSInfo": { - "TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBazCCARCgAwIBAgIUOzgqU4tA2q5Yv1HnkzhSIwGyIBswCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAyMDAyNDAwWhcNMzcwNDI3MDAy\nNDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABMbiAmET+HZyve35ujrnL2kOLBEQhFDZ5MhxAuYs96n796sFlfxTxC1lM/2g\nAh8DI34pm3JmHgZxeBPKUURJHKWjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBS3sjTJOcXdkls6WSY2rTx1KIJueTAKBggqhkjO\nPQQDAgNJADBGAiEAoeVWkaXgSUAucQmZ3Yhmx22N/cq1EPBgYHOBZmHt0NkCIQC3\nzONcJ/+WA21OXtb+vcijpUOXtNjyHfcox0N8wsLDqQ==\n-----END CERTIFICATE-----\n", - "CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh", - "CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExuICYRP4dnK97fm6OucvaQ4sERCEUNnkyHEC5iz3qfv3qwWV/FPELWUz/aACHwMjfimbcmYeBnF4E8pRREkcpQ==" + "Status": { + "State": "ready", + "Addr": "168.0.32.137" + }, + "ManagerStatus": { + "Leader": true, + "Reachability": "reachable", + "Addr": "168.0.32.137:2377" } - }, - "Status": { - "State": "ready", - "Addr": "168.0.32.137" - }, - "ManagerStatus": { - "Leader": true, - "Reachability": "reachable", - "Addr": "168.0.32.137:2377" } - } - ] - ``` + ] + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - ```console - $ docker node inspect --format '{{ .ManagerStatus.Leader }}' self + ```console + $ docker node inspect --format '{{ .ManagerStatus.Leader }}' self - false - ``` + false + ``` - Use `--format=pretty` or the `--pretty` shorthand to pretty-print the output: + Use `--format=pretty` or the `--pretty` shorthand to pretty-print the output: - ```console - $ docker node inspect --format=pretty self + ```console + $ docker node inspect --format=pretty self - ID: e216jshn25ckzbvmwlnh5jr3g - Hostname: swarm-manager - Joined at: 2017-05-16 22:52:44.9910662 +0000 utc - Status: - State: Ready - Availability: Active - Address: 172.17.0.2 - Manager Status: - Address: 172.17.0.2:2377 - Raft Status: Reachable - Leader: Yes - Platform: - Operating System: linux - Architecture: x86_64 - Resources: - CPUs: 4 - Memory: 7.704 GiB - Plugins: - Network: overlay, bridge, null, host, overlay - Volume: local - Engine Version: 17.06.0-ce - TLS Info: - TrustRoot: - -----BEGIN CERTIFICATE----- - MIIBazCCARCgAwIBAgIUOzgqU4tA2q5Yv1HnkzhSIwGyIBswCgYIKoZIzj0EAwIw - EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAyMDAyNDAwWhcNMzcwNDI3MDAy - NDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH - A0IABMbiAmET+HZyve35ujrnL2kOLBEQhFDZ5MhxAuYs96n796sFlfxTxC1lM/2g - Ah8DI34pm3JmHgZxeBPKUURJHKWjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB - Af8EBTADAQH/MB0GA1UdDgQWBBS3sjTJOcXdkls6WSY2rTx1KIJueTAKBggqhkjO - PQQDAgNJADBGAiEAoeVWkaXgSUAucQmZ3Yhmx22N/cq1EPBgYHOBZmHt0NkCIQC3 - zONcJ/+WA21OXtb+vcijpUOXtNjyHfcox0N8wsLDqQ== - -----END CERTIFICATE----- + ID: e216jshn25ckzbvmwlnh5jr3g + Hostname: swarm-manager + Joined at: 2017-05-16 22:52:44.9910662 +0000 utc + Status: + State: Ready + Availability: Active + Address: 172.17.0.2 + Manager Status: + Address: 172.17.0.2:2377 + Raft Status: Reachable + Leader: Yes + Platform: + Operating System: linux + Architecture: x86_64 + Resources: + CPUs: 4 + Memory: 7.704 GiB + Plugins: + Network: overlay, bridge, null, host, overlay + Volume: local + Engine Version: 17.06.0-ce + TLS Info: + TrustRoot: + -----BEGIN CERTIFICATE----- + MIIBazCCARCgAwIBAgIUOzgqU4tA2q5Yv1HnkzhSIwGyIBswCgYIKoZIzj0EAwIw + EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAyMDAyNDAwWhcNMzcwNDI3MDAy + NDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH + A0IABMbiAmET+HZyve35ujrnL2kOLBEQhFDZ5MhxAuYs96n796sFlfxTxC1lM/2g + Ah8DI34pm3JmHgZxeBPKUURJHKWjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB + Af8EBTADAQH/MB0GA1UdDgQWBBS3sjTJOcXdkls6WSY2rTx1KIJueTAKBggqhkjO + PQQDAgNJADBGAiEAoeVWkaXgSUAucQmZ3Yhmx22N/cq1EPBgYHOBZmHt0NkCIQC3 + zONcJ/+WA21OXtb+vcijpUOXtNjyHfcox0N8wsLDqQ== + -----END CERTIFICATE----- - Issuer Public Key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExuICYRP4dnK97fm6OucvaQ4sERCEUNnkyHEC5iz3qfv3qwWV/FPELWUz/aACHwMjfimbcmYeBnF4E8pRREkcpQ== - Issuer Subject: MBMxETAPBgNVBAMTCHN3YXJtLWNh - ``` + Issuer Public Key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExuICYRP4dnK97fm6OucvaQ4sERCEUNnkyHEC5iz3qfv3qwWV/FPELWUz/aACHwMjfimbcmYeBnF4E8pRREkcpQ== + Issuer Subject: MBMxETAPBgNVBAMTCHN3YXJtLWNh + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_node_ls.yaml b/_data/engine-cli/docker_node_ls.yaml index a321eaae62..2002c07b4b 100644 --- a/_data/engine-cli/docker_node_ls.yaml +++ b/_data/engine-cli/docker_node_ls.yaml @@ -1,215 +1,243 @@ command: docker node ls -aliases: list +aliases: docker node ls, docker node list short: List nodes in the swarm long: |- - Lists all the nodes that the Docker Swarm manager knows about. You can filter - using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section - for more information about available filter options. + Lists all the nodes that the Docker Swarm manager knows about. You can filter + using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section + for more information about available filter options. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker node ls [OPTIONS] pname: docker node plink: docker_node.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print nodes using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker node ls + ```console + $ docker node ls - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active - 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active - e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active + 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active + e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader + ``` - > **Note** - > - > In the above example output, there is a hidden column of `.Self` that indicates - > if the node is the same node as the current docker daemon. A `*` (e.g., - > `e216jshn25ckzbvmwlnh5jr3g *`) means this node is the current docker daemon. + > **Note** + > + > In the above example output, there is a hidden column of `.Self` that indicates + > if the node is the same node as the current docker daemon. A `*` (e.g., + > `e216jshn25ckzbvmwlnh5jr3g *`) means this node is the current docker daemon. - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--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 filtering flag (`-f` or `--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: + The currently supported filters are: - * [id](#id) - * [label](#label) - * [node.label](#nodelabel) - * [membership](#membership) - * [name](#name) - * [role](#role) + * [id](#id) + * [label](#label) + * [node.label](#nodelabel) + * [membership](#membership) + * [name](#name) + * [role](#role) - #### id + #### id - The `id` filter matches all or part of a node's id. + The `id` filter matches all or part of a node's id. - ```console - $ docker node ls -f id=1 + ```console + $ docker node ls -f id=1 - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active + ``` - #### label + #### label - The `label` filter matches nodes based on engine labels and on the presence of a - `label` alone or a `label` and a value. Engine labels are configured in - the [daemon configuration](dockerd.md#daemon-configuration-file). To filter on - Swarm `node` labels, use [`node.label` instead](#nodelabel). + The `label` filter matches nodes based on engine labels and on the presence of a + `label` alone or a `label` and a value. Engine labels are configured in + the [daemon configuration](dockerd.md#daemon-configuration-file). To filter on + Swarm `node` labels, use [`node.label` instead](#nodelabel). - The following filter matches nodes with the `foo` label regardless of its value. + The following filter matches nodes with the `foo` label regardless of its value. - ```console - $ docker node ls -f "label=foo" + ```console + $ docker node ls -f "label=foo" - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active + ``` - #### node.label + #### node.label - The `node.label` filter matches nodes based on node labels and on the presence - of a `node.label` alone or a `node.label` and a value. + The `node.label` filter matches nodes based on node labels and on the presence + of a `node.label` alone or a `node.label` and a value. - The following filter updates nodes to have a `region` node label: + The following filter updates nodes to have a `region` node label: - ```console - $ docker node update --label-add region=region-a swarm-test-01 - $ docker node update --label-add region=region-a swarm-test-02 - $ docker node update --label-add region=region-b swarm-test-03 - $ docker node update --label-add region=region-b swarm-test-04 - ``` + ```console + $ docker node update --label-add region=region-a swarm-test-01 + $ docker node update --label-add region=region-a swarm-test-02 + $ docker node update --label-add region=region-b swarm-test-03 + $ docker node update --label-add region=region-b swarm-test-04 + ``` - Show all nodes that have a `region` node label set: + Show all nodes that have a `region` node label set: - ```console - $ docker node ls --filter node.label=region + ```console + $ docker node ls --filter node.label=region - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION - yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 20.10.2 - 2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 20.10.2 - hc0pu7ntc7s4uvj4pv7z7pz15 swarm-test-03 Ready Active Reachable 20.10.2 - n41b2cijmhifxxvz56vwrs12q swarm-test-04 Ready Active 20.10.2 - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION + yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 20.10.2 + 2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 20.10.2 + hc0pu7ntc7s4uvj4pv7z7pz15 swarm-test-03 Ready Active Reachable 20.10.2 + n41b2cijmhifxxvz56vwrs12q swarm-test-04 Ready Active 20.10.2 + ``` - Show all nodes that have a `region` node label, with value `region-a`: + Show all nodes that have a `region` node label, with value `region-a`: - ```console - $ docker node ls --filter node.label=region=region-a + ```console + $ docker node ls --filter node.label=region=region-a - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION - yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 20.10.2 - 2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 20.10.2 - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION + yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 20.10.2 + 2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 20.10.2 + ``` - #### membership + #### membership - The `membership` filter matches nodes based on the presence of a `membership` and a value - `accepted` or `pending`. + The `membership` filter matches nodes based on the presence of a `membership` and a value + `accepted` or `pending`. - The following filter matches nodes with the `membership` of `accepted`. + The following filter matches nodes with the `membership` of `accepted`. - ```console - $ docker node ls -f "membership=accepted" + ```console + $ docker node ls -f "membership=accepted" - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active - 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active + 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active + ``` - #### name + #### name - The `name` filter matches on all or part of a node hostname. + The `name` filter matches on all or part of a node hostname. - The following filter matches the nodes with a name equal to `swarm-master` string. + The following filter matches the nodes with a name equal to `swarm-master` string. - ```console - $ docker node ls -f name=swarm-manager1 + ```console + $ docker node ls -f name=swarm-manager1 - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader + ``` - #### role + #### role - The `role` filter matches nodes based on the presence of a `role` and a value `worker` or `manager`. + The `role` filter matches nodes based on the presence of a `role` and a value `worker` or `manager`. - The following filter matches nodes with the `manager` role. + The following filter matches nodes with the `manager` role. - ```console - $ docker node ls -f "role=manager" + ```console + $ docker node ls -f "role=manager" - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints nodes output - using a Go template. + The formatting options (`--format`) pretty-prints nodes output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |------------------|-------------------------------------------------------------------------------------------------------| - | `.ID` | Node ID | - | `.Self` | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) | - | `.Hostname` | Node hostname | - | `.Status` | Node status | - | `.Availability` | Node availability ("active", "pause", or "drain") | - | `.ManagerStatus` | Manager status of the node | - | `.TLSStatus` | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA) | - | `.EngineVersion` | Engine version | + | Placeholder | Description | + |------------------|-------------------------------------------------------------------------------------------------------| + | `.ID` | Node ID | + | `.Self` | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) | + | `.Hostname` | Node hostname | + | `.Status` | Node status | + | `.Availability` | Node availability ("active", "pause", or "drain") | + | `.ManagerStatus` | Manager status of the node | + | `.TLSStatus` | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA) | + | `.EngineVersion` | Engine version | - When using the `--format` option, the `node ls` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `node ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `ID`, `Hostname`, and `TLS Status` entries separated by a colon (`:`) for all - nodes: + The following example uses a template without headers and outputs the + `ID`, `Hostname`, and `TLS Status` entries separated by a colon (`:`) for all + nodes: - ```console - $ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}" + ```console + $ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}" - e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready - 35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation - ``` + e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready + 35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation + ``` + + To list all nodes in JSON format, use the `json` directive: + ```console + $ docker node ls --format json + {"Availability":"Active","EngineVersion":"20.10.5","Hostname":"docker-desktop","ID":"k8f4w7qtzpj5sqzclcqafw35g","ManagerStatus":"Leader","Self":true,"Status":"Ready","TLSStatus":"Ready"} + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_node_promote.yaml b/_data/engine-cli/docker_node_promote.yaml index 1d641532cf..9a4e70da56 100644 --- a/_data/engine-cli/docker_node_promote.yaml +++ b/_data/engine-cli/docker_node_promote.yaml @@ -1,21 +1,32 @@ command: docker node promote short: Promote one or more nodes to manager in the swarm long: |- - Promotes a node to manager. This command can only be executed on a manager node. + Promotes a node to manager. This command can only be executed on a manager node. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker node promote NODE [NODE...] pname: docker node plink: docker_node.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker node promote - ``` + ```console + $ docker node promote + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_node_ps.yaml b/_data/engine-cli/docker_node_ps.yaml index b3dff83a7d..de4d457569 100644 --- a/_data/engine-cli/docker_node_ps.yaml +++ b/_data/engine-cli/docker_node_ps.yaml @@ -1,170 +1,188 @@ command: docker node ps short: List tasks running on one or more nodes, defaults to current node long: |- - Lists all the tasks on a Node that Docker knows about. You can filter using the - `-f` or `--filter` flag. Refer to the [filtering](#filter) section for more - information about available filter options. + Lists all the tasks on a Node that Docker knows about. You can filter using the + `-f` or `--filter` flag. Refer to the [filtering](#filter) section for more + information about available filter options. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker node ps [OPTIONS] [NODE...] pname: docker node plink: docker_node.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print tasks using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-resolve - value_type: bool - default_value: "false" - description: Do not map IDs to Names - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Do not truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display task IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: Pretty-print tasks using a Go template + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-resolve + value_type: bool + default_value: "false" + description: Do not map IDs to Names + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Do not truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display task IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker node ps swarm-manager1 + ```console + $ docker node ps swarm-manager1 - NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours - redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds - ``` + NAME IMAGE NODE DESIRED STATE CURRENT STATE + redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours + redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds + redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds + redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds + redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--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 filtering flag (`-f` or `--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: + The currently supported filters are: - * [name](#name) - * [id](#id) - * [label](#label) - * [desired-state](#desired-state) + * [name](#name) + * [id](#id) + * [label](#label) + * [desired-state](#desired-state) - #### name + #### name - The `name` filter matches on all or part of a task's name. + The `name` filter matches on all or part of a task's name. - The following filter matches all tasks with a name containing the `redis` string. + The following filter matches all tasks with a name containing the `redis` string. - ```console - $ docker node ps -f name=redis swarm-manager1 + ```console + $ docker node ps -f name=redis swarm-manager1 - NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours - redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds - ``` + NAME IMAGE NODE DESIRED STATE CURRENT STATE + redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours + redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds + redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds + redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds + redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds + ``` - #### id + #### id - The `id` filter matches a task's id. + The `id` filter matches a task's id. - ```console - $ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1 + ```console + $ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1 - NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds - ``` + NAME IMAGE NODE DESIRED STATE CURRENT STATE + redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds + ``` - #### label + #### label - The `label` filter matches tasks based on the presence of a `label` alone or a `label` and a - value. + The `label` filter matches tasks based on the presence of a `label` alone or a `label` and a + value. - The following filter matches tasks with the `usage` label regardless of its value. + The following filter matches tasks with the `usage` label regardless of its value. - ```console - $ docker node ps -f "label=usage" + ```console + $ docker node ps -f "label=usage" - NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 10 minutes - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 9 minutes - ``` + NAME IMAGE NODE DESIRED STATE CURRENT STATE + redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 10 minutes + redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 9 minutes + ``` - #### desired-state + #### desired-state - The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`. + The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`. - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints tasks output - using a Go template. + The formatting options (`--format`) pretty-prints tasks output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |-----------------|------------------------------------------------------------------| - | `.ID` | Task ID | - | `.Name` | Task name | - | `.Image` | Task image | - | `.Node` | Node ID | - | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | - | `.CurrentState` | Current state of the task | - | `.Error` | Error | - | `.Ports` | Task published ports | + | Placeholder | Description | + |-----------------|------------------------------------------------------------------| + | `.ID` | Task ID | + | `.Name` | Task name | + | `.Image` | Task image | + | `.Node` | Node ID | + | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | + | `.CurrentState` | Current state of the task | + | `.Error` | Error | + | `.Ports` | Task published ports | - When using the `--format` option, the `node ps` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `node ps` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `Name` and `Image` entries separated by a colon (`:`) for all tasks: + The following example uses a template without headers and outputs the + `Name` and `Image` entries separated by a colon (`:`) for all tasks: - ```console - $ docker node ps --format "{{.Name}}: {{.Image}}" + ```console + $ docker node ps --format "{{.Name}}: {{.Image}}" - top.1: busybox - top.2: busybox - top.3: busybox - ``` + top.1: busybox + top.2: busybox + top.3: busybox + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_node_rm.yaml b/_data/engine-cli/docker_node_rm.yaml index 99c1c8f075..c8b37173fa 100644 --- a/_data/engine-cli/docker_node_rm.yaml +++ b/_data/engine-cli/docker_node_rm.yaml @@ -1,65 +1,78 @@ command: docker node rm -aliases: remove +aliases: docker node rm, docker node remove short: Remove one or more nodes from the swarm long: |- - Removes the specified nodes from a swarm. + Removes the specified nodes from a swarm. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker node rm [OPTIONS] NODE [NODE...] pname: docker node plink: docker_node.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force remove a node from the swarm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force remove a node from the swarm + details_url: '#force' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Remove a stopped node from the swarm + ### Remove a stopped node from the swarm - ```console - $ docker node rm swarm-node-02 + ```console + $ docker node rm swarm-node-02 - Node swarm-node-02 removed from swarm - ``` + Node swarm-node-02 removed from swarm + ``` - ### Attempt to remove a running node from a swarm + ### Attempt to remove a running node from a swarm - Removes the specified nodes from the swarm, but only if the nodes are in the - down state. If you attempt to remove an active node you will receive an error: + Removes the specified nodes from the swarm, but only if the nodes are in the + down state. If you attempt to remove an active node you will receive an error: - ```non - $ docker node rm swarm-node-03 + ```non + $ docker node rm swarm-node-03 - Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not - down and can't be removed - ``` + Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not + down and can't be removed + ``` - ### Forcibly remove an inaccessible node from a swarm (--force) + ### Forcibly remove an inaccessible node from a swarm (--force) {#force} - If you lose access to a worker node or need to shut it down because it has been - compromised or is not behaving as expected, you can use the `--force` option. - This may cause transient errors or interruptions, depending on the type of task - being run on the node. + If you lose access to a worker node or need to shut it down because it has been + compromised or is not behaving as expected, you can use the `--force` option. + This may cause transient errors or interruptions, depending on the type of task + being run on the node. - ```console - $ docker node rm --force swarm-node-03 + ```console + $ docker node rm --force swarm-node-03 - Node swarm-node-03 removed from swarm - ``` + Node swarm-node-03 removed from swarm + ``` - A manager node must be demoted to a worker node (using `docker node demote`) - before you can remove it from the swarm. + A manager node must be demoted to a worker node (using `docker node demote`) + before you can remove it from the swarm. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_node_update.yaml b/_data/engine-cli/docker_node_update.yaml index c2a18feef0..ced77c9529 100644 --- a/_data/engine-cli/docker_node_update.yaml +++ b/_data/engine-cli/docker_node_update.yaml @@ -1,83 +1,99 @@ command: docker node update short: Update a node long: |- - Update metadata about a node, such as its availability, labels, or roles. + Update metadata about a node, such as its availability, labels, or roles. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker node update [OPTIONS] NODE pname: docker node plink: docker_node.yaml options: -- option: availability - value_type: string - description: Availability of the node ("active"|"pause"|"drain") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label-add - value_type: list - description: Add or update a node label (key=value) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label-rm - value_type: list - description: Remove a node label if exists - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: role - value_type: string - description: Role of the node ("worker"|"manager") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: availability + value_type: string + description: Availability of the node (`active`, `pause`, `drain`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label-add + value_type: list + description: Add or update a node label (`key=value`) + details_url: '#label-add' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label-rm + value_type: list + description: Remove a node label if exists + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: role + value_type: string + description: Role of the node (`worker`, `manager`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Add label metadata to a node (--label-add) + ### Add label metadata to a node (--label-add) {#label-add} - Add metadata to a swarm node using node labels. You can specify a node label as - a key with an empty value: + Add metadata to a swarm node using node labels. You can specify a node label as + a key with an empty value: - ``` bash - $ docker node update --label-add foo worker1 - ``` + ``` bash + $ docker node update --label-add foo worker1 + ``` - To add multiple labels to a node, pass the `--label-add` flag for each label: + To add multiple labels to a node, pass the `--label-add` flag for each label: - ```console - $ docker node update --label-add foo --label-add bar worker1 - ``` + ```console + $ docker node update --label-add foo --label-add bar worker1 + ``` - When you [create a service](service_create.md), - you can use node labels as a constraint. A constraint limits the nodes where the - scheduler deploys tasks for a service. + When you [create a service](service_create.md), + you can use node labels as a constraint. A constraint limits the nodes where the + scheduler deploys tasks for a service. - For example, to add a `type` label to identify nodes where the scheduler should - deploy message queue service tasks: + For example, to add a `type` label to identify nodes where the scheduler should + deploy message queue service tasks: - ``` bash - $ docker node update --label-add type=queue worker1 - ``` + ``` bash + $ docker node update --label-add type=queue worker1 + ``` - The labels you set for nodes using `docker node update` apply only to the node - entity within the swarm. Do not confuse them with the docker daemon labels for - [dockerd](dockerd.md). + The labels you set for nodes using `docker node update` apply only to the node + entity within the swarm. Do not confuse them with the docker daemon labels for + [dockerd](dockerd.md). - For more information about labels, refer to [apply custom - metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/). + For more information about labels, refer to [apply custom + metadata](/engine/userguide/labels-custom-metadata/). deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_pause.yaml b/_data/engine-cli/docker_pause.yaml index bb8a045ee9..1cc28c5930 100644 --- a/_data/engine-cli/docker_pause.yaml +++ b/_data/engine-cli/docker_pause.yaml @@ -1,23 +1,35 @@ command: docker pause +aliases: docker container pause, docker pause short: Pause all processes within one or more containers long: |- - The `docker pause` command suspends all processes in the specified containers. - On Linux, this uses the freezer cgroup. 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. On Windows, only Hyper-V - containers can be paused. + The `docker pause` command suspends all processes in the specified containers. + On Linux, this uses the freezer cgroup. 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. On Windows, only Hyper-V + containers can be paused. - See the - [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) - for further details. + See the + [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) + for further details. usage: docker pause CONTAINER [CONTAINER...] pname: docker plink: docker.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker pause my_container - ``` + ```console + $ docker pause my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_plugin.yaml b/_data/engine-cli/docker_plugin.yaml index 23b9087eef..5ccb1a81f0 100644 --- a/_data/engine-cli/docker_plugin.yaml +++ b/_data/engine-cli/docker_plugin.yaml @@ -5,27 +5,38 @@ usage: docker plugin pname: docker plink: docker.yaml cname: -- docker plugin create -- docker plugin disable -- docker plugin enable -- docker plugin inspect -- docker plugin install -- docker plugin ls -- docker plugin push -- docker plugin rm -- docker plugin set -- docker plugin upgrade + - docker plugin create + - docker plugin disable + - docker plugin enable + - docker plugin inspect + - docker plugin install + - docker plugin ls + - docker plugin push + - docker plugin rm + - docker plugin set + - docker plugin upgrade clink: -- docker_plugin_create.yaml -- docker_plugin_disable.yaml -- docker_plugin_enable.yaml -- docker_plugin_inspect.yaml -- docker_plugin_install.yaml -- docker_plugin_ls.yaml -- docker_plugin_push.yaml -- docker_plugin_rm.yaml -- docker_plugin_set.yaml -- docker_plugin_upgrade.yaml + - docker_plugin_create.yaml + - docker_plugin_disable.yaml + - docker_plugin_enable.yaml + - docker_plugin_inspect.yaml + - docker_plugin_install.yaml + - docker_plugin_ls.yaml + - docker_plugin_push.yaml + - docker_plugin_rm.yaml + - docker_plugin_set.yaml + - docker_plugin_upgrade.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_create.yaml b/_data/engine-cli/docker_plugin_create.yaml index db2defb247..e83466b6e7 100644 --- a/_data/engine-cli/docker_plugin_create.yaml +++ b/_data/engine-cli/docker_plugin_create.yaml @@ -1,43 +1,55 @@ command: docker plugin create -short: Create a plugin from a rootfs and configuration. Plugin data directory must - contain config.json and rootfs directory. +short: | + Create a plugin from a rootfs and configuration. Plugin data directory must contain config.json and rootfs directory. long: |- - Creates a plugin. Before creating the plugin, prepare the plugin's root filesystem as well as - [the config.json](../../extend/config.md) + Creates a plugin. Before creating the plugin, prepare the plugin's root filesystem as well as + [the config.json](../../extend/config.md) usage: docker plugin create [OPTIONS] PLUGIN PLUGIN-DATA-DIR pname: docker plugin plink: docker_plugin.yaml options: -- option: compress - value_type: bool - default_value: "false" - description: Compress the context using gzip - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: compress + value_type: bool + default_value: "false" + description: Compress the context using gzip + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following example shows how to create a sample `plugin`. + The following example shows how to create a sample `plugin`. - ```console - $ ls -ls /home/pluginDir + ```console + $ ls -ls /home/pluginDir - total 4 - 4 -rw-r--r-- 1 root root 431 Nov 7 01:40 config.json - 0 drwxr-xr-x 19 root root 420 Nov 7 01:40 rootfs + total 4 + 4 -rw-r--r-- 1 root root 431 Nov 7 01:40 config.json + 0 drwxr-xr-x 19 root root 420 Nov 7 01:40 rootfs - $ docker plugin create plugin /home/pluginDir + $ docker plugin create plugin /home/pluginDir - plugin + plugin - $ docker plugin ls + $ docker plugin ls - ID NAME DESCRIPTION ENABLED - 672d8144ec02 plugin:latest A sample plugin for Docker false - ``` + ID NAME DESCRIPTION ENABLED + 672d8144ec02 plugin:latest A sample plugin for Docker false + ``` - The plugin can subsequently be enabled for local use or pushed to the public registry. + The plugin can subsequently be enabled for local use or pushed to the public registry. deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_disable.yaml b/_data/engine-cli/docker_plugin_disable.yaml index d746b4c660..21f8ca1822 100644 --- a/_data/engine-cli/docker_plugin_disable.yaml +++ b/_data/engine-cli/docker_plugin_disable.yaml @@ -1,46 +1,58 @@ command: docker plugin disable short: Disable a plugin long: |- - Disables a plugin. The plugin must be installed before it can be disabled, - see [`docker plugin install`](plugin_install.md). Without the `-f` option, - a plugin that has references (e.g., volumes, networks) cannot be disabled. + Disables a plugin. The plugin must be installed before it can be disabled, + see [`docker plugin install`](plugin_install.md). Without the `-f` option, + a plugin that has references (e.g., volumes, networks) cannot be disabled. usage: docker plugin disable [OPTIONS] PLUGIN pname: docker plugin plink: docker_plugin.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force the disable of an active plugin - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force the disable of an active plugin + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following example shows that the `sample-volume-plugin` plugin is installed - and enabled: + The following example shows that the `sample-volume-plugin` plugin is installed + and enabled: - ```console - $ docker plugin ls + ```console + $ docker plugin ls - ID NAME DESCRIPTION ENABLED - 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker true - ``` + ID NAME DESCRIPTION ENABLED + 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker true + ``` - To disable the plugin, use the following command: + To disable the plugin, use the following command: - ```console - $ docker plugin disable tiborvass/sample-volume-plugin + ```console + $ docker plugin disable tiborvass/sample-volume-plugin - tiborvass/sample-volume-plugin + tiborvass/sample-volume-plugin - $ docker plugin ls + $ docker plugin ls - ID NAME DESCRIPTION ENABLED - 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker false - ``` + ID NAME DESCRIPTION ENABLED + 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker false + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_enable.yaml b/_data/engine-cli/docker_plugin_enable.yaml index 0af60b28a8..8a21c2a32a 100644 --- a/_data/engine-cli/docker_plugin_enable.yaml +++ b/_data/engine-cli/docker_plugin_enable.yaml @@ -1,44 +1,56 @@ command: docker plugin enable short: Enable a plugin long: |- - Enables a plugin. The plugin must be installed before it can be enabled, - see [`docker plugin install`](plugin_install.md). + Enables a plugin. The plugin must be installed before it can be enabled, + see [`docker plugin install`](plugin_install.md). usage: docker plugin enable [OPTIONS] PLUGIN pname: docker plugin plink: docker_plugin.yaml options: -- option: timeout - value_type: int - default_value: "30" - description: HTTP client timeout (in seconds) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: timeout + value_type: int + default_value: "30" + description: HTTP client timeout (in seconds) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following example shows that the `sample-volume-plugin` plugin is installed, - but disabled: + The following example shows that the `sample-volume-plugin` plugin is installed, + but disabled: - ```console - $ docker plugin ls + ```console + $ docker plugin ls - ID NAME DESCRIPTION ENABLED - 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker false - ``` + ID NAME DESCRIPTION ENABLED + 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker false + ``` - To enable the plugin, use the following command: + To enable the plugin, use the following command: - ```console - $ docker plugin enable tiborvass/sample-volume-plugin + ```console + $ docker plugin enable tiborvass/sample-volume-plugin - tiborvass/sample-volume-plugin + tiborvass/sample-volume-plugin - $ docker plugin ls + $ docker plugin ls - ID NAME DESCRIPTION ENABLED - 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker true - ``` + ID NAME DESCRIPTION ENABLED + 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker true + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_inspect.yaml b/_data/engine-cli/docker_plugin_inspect.yaml index 12e272a7ad..3c9781031c 100644 --- a/_data/engine-cli/docker_plugin_inspect.yaml +++ b/_data/engine-cli/docker_plugin_inspect.yaml @@ -1,148 +1,165 @@ command: docker plugin inspect short: Display detailed information on one or more plugins long: |- - Returns information about a plugin. By default, this command renders all results - in a JSON array. + Returns information about a plugin. By default, this command renders all results + in a JSON array. usage: docker plugin inspect [OPTIONS] PLUGIN [PLUGIN...] pname: docker plugin plink: docker_plugin.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Inspect a plugin + ### Inspect a plugin - The following example example inspects the `tiborvass/sample-volume-plugin` plugin: + The following example example inspects the `tiborvass/sample-volume-plugin` plugin: - ```console - $ docker plugin inspect tiborvass/sample-volume-plugin:latest - ``` + ```console + $ docker plugin inspect tiborvass/sample-volume-plugin:latest + ``` - Output is in JSON format (output below is formatted for readability): + Output is in JSON format (output below is formatted for readability): - ```json - { - "Id": "8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21", - "Name": "tiborvass/sample-volume-plugin:latest", - "PluginReference": "tiborvas/sample-volume-plugin:latest", - "Enabled": true, - "Config": { - "Mounts": [ - { - "Name": "", - "Description": "", - "Settable": null, - "Source": "/data", - "Destination": "/data", - "Type": "bind", - "Options": [ - "shared", - "rbind" - ] - }, - { - "Name": "", - "Description": "", - "Settable": null, - "Source": null, - "Destination": "/foobar", - "Type": "tmpfs", - "Options": null - } - ], - "Env": [ - "DEBUG=1" - ], - "Args": null, - "Devices": null - }, - "Manifest": { - "ManifestVersion": "v0", - "Description": "A test plugin for Docker", - "Documentation": "https://docs.docker.com/engine/extend/plugins/", - "Interface": { - "Types": [ - "docker.volumedriver/1.0" + ```json + { + "Id": "8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21", + "Name": "tiborvass/sample-volume-plugin:latest", + "PluginReference": "tiborvas/sample-volume-plugin:latest", + "Enabled": true, + "Config": { + "Mounts": [ + { + "Name": "", + "Description": "", + "Settable": null, + "Source": "/data", + "Destination": "/data", + "Type": "bind", + "Options": [ + "shared", + "rbind" + ] + }, + { + "Name": "", + "Description": "", + "Settable": null, + "Source": null, + "Destination": "/foobar", + "Type": "tmpfs", + "Options": null + } ], - "Socket": "plugins.sock" + "Env": [ + "DEBUG=1" + ], + "Args": null, + "Devices": null }, - "Entrypoint": [ - "plugin-sample-volume-plugin", - "/data" - ], - "Workdir": "", - "User": { - }, - "Network": { - "Type": "host" - }, - "Capabilities": null, - "Mounts": [ - { - "Name": "", - "Description": "", - "Settable": null, - "Source": "/data", - "Destination": "/data", - "Type": "bind", - "Options": [ - "shared", - "rbind" - ] + "Manifest": { + "ManifestVersion": "v0", + "Description": "A test plugin for Docker", + "Documentation": "/engine/extend/plugins/", + "Interface": { + "Types": [ + "docker.volumedriver/1.0" + ], + "Socket": "plugins.sock" }, - { - "Name": "", - "Description": "", + "Entrypoint": [ + "plugin-sample-volume-plugin", + "/data" + ], + "Workdir": "", + "User": { + }, + "Network": { + "Type": "host" + }, + "Capabilities": null, + "Mounts": [ + { + "Name": "", + "Description": "", + "Settable": null, + "Source": "/data", + "Destination": "/data", + "Type": "bind", + "Options": [ + "shared", + "rbind" + ] + }, + { + "Name": "", + "Description": "", + "Settable": null, + "Source": null, + "Destination": "/foobar", + "Type": "tmpfs", + "Options": null + } + ], + "Devices": [ + { + "Name": "device", + "Description": "a host device to mount", + "Settable": null, + "Path": "/dev/cpu_dma_latency" + } + ], + "Env": [ + { + "Name": "DEBUG", + "Description": "If set, prints debug messages", + "Settable": null, + "Value": "1" + } + ], + "Args": { + "Name": "args", + "Description": "command line arguments", "Settable": null, - "Source": null, - "Destination": "/foobar", - "Type": "tmpfs", - "Options": null - } - ], - "Devices": [ - { - "Name": "device", - "Description": "a host device to mount", - "Settable": null, - "Path": "/dev/cpu_dma_latency" - } - ], - "Env": [ - { - "Name": "DEBUG", - "Description": "If set, prints debug messages", - "Settable": null, - "Value": "1" - } - ], - "Args": { - "Name": "args", - "Description": "command line arguments", - "Settable": null, - "Value": [ + "Value": [ - ] + ] + } } } - } - ``` + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - ```console - $ docker plugin inspect -f '{{.Id}}' tiborvass/sample-volume-plugin:latest + ```console + $ docker plugin inspect -f '{{.Id}}' tiborvass/sample-volume-plugin:latest - 8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21 - ``` + 8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21 + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_install.yaml b/_data/engine-cli/docker_plugin_install.yaml index 6c8652847d..15e28c3467 100644 --- a/_data/engine-cli/docker_plugin_install.yaml +++ b/_data/engine-cli/docker_plugin_install.yaml @@ -1,74 +1,89 @@ command: docker plugin install short: Install a plugin long: |- - Installs and enables a plugin. Docker looks first for the plugin on your Docker - host. If the plugin does not exist locally, then the plugin is pulled from - the registry. Note that the minimum required registry version to distribute - plugins is 2.3.0 + Installs and enables a plugin. Docker looks first for the plugin on your Docker + host. If the plugin does not exist locally, then the plugin is pulled from + the registry. Note that the minimum required registry version to distribute + plugins is 2.3.0 usage: docker plugin install [OPTIONS] PLUGIN [KEY=VALUE...] pname: docker plugin plink: docker_plugin.yaml options: -- option: alias - value_type: string - description: Local name for plugin - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable - value_type: bool - default_value: "false" - description: Do not enable the plugin on install - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: grant-all-permissions - value_type: bool - default_value: "false" - description: Grant all permissions necessary to run the plugin - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: alias + value_type: string + description: Local name for plugin + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable + value_type: bool + default_value: "false" + description: Do not enable the plugin on install + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: grant-all-permissions + value_type: bool + default_value: "false" + description: Grant all permissions necessary to run the plugin + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following example installs `vieus/sshfs` plugin and [sets](plugin_set.md) its - `DEBUG` environment variable to `1`. To install, `pull` the plugin from Docker - Hub and prompt the user to accept the list of privileges that the plugin needs, - set the plugin's parameters and enable the plugin. + The following example installs `vieus/sshfs` plugin and [sets](plugin_set.md) its + `DEBUG` environment variable to `1`. To install, `pull` the plugin from Docker + Hub and prompt the user to accept the list of privileges that the plugin needs, + set the plugin's parameters and enable the plugin. - ```console - $ docker plugin install vieux/sshfs DEBUG=1 + ```console + $ docker plugin install vieux/sshfs DEBUG=1 - Plugin "vieux/sshfs" is requesting the following privileges: - - network: [host] - - device: [/dev/fuse] - - capabilities: [CAP_SYS_ADMIN] - Do you grant the above permissions? [y/N] y - vieux/sshfs - ``` + Plugin "vieux/sshfs" is requesting the following privileges: + - network: [host] + - device: [/dev/fuse] + - capabilities: [CAP_SYS_ADMIN] + Do you grant the above permissions? [y/N] y + vieux/sshfs + ``` - After the plugin is installed, it appears in the list of plugins: + After the plugin is installed, it appears in the list of plugins: - ```console - $ docker plugin ls + ```console + $ docker plugin ls - ID NAME DESCRIPTION ENABLED - 69553ca1d123 vieux/sshfs:latest sshFS plugin for Docker true - ``` + ID NAME DESCRIPTION ENABLED + 69553ca1d123 vieux/sshfs:latest sshFS plugin for Docker true + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_ls.yaml b/_data/engine-cli/docker_plugin_ls.yaml index 8c8fba3850..09f89a502d 100644 --- a/_data/engine-cli/docker_plugin_ls.yaml +++ b/_data/engine-cli/docker_plugin_ls.yaml @@ -1,116 +1,145 @@ command: docker plugin ls -aliases: list +aliases: docker plugin ls, docker plugin list short: List plugins long: |- - Lists all the plugins that are currently installed. You can install plugins - using the [`docker plugin install`](plugin_install.md) command. - You can also filter using the `-f` or `--filter` flag. - Refer to the [filtering](#filter) section for more information about available filter options. + Lists all the plugins that are currently installed. You can install plugins + using the [`docker plugin install`](plugin_install.md) command. + You can also filter using the `-f` or `--filter` flag. + Refer to the [filtering](#filter) section for more information about available filter options. usage: docker plugin ls [OPTIONS] pname: docker plugin plink: docker_plugin.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Provide filter values (e.g. 'enabled=true') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print plugins using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display plugin IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Provide filter values (e.g. `enabled=true`) + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display plugin IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker plugin ls + ```console + $ docker plugin ls - ID NAME DESCRIPTION ENABLED - 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker true - ``` + ID NAME DESCRIPTION ENABLED + 69553ca1d123 tiborvass/sample-volume-plugin:latest A test plugin for Docker true + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--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 filtering flag (`-f` or `--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: + The currently supported filters are: - * enabled (boolean - true or false, 0 or 1) - * capability (string - currently `volumedriver`, `networkdriver`, `ipamdriver`, `logdriver`, `metricscollector`, or `authz`) + * enabled (boolean - true or false, 0 or 1) + * capability (string - currently `volumedriver`, `networkdriver`, `ipamdriver`, `logdriver`, `metricscollector`, or `authz`) - #### enabled + #### enabled - The `enabled` filter matches on plugins enabled or disabled. + The `enabled` filter matches on plugins enabled or disabled. - #### capability + #### capability - The `capability` filter matches on plugin capabilities. One plugin - might have multiple capabilities. Currently `volumedriver`, `networkdriver`, - `ipamdriver`, `logdriver`, `metricscollector`, and `authz` are supported capabilities. + The `capability` filter matches on plugin capabilities. One plugin + might have multiple capabilities. Currently `volumedriver`, `networkdriver`, + `ipamdriver`, `logdriver`, `metricscollector`, and `authz` are supported capabilities. - ```console - $ docker plugin install --disable vieux/sshfs + ```console + $ docker plugin install --disable vieux/sshfs - Installed plugin vieux/sshfs + Installed plugin vieux/sshfs - $ docker plugin ls --filter enabled=true + $ docker plugin ls --filter enabled=true - ID NAME DESCRIPTION ENABLED - ``` + ID NAME DESCRIPTION ENABLED + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints plugins output - using a Go template. + The formatting options (`--format`) pretty-prints plugins output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |--------------------|-------------------------------------------------| - | `.ID` | Plugin ID | - | `.Name` | Plugin name and tag | - | `.Description` | Plugin description | - | `.Enabled` | Whether plugin is enabled or not | - | `.PluginReference` | The reference used to push/pull from a registry | + | Placeholder | Description | + |--------------------|-------------------------------------------------| + | `.ID` | Plugin ID | + | `.Name` | Plugin name and tag | + | `.Description` | Plugin description | + | `.Enabled` | Whether plugin is enabled or not | + | `.PluginReference` | The reference used to push/pull from a registry | - When using the `--format` option, the `plugin ls` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `plugin ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `ID` and `Name` entries separated by a colon (`:`) for all plugins: + The following example uses a template without headers and outputs the + `ID` and `Name` entries separated by a colon (`:`) for all plugins: - ```console - $ docker plugin ls --format "{{.ID}}: {{.Name}}" + ```console + $ docker plugin ls --format "{{.ID}}: {{.Name}}" - 4be01827a72e: vieux/sshfs:latest - ``` + 4be01827a72e: vieux/sshfs:latest + ``` + + To list all plugins in JSON format, use the `json` directive: + ```console + $ docker plugin ls --format json + {"Description":"sshFS plugin for Docker","Enabled":false,"ID":"856d89febb1c","Name":"vieux/sshfs:latest","PluginReference":"docker.io/vieux/sshfs:latest"} + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_push.yaml b/_data/engine-cli/docker_plugin_push.yaml index 6b8804cb36..0eae0bdfee 100644 --- a/_data/engine-cli/docker_plugin_push.yaml +++ b/_data/engine-cli/docker_plugin_push.yaml @@ -1,35 +1,47 @@ command: docker plugin push short: Push a plugin to a registry long: |- - After you have created a plugin using `docker plugin create` and the plugin is - ready for distribution, use `docker plugin push` to share your images to Docker - Hub or a self-hosted registry. + After you have created a plugin using `docker plugin create` and the plugin is + ready for distribution, use `docker plugin push` to share your images to Docker + Hub or a self-hosted registry. - Registry credentials are managed by [docker login](login.md). + Registry credentials are managed by [docker login](login.md). usage: docker plugin push [OPTIONS] PLUGIN[:TAG] pname: docker plugin plink: docker_plugin.yaml options: -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image signing - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image signing + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following example shows how to push a sample `user/plugin`. + The following example shows how to push a sample `user/plugin`. - ```console - $ docker plugin ls + ```console + $ docker plugin ls - ID NAME DESCRIPTION ENABLED - 69553ca1d456 user/plugin:latest A sample plugin for Docker false + ID NAME DESCRIPTION ENABLED + 69553ca1d456 user/plugin:latest A sample plugin for Docker false - $ docker plugin push user/plugin - ``` + $ docker plugin push user/plugin + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_rm.yaml b/_data/engine-cli/docker_plugin_rm.yaml index e69bbaa2dd..a6ccb25d23 100644 --- a/_data/engine-cli/docker_plugin_rm.yaml +++ b/_data/engine-cli/docker_plugin_rm.yaml @@ -1,38 +1,50 @@ command: docker plugin rm -aliases: remove +aliases: docker plugin rm, docker plugin remove short: Remove one or more plugins long: |- - Removes a plugin. You cannot remove a plugin if it is enabled, you must disable - a plugin using the [`docker plugin disable`](plugin_disable.md) before removing - it (or use --force, use of force is not recommended, since it can affect - functioning of running containers using the plugin). + Removes a plugin. You cannot remove a plugin if it is enabled, you must disable + a plugin using the [`docker plugin disable`](plugin_disable.md) before removing + it (or use --force, use of force is not recommended, since it can affect + functioning of running containers using the plugin). usage: docker plugin rm [OPTIONS] PLUGIN [PLUGIN...] pname: docker plugin plink: docker_plugin.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force the removal of an active plugin - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force the removal of an active plugin + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following example disables and removes the `sample-volume-plugin:latest` - plugin: + The following example disables and removes the `sample-volume-plugin:latest` + plugin: - ```console - $ docker plugin disable tiborvass/sample-volume-plugin + ```console + $ docker plugin disable tiborvass/sample-volume-plugin - tiborvass/sample-volume-plugin + tiborvass/sample-volume-plugin - $ docker plugin rm tiborvass/sample-volume-plugin:latest + $ docker plugin rm tiborvass/sample-volume-plugin:latest - tiborvass/sample-volume-plugin - ``` + tiborvass/sample-volume-plugin + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_set.yaml b/_data/engine-cli/docker_plugin_set.yaml index e875ffe095..999c7f6e9d 100644 --- a/_data/engine-cli/docker_plugin_set.yaml +++ b/_data/engine-cli/docker_plugin_set.yaml @@ -1,88 +1,99 @@ command: docker plugin set short: Change settings for a plugin long: |- - Change settings for a plugin. The plugin must be disabled. + Change settings for a plugin. The plugin must be disabled. - The settings currently supported are: - * env variables - * source of mounts - * path of devices - * args + The settings currently supported are: + * env variables + * source of mounts + * path of devices + * args usage: docker plugin set PLUGIN KEY=VALUE [KEY=VALUE...] pname: docker plugin plink: docker_plugin.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Change an environment variable + ### Change an environment variable - The following example change the env variable `DEBUG` on the - `sample-volume-plugin` plugin. + The following example change the env variable `DEBUG` on the + `sample-volume-plugin` plugin. - ```console - $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin - [DEBUG=0] + ```console + $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin + [DEBUG=0] - $ docker plugin set tiborvass/sample-volume-plugin DEBUG=1 + $ docker plugin set tiborvass/sample-volume-plugin DEBUG=1 - $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin - [DEBUG=1] - ``` + $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin + [DEBUG=1] + ``` - ### Change the source of a mount + ### Change the source of a mount - The following example change the source of the `mymount` mount on - the `myplugin` plugin. + The following example change the source of the `mymount` mount on + the `myplugin` plugin. - ```console - $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin - /foo + ```console + $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin + /foo - $ docker plugins set myplugin mymount.source=/bar + $ docker plugins set myplugin mymount.source=/bar - $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin - /bar - ``` + $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin + /bar + ``` - > **Note** - > - > Since only `source` is settable in `mymount`, - > `docker plugins set mymount=/bar myplugin` would work too. + > **Note** + > + > Since only `source` is settable in `mymount`, + > `docker plugins set mymount=/bar myplugin` would work too. - ### Change a device path + ### Change a device path - The following example change the path of the `mydevice` device on - the `myplugin` plugin. + The following example change the path of the `mydevice` device on + the `myplugin` plugin. - ```console - $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin + ```console + $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin - /dev/foo + /dev/foo - $ docker plugins set myplugin mydevice.path=/dev/bar + $ docker plugins set myplugin mydevice.path=/dev/bar - $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin + $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin - /dev/bar - ``` + /dev/bar + ``` - > **Note** - > Since only `path` is settable in `mydevice`, - > `docker plugins set mydevice=/dev/bar myplugin` would work too. + > **Note** + > Since only `path` is settable in `mydevice`, + > `docker plugins set mydevice=/dev/bar myplugin` would work too. - ### Change the source of the arguments + ### Change the source of the arguments - The following example change the value of the args on the `myplugin` plugin. + The following example change the value of the args on the `myplugin` plugin. - ```console - $ docker plugin inspect -f '{{.Settings.Args}}' myplugin + ```console + $ docker plugin inspect -f '{{.Settings.Args}}' myplugin - ["foo", "bar"] + ["foo", "bar"] - $ docker plugins set myplugin myargs="foo bar baz" + $ docker plugins set myplugin myargs="foo bar baz" - $ docker plugin inspect -f '{{.Settings.Args}}' myplugin + $ docker plugin inspect -f '{{.Settings.Args}}' myplugin - ["foo", "bar", "baz"] - ``` + ["foo", "bar", "baz"] + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_plugin_upgrade.yaml b/_data/engine-cli/docker_plugin_upgrade.yaml index 750343c407..a9f56a463a 100644 --- a/_data/engine-cli/docker_plugin_upgrade.yaml +++ b/_data/engine-cli/docker_plugin_upgrade.yaml @@ -1,93 +1,107 @@ command: docker plugin upgrade short: Upgrade an existing plugin long: |- - Upgrades an existing plugin to the specified remote plugin image. If no remote - is specified, Docker will re-pull the current image and use the updated version. - All existing references to the plugin will continue to work. - The plugin must be disabled before running the upgrade. + Upgrades an existing plugin to the specified remote plugin image. If no remote + is specified, Docker will re-pull the current image and use the updated version. + All existing references to the plugin will continue to work. + The plugin must be disabled before running the upgrade. usage: docker plugin upgrade [OPTIONS] PLUGIN [REMOTE] pname: docker plugin plink: docker_plugin.yaml options: -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: grant-all-permissions - value_type: bool - default_value: "false" - description: Grant all permissions necessary to run the plugin - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: skip-remote-check - value_type: bool - default_value: "false" - description: | - Do not check if specified remote plugin matches existing plugin image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: grant-all-permissions + value_type: bool + default_value: "false" + description: Grant all permissions necessary to run the plugin + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: skip-remote-check + value_type: bool + default_value: "false" + description: | + Do not check if specified remote plugin matches existing plugin image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following example installs `vieus/sshfs` plugin, uses it to create and use - a volume, then upgrades the plugin. + The following example installs `vieus/sshfs` plugin, uses it to create and use + a volume, then upgrades the plugin. - ```console - $ docker plugin install vieux/sshfs DEBUG=1 + ```console + $ docker plugin install vieux/sshfs DEBUG=1 - Plugin "vieux/sshfs:next" is requesting the following privileges: - - network: [host] - - device: [/dev/fuse] - - capabilities: [CAP_SYS_ADMIN] - Do you grant the above permissions? [y/N] y - vieux/sshfs:next + Plugin "vieux/sshfs:next" is requesting the following privileges: + - network: [host] + - device: [/dev/fuse] + - capabilities: [CAP_SYS_ADMIN] + Do you grant the above permissions? [y/N] y + vieux/sshfs:next - $ docker volume create -d vieux/sshfs:next -o sshcmd=root@1.2.3.4:/tmp/shared -o password=XXX sshvolume + $ docker volume create -d vieux/sshfs:next -o sshcmd=root@1.2.3.4:/tmp/shared -o password=XXX sshvolume - sshvolume + sshvolume - $ docker run -it -v sshvolume:/data alpine sh -c "touch /data/hello" + $ docker run -it -v sshvolume:/data alpine sh -c "touch /data/hello" - $ docker plugin disable -f vieux/sshfs:next + $ docker plugin disable -f vieux/sshfs:next - viex/sshfs:next + viex/sshfs:next - # Here docker volume ls doesn't show 'sshfsvolume', since the plugin is disabled - $ docker volume ls + # Here docker volume ls doesn't show 'sshfsvolume', since the plugin is disabled + $ docker volume ls - DRIVER VOLUME NAME + DRIVER VOLUME NAME - $ docker plugin upgrade vieux/sshfs:next vieux/sshfs:next + $ docker plugin upgrade vieux/sshfs:next vieux/sshfs:next - Plugin "vieux/sshfs:next" is requesting the following privileges: - - network: [host] - - device: [/dev/fuse] - - capabilities: [CAP_SYS_ADMIN] - Do you grant the above permissions? [y/N] y - Upgrade plugin vieux/sshfs:next to vieux/sshfs:next + Plugin "vieux/sshfs:next" is requesting the following privileges: + - network: [host] + - device: [/dev/fuse] + - capabilities: [CAP_SYS_ADMIN] + Do you grant the above permissions? [y/N] y + Upgrade plugin vieux/sshfs:next to vieux/sshfs:next - $ docker plugin enable vieux/sshfs:next + $ docker plugin enable vieux/sshfs:next - viex/sshfs:next + viex/sshfs:next - $ docker volume ls + $ docker volume ls - DRIVER VOLUME NAME - viuex/sshfs:next sshvolume + DRIVER VOLUME NAME + viuex/sshfs:next sshvolume - $ docker run -it -v sshvolume:/data alpine sh -c "ls /data" + $ docker run -it -v sshvolume:/data alpine sh -c "ls /data" - hello - ``` + hello + ``` deprecated: false min_api_version: "1.26" experimental: false diff --git a/_data/engine-cli/docker_port.yaml b/_data/engine-cli/docker_port.yaml index 86e04c1a81..b48013ee9a 100644 --- a/_data/engine-cli/docker_port.yaml +++ b/_data/engine-cli/docker_port.yaml @@ -1,38 +1,50 @@ command: docker port +aliases: docker container port, docker port short: List port mappings or a specific mapping for the container long: List port mappings or a specific mapping for the container usage: docker port CONTAINER [PRIVATE_PORT[/PROTO]] pname: docker plink: docker.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Show all mapped ports + ### Show all mapped ports - You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or - just a specific mapping: + You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or + just a specific mapping: - ```console - $ docker ps + ```console + $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test - $ docker port test + $ docker port test - 7890/tcp -> 0.0.0.0:4321 - 9876/tcp -> 0.0.0.0:1234 + 7890/tcp -> 0.0.0.0:4321 + 9876/tcp -> 0.0.0.0:1234 - $ docker port test 7890/tcp + $ docker port test 7890/tcp - 0.0.0.0:4321 + 0.0.0.0:4321 - $ docker port test 7890/udp + $ docker port test 7890/udp - 2014/06/24 11:53:36 Error: No public port '7890/udp' published for test + 2014/06/24 11:53:36 Error: No public port '7890/udp' published for test - $ docker port test 7890 + $ docker port test 7890 - 0.0.0.0:4321 - ``` + 0.0.0.0:4321 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_ps.yaml b/_data/engine-cli/docker_ps.yaml index f93a48f062..0da25d79ba 100644 --- a/_data/engine-cli/docker_ps.yaml +++ b/_data/engine-cli/docker_ps.yaml @@ -1,491 +1,529 @@ command: docker ps +aliases: docker container ls, docker container list, docker container ps, docker ps short: List containers long: List containers usage: docker ps [OPTIONS] pname: docker plink: docker.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Show all containers (default shows just running) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print containers using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: last - shorthand: "n" - value_type: int - default_value: "-1" - description: Show n last created containers (includes all states) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: latest - shorthand: l - value_type: bool - default_value: "false" - description: Show the latest created container (includes all states) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display container IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: size - shorthand: s - value_type: bool - default_value: "false" - description: Display total file sizes - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Show all containers (default shows just running) + details_url: '#all' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: last + shorthand: "n" + value_type: int + default_value: "-1" + description: Show n last created containers (includes all states) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: latest + shorthand: l + value_type: bool + default_value: "false" + description: Show the latest created container (includes all states) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + details_url: '#no-trunc' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display container IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: size + shorthand: s + value_type: bool + default_value: "false" + description: Display total file sizes + details_url: '#size' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Do not truncate output (--no-trunc) + ### Do not truncate output (--no-trunc) {#no-trunc} - Running `docker ps --no-trunc` showing 2 linked containers. + Running `docker ps --no-trunc` showing 2 linked containers. - ```console - $ docker ps + ```console + $ docker ps --no-trunc - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4c01db0b339c ubuntu:22.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp - d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 4c01db0b339c ubuntu:22.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp + d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db + ``` - ### Show both running and stopped containers (-a, --all) + ### Show both running and stopped containers (-a, --all) {#all} - The `docker ps` command only shows running containers by default. To see all - containers, use the `--all` (or `-a`) flag: + The `docker ps` command only shows running containers by default. To see all + containers, use the `--all` (or `-a`) flag: - ```console - $ docker ps -a - ``` + ```console + $ docker ps -a + ``` - `docker ps` groups exposed ports into a single range if possible. E.g., a - container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in - the `PORTS` column. + `docker ps` groups exposed ports into a single range if possible. E.g., a + container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in + the `PORTS` column. - ### Show disk usage by container (--size) + ### Show disk usage by container (--size) {#size} - The `docker ps --size` (or `-s`) command displays two different on-disk-sizes for each container: + The `docker ps --size` (or `-s`) command displays two different on-disk-sizes for each container: - ```console - $ docker ps --size + ```console + $ docker ps --size - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE SIZE - e90b8831a4b8 nginx "/bin/bash -c 'mkdir " 11 weeks ago Up 4 hours my_nginx 35.58 kB (virtual 109.2 MB) - 00c6131c5e30 telegraf:1.5 "/entrypoint.sh" 11 weeks ago Up 11 weeks my_telegraf 0 B (virtual 209.5 MB) - ``` - * The "size" information shows the amount of data (on disk) that is used for the _writable_ layer of each container - * The "virtual size" is the total amount of disk-space used for the read-only _image_ data used by the container and the writable layer. + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE + e90b8831a4b8 nginx "/bin/bash -c 'mkdir " 11 weeks ago Up 4 hours my_nginx 35.58 kB (virtual 109.2 MB) + 00c6131c5e30 telegraf:1.5 "/entrypoint.sh" 11 weeks ago Up 11 weeks my_telegraf 0 B (virtual 209.5 MB) + ``` + * The "size" information shows the amount of data (on disk) that is used for the _writable_ layer of each container + * The "virtual size" is the total amount of disk-space used for the read-only _image_ data used by the container and the writable layer. - For more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk) section. + For more information, refer to the [container size on disk](/storage/storagedriver/#container-size-on-disk) section. - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The `--filter` (or `-f`) flag format is a `key=value` pair. If there is more - than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) + The `--filter` (or `-f`) flag format is a `key=value` pair. If there is more + than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) - The currently supported filters are: + The currently supported filters are: - | Filter | Description | - |:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------| - | `id` | Container's ID | - | `name` | Container's name | - | `label` | An arbitrary string representing either a key or a key-value pair. Expressed as `` or `=` | - | `exited` | An integer representing the container's exit code. Only useful with `--all`. | - | `status` | One of `created`, `restarting`, `running`, `removing`, `paused`, `exited`, or `dead` | - | `ancestor` | Filters containers which share a given image as an ancestor. Expressed as `[:]`, ``, or `` | - | `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. Expressed as `[/]` or `/[]` | - | `health` | Filters containers based on their healthcheck status. One of `starting`, `healthy`, `unhealthy` or `none`. | - | `isolation` | Windows daemon only. One of `default`, `process`, or `hyperv`. | - | `is-task` | Filters containers that are a "task" for a service. Boolean option (`true` or `false`) | + | Filter | Description | + |:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------| + | `id` | Container's ID | + | `name` | Container's name | + | `label` | An arbitrary string representing either a key or a key-value pair. Expressed as `` or `=` | + | `exited` | An integer representing the container's exit code. Only useful with `--all`. | + | `status` | One of `created`, `restarting`, `running`, `removing`, `paused`, `exited`, or `dead` | + | `ancestor` | Filters containers which share a given image as an ancestor. Expressed as `[:]`, ``, or `` | + | `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. Expressed as `[/]` or `/[]` | + | `health` | Filters containers based on their healthcheck status. One of `starting`, `healthy`, `unhealthy` or `none`. | + | `isolation` | Windows daemon only. One of `default`, `process`, or `hyperv`. | + | `is-task` | Filters containers that are a "task" for a service. Boolean option (`true` or `false`) | - #### label + #### label - The `label` filter matches containers based on the presence of a `label` alone or a `label` and a - value. + The `label` filter matches containers based on the presence of a `label` alone or a `label` and a + value. - The following filter matches containers with the `color` label regardless of its value. + The following filter matches containers with the `color` label regardless of its value. - ```console - $ docker ps --filter "label=color" + ```console + $ docker ps --filter "label=color" - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley - d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley + d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani + ``` - The following filter matches containers with the `color` label with the `blue` value. + The following filter matches containers with the `color` label with the `blue` value. - ```console - $ docker ps --filter "label=color=blue" + ```console + $ docker ps --filter "label=color=blue" - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani + ``` - #### name + #### name - The `name` filter matches on all or part of a container's name. + The `name` filter matches on all or part of a container's name. - The following filter matches all containers with a name containing the `nostalgic_stallman` string. + The following filter matches all containers with a name containing the `nostalgic_stallman` string. - ```console - $ docker ps --filter "name=nostalgic_stallman" + ```console + $ docker ps --filter "name=nostalgic_stallman" - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman + ``` - You can also filter for a substring in a name as this shows: + You can also filter for a substring in a name as this shows: - ```console - $ docker ps --filter "name=nostalgic" + ```console + $ docker ps --filter "name=nostalgic" - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 715ebfcee040 busybox "top" 3 seconds ago Up 1 second i_am_nostalgic - 9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman - 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 715ebfcee040 busybox "top" 3 seconds ago Up 1 second i_am_nostalgic + 9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman + 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley + ``` - #### exited + #### exited - The `exited` filter matches containers by exist status code. For example, to - filter for containers that have exited successfully: + The `exited` filter matches containers by exist status code. For example, to + filter for containers that have exited successfully: - ```console - $ docker ps -a --filter 'exited=0' + ```console + $ docker ps -a --filter 'exited=0' - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey - 106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani - 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey + 106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani + 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds + ``` - #### Filter by exit signal + #### Filter by exit signal - You can use a filter to locate containers that exited with status of `137` - meaning a `SIGKILL(9)` killed them. + You can use a filter to locate containers that exited with status of `137` + meaning a `SIGKILL(9)` killed them. - ```console - $ docker ps -a --filter 'exited=137' + ```console + $ docker ps -a --filter 'exited=137' - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - b3e1c0ed5bfe ubuntu:latest "sleep 1000" 12 seconds ago Exited (137) 5 seconds ago grave_kowalevski - a2eb5558d669 redis:latest "/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + b3e1c0ed5bfe ubuntu:latest "sleep 1000" 12 seconds ago Exited (137) 5 seconds ago grave_kowalevski + a2eb5558d669 redis:latest "/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande + ``` - Any of these events result in a `137` status: + Any of these events result in a `137` status: - * the `init` process of the container is killed manually - * `docker kill` kills the container - * Docker daemon restarts which kills all running containers + * the `init` process of the container is killed manually + * `docker kill` kills the container + * Docker daemon restarts which kills all running containers - #### status + #### status - The `status` filter matches containers by status. You can filter using - `created`, `restarting`, `running`, `removing`, `paused`, `exited` and `dead`. For example, - to filter for `running` containers: + The `status` filter matches containers by status. You can filter using + `created`, `restarting`, `running`, `removing`, `paused`, `exited` and `dead`. For example, + to filter for `running` containers: - ```console - $ docker ps --filter status=running + ```console + $ docker ps --filter status=running - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic - d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top - 9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic + d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top + 9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman + ``` - To filter for `paused` containers: + To filter for `paused` containers: - ```console - $ docker ps --filter status=paused + ```console + $ docker ps --filter status=paused - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley + ``` - #### ancestor + #### ancestor - The `ancestor` filter matches containers based on its image or a descendant of - it. The filter supports the following image representation: + The `ancestor` filter matches containers based on its image or a descendant of + it. The filter supports the following image representation: - - `image` - - `image:tag` - - `image:tag@digest` - - `short-id` - - `full-id` + - `image` + - `image:tag` + - `image:tag@digest` + - `short-id` + - `full-id` - If you don't specify a `tag`, the `latest` tag is used. For example, to filter - for containers that use the latest `ubuntu` image: + If you don't specify a `tag`, the `latest` tag is used. For example, to filter + for containers that use the latest `ubuntu` image: - ```console - $ docker ps --filter ancestor=ubuntu + ```console + $ docker ps --filter ancestor=ubuntu - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace - 5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet - 82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose - bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace + 5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet + 82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose + bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath + ``` - Match containers based on the `ubuntu-c1` image which, in this case, is a child - of `ubuntu`: + Match containers based on the `ubuntu-c1` image which, in this case, is a child + of `ubuntu`: - ```console - $ docker ps --filter ancestor=ubuntu-c1 + ```console + $ docker ps --filter ancestor=ubuntu-c1 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace + ``` - Match containers based on the `ubuntu` version `22.04` image: + Match containers based on the `ubuntu` version `22.04` image: - ```console - $ docker ps --filter ancestor=ubuntu:22.04 + ```console + $ docker ps --filter ancestor=ubuntu:22.04 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose + ``` - The following matches containers based on the layer `d0e008c6cf02` or an image - that have this layer in its layer stack. + The following matches containers based on the layer `d0e008c6cf02` or an image + that have this layer in its layer stack. - ```console - $ docker ps --filter ancestor=d0e008c6cf02 + ```console + $ docker ps --filter ancestor=d0e008c6cf02 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose + ``` - #### Create time + #### Create time - ##### before + ##### before - The `before` filter shows only containers created before the container with - given id or name. For example, having these containers created: + The `before` filter shows only containers created before the container with + given id or name. For example, having these containers created: - ```console - $ docker ps + ```console + $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky - 4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton - 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky + 4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton + 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat + ``` - Filtering with `before` would give: + Filtering with `before` would give: - ```console - $ docker ps -f before=9c3527ed70ce + ```console + $ docker ps -f before=9c3527ed70ce - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton - 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton + 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat + ``` - ##### since + ##### since - The `since` filter shows only containers created since the container with given - id or name. For example, with the same containers as in `before` filter: + The `since` filter shows only containers created since the container with given + id or name. For example, with the same containers as in `before` filter: - ```console - $ docker ps -f since=6e63f6ff38b0 + ```console + $ docker ps -f since=6e63f6ff38b0 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky - 4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky + 4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton + ``` - #### volume + #### volume - The `volume` filter shows only containers that mount a specific volume or have - a volume mounted in a specific path: + The `volume` filter shows only containers that mount a specific volume or have + a volume mounted in a specific path: - ```console - $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" + ```console + $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" - CONTAINER ID MOUNTS - 9c3527ed70ce remote-volume + CONTAINER ID MOUNTS + 9c3527ed70ce remote-volume - $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" + $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" - CONTAINER ID MOUNTS - 9c3527ed70ce remote-volume - ``` + CONTAINER ID MOUNTS + 9c3527ed70ce remote-volume + ``` - #### network + #### network - The `network` filter shows only containers that are connected to a network with - a given name or id. + The `network` filter shows only containers that are connected to a network with + a given name or id. - The following filter matches all containers that are connected to a network - with a name containing `net1`. + The following filter matches all containers that are connected to a network + with a name containing `net1`. - ```console - $ docker run -d --net=net1 --name=test1 ubuntu top - $ docker run -d --net=net2 --name=test2 ubuntu top + ```console + $ docker run -d --net=net1 --name=test1 ubuntu top + $ docker run -d --net=net2 --name=test2 ubuntu top - $ docker ps --filter network=net1 + $ docker ps --filter network=net1 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 + ``` - The network filter matches on both the network's name and id. The following - example shows all containers that are attached to the `net1` network, using - the network id as a filter; + The network filter matches on both the network's name and id. The following + example shows all containers that are attached to the `net1` network, using + the network id as a filter; - ```console - $ docker network inspect --format "{{.ID}}" net1 + ```console + $ docker network inspect --format "{{.ID}}" net1 - 8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 + 8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 - $ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 + $ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 + ``` - #### publish and expose + #### publish and expose - The `publish` and `expose` filters show only containers that have published or exposed port with a given port - number, port range, and/or protocol. The default protocol is `tcp` when not specified. + The `publish` and `expose` filters show only containers that have published or exposed port with a given port + number, port range, and/or protocol. The default protocol is `tcp` when not specified. - The following filter matches all containers that have published port of 80: + The following filter matches all containers that have published port of 80: - ```console - $ docker run -d --publish=80 busybox top - $ docker run -d --expose=8080 busybox top + ```console + $ docker run -d --publish=80 busybox top + $ docker run -d --expose=8080 busybox top - $ docker ps -a + $ docker ps -a - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9833437217a5 busybox "top" 5 seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy - fc7e477723b7 busybox "top" 50 seconds ago Up 50 seconds 0.0.0.0:32768->80/tcp admiring_roentgen + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9833437217a5 busybox "top" 5 seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy + fc7e477723b7 busybox "top" 50 seconds ago Up 50 seconds 0.0.0.0:32768->80/tcp admiring_roentgen - $ docker ps --filter publish=80 + $ docker ps --filter publish=80 - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - fc7e477723b7 busybox "top" About a minute ago Up About a minute 0.0.0.0:32768->80/tcp admiring_roentgen - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + fc7e477723b7 busybox "top" About a minute ago Up About a minute 0.0.0.0:32768->80/tcp admiring_roentgen + ``` - The following filter matches all containers that have exposed TCP port in the range of `8000-8080`: + The following filter matches all containers that have exposed TCP port in the range of `8000-8080`: - ```console - $ docker ps --filter expose=8000-8080/tcp + ```console + $ docker ps --filter expose=8000-8080/tcp - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9833437217a5 busybox "top" 21 seconds ago Up 19 seconds 8080/tcp dreamy_mccarthy - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9833437217a5 busybox "top" 21 seconds ago Up 19 seconds 8080/tcp dreamy_mccarthy + ``` - The following filter matches all containers that have exposed UDP port `80`: + The following filter matches all containers that have exposed UDP port `80`: - ```console - $ docker ps --filter publish=80/udp + ```console + $ docker ps --filter publish=80/udp - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) pretty-prints container output using a Go - template. + The formatting option (`--format`) pretty-prints container output using a Go + template. - Valid placeholders for the Go template are listed below: + 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. | - | `.State` | Container status (for example; "created", "running", "exited"). | - | `.Status` | Container status with details about duration and health-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. | + | `.State` | Container status (for example; "created", "running", "exited"). | + | `.Status` | Container status with details about duration and health-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 - column headers as well. + 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 + column headers as well. - The following example uses a template without headers and outputs the `ID` and - `Command` entries separated by a colon (`:`) for all running containers: + The following example uses a template without headers and outputs the `ID` and + `Command` entries separated by a colon (`:`) for all running containers: - ```console - $ docker ps --format "{{.ID}}: {{.Command}}" + ```console + $ docker ps --format "{{.ID}}: {{.Command}}" - a87ecb4f327c: /bin/sh -c #(nop) MA - 01946d9d34d8: /bin/sh -c #(nop) MA - c1d3b0166030: /bin/sh -c yum -y up - 41d50ecd2f57: /bin/sh -c #(nop) MA - ``` + a87ecb4f327c: /bin/sh -c #(nop) MA + 01946d9d34d8: /bin/sh -c #(nop) MA + c1d3b0166030: /bin/sh -c yum -y up + 41d50ecd2f57: /bin/sh -c #(nop) MA + ``` - To list all running containers with their labels in a table format you can use: + To list all running containers with their labels in a table format you can use: - ```console - $ docker ps --format "table {{.ID}}\t{{.Labels}}" + ```console + $ docker ps --format "table {{.ID}}\t{{.Labels}}" - CONTAINER ID LABELS - 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 - ``` + CONTAINER ID LABELS + 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 + ``` + + To list all running containers in JSON format, use the `json` directive: + + ```console + $ docker ps --format json + {"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"} + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_pull.yaml b/_data/engine-cli/docker_pull.yaml index 4ff66d2707..31edebb343 100644 --- a/_data/engine-cli/docker_pull.yaml +++ b/_data/engine-cli/docker_pull.yaml @@ -1,269 +1,286 @@ command: docker pull -short: Pull an image or a repository from a registry +aliases: docker image pull, docker pull +short: Download an image from a registry long: |- - Most of your images will be created on top of a base image from the - [Docker Hub](https://hub.docker.com) registry. + Most of your images will be created on top of a base image from the + [Docker Hub](https://hub.docker.com) registry. - [Docker Hub](https://hub.docker.com) contains many pre-built images that you - can `pull` and try without needing to define and configure your own. + [Docker Hub](https://hub.docker.com) contains many pre-built images that you + can `pull` and try without needing to define and configure your own. - To download a particular image, or set of images (i.e., a repository), - use `docker pull`. + To download a particular image, or set of images (i.e., a repository), + use `docker pull`. - ### Proxy configuration + ### Proxy configuration - If you are behind an HTTP proxy server, for example in corporate settings, - before open a connect to registry, you may need to configure the Docker - daemon's proxy settings, using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` - environment variables. To set these environment variables on a host using - `systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) - for variables configuration. + If you are behind an HTTP proxy server, for example in corporate settings, + before open a connect to registry, you may need to configure the Docker + daemon's proxy settings, using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` + environment variables. To set these environment variables on a host using + `systemd`, refer to the [control and configure Docker with systemd](/config/daemon/systemd/#httphttps-proxy) + for variables configuration. - ### Concurrent downloads + ### Concurrent downloads - By default the Docker daemon will pull three layers of an image at a time. - If you are on a low bandwidth connection this may cause timeout issues and you may want to lower - this via the `--max-concurrent-downloads` daemon option. See the - [daemon documentation](dockerd.md) for more details. + By default the Docker daemon will pull three layers of an image at a time. + If you are on a low bandwidth connection this may cause timeout issues and you may want to lower + this via the `--max-concurrent-downloads` daemon option. See the + [daemon documentation](dockerd.md) for more details. usage: docker pull [OPTIONS] NAME[:TAG|@DIGEST] pname: docker plink: docker.yaml options: -- option: all-tags - shorthand: a - value_type: bool - default_value: "false" - description: Download all tagged images in the repository - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress verbose output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all-tags + shorthand: a + value_type: bool + default_value: "false" + description: Download all tagged images in the repository + details_url: '#all-tags' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Pull an image from Docker Hub + ### Pull an image from Docker Hub - To download a particular image, or set of images (i.e., a repository), use - `docker image pull` (or the `docker pull` shorthand). If no tag is provided, - Docker Engine uses the `:latest` tag as a default. This example pulls the - `debian:latest` image: + To download a particular image, or set of images (i.e., a repository), use + `docker image pull` (or the `docker pull` shorthand). If no tag is provided, + Docker Engine uses the `:latest` tag as a default. This example pulls the + `debian:latest` image: - ```console - $ docker image pull debian + ```console + $ docker image pull debian - Using default tag: latest - latest: Pulling from library/debian - e756f3fdd6a3: Pull complete - Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 - Status: Downloaded newer image for debian:latest - docker.io/library/debian:latest - ``` + Using default tag: latest + latest: Pulling from library/debian + e756f3fdd6a3: Pull complete + Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 + Status: Downloaded newer image for debian:latest + docker.io/library/debian:latest + ``` - Docker images can consist of multiple layers. In the example above, the image - consists of a single layer; `e756f3fdd6a3`. + Docker images can consist of multiple layers. In the example above, the image + consists of a single layer; `e756f3fdd6a3`. - Layers can be reused by images. For example, the `debian:bullseye` image shares - its layer with the `debian:latest`. Pulling the `debian:bullseye` image therefore - only pulls its metadata, but not its layers, because the layer is already present - locally: + Layers can be reused by images. For example, the `debian:bullseye` image shares + its layer with the `debian:latest`. Pulling the `debian:bullseye` image therefore + only pulls its metadata, but not its layers, because the layer is already present + locally: - ```console - $ docker image pull debian:bullseye + ```console + $ docker image pull debian:bullseye - bullseye: Pulling from library/debian - Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 - Status: Downloaded newer image for debian:bullseye - docker.io/library/debian:bullseye - ``` + bullseye: Pulling from library/debian + Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 + Status: Downloaded newer image for debian:bullseye + docker.io/library/debian:bullseye + ``` - To see which images are present locally, use the [`docker images`](images.md) - command: + To see which images are present locally, use the [`docker images`](images.md) + command: - ```console - $ docker images + ```console + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - debian bullseye 4eacea30377a 8 days ago 124MB - debian latest 4eacea30377a 8 days ago 124MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + debian bullseye 4eacea30377a 8 days ago 124MB + debian latest 4eacea30377a 8 days ago 124MB + ``` - Docker uses a content-addressable image store, and the image ID is a SHA256 - digest covering the image's configuration and layers. In the example above, - `debian:bullseye` and `debian:latest` have the same image ID because they are - the *same* image tagged with different names. Because they are the same image, - their layers are stored only once and do not consume extra disk space. + Docker uses a content-addressable image store, and the image ID is a SHA256 + digest covering the image's configuration and layers. In the example above, + `debian:bullseye` and `debian:latest` have the same image ID because they are + the *same* image tagged with different names. Because they are the same image, + their layers are stored only once and do not consume extra disk space. - For more information about images, layers, and the content-addressable store, - refer to [understand images, containers, and storage drivers](https://docs.docker.com/storage/storagedriver/). + For more information about images, layers, and the content-addressable store, + refer to [understand images, containers, and storage drivers](/storage/storagedriver/). - ### Pull an image by digest (immutable identifier) + ### Pull an image by digest (immutable identifier) - So far, you've pulled images by their name (and "tag"). Using names and tags is - a convenient way to work with images. When using tags, you can `docker pull` an - image again to make sure you have the most up-to-date version of that image. - For example, `docker pull ubuntu:22.04` pulls the latest version of the Ubuntu - 22.04 image. + So far, you've pulled images by their name (and "tag"). Using names and tags is + a convenient way to work with images. When using tags, you can `docker pull` an + image again to make sure you have the most up-to-date version of that image. + For example, `docker pull ubuntu:22.04` pulls the latest version of the Ubuntu + 22.04 image. - In some cases you don't want images to be updated to newer versions, but prefer - to use a fixed version of an image. Docker enables you to pull an image by its - *digest*. When pulling an image by digest, you specify *exactly* which version - of an image to pull. Doing so, allows you to "pin" an image to that version, - and guarantee that the image you're using is always the same. + In some cases you don't want images to be updated to newer versions, but prefer + to use a fixed version of an image. Docker enables you to pull an image by its + *digest*. When pulling an image by digest, you specify *exactly* which version + of an image to pull. Doing so, allows you to "pin" an image to that version, + and guarantee that the image you're using is always the same. - To know the digest of an image, pull the image first. Let's pull the latest - `ubuntu:22.04` image from Docker Hub: + To know the digest of an image, pull the image first. Let's pull the latest + `ubuntu:22.04` image from Docker Hub: - ```console - $ docker pull ubuntu:22.04 + ```console + $ docker pull ubuntu:22.04 - 22.04: Pulling from library/ubuntu - 125a6e411906: Pull complete - Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - Status: Downloaded newer image for ubuntu:22.04 - docker.io/library/ubuntu:22.04 - ``` + 22.04: Pulling from library/ubuntu + 125a6e411906: Pull complete + Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + Status: Downloaded newer image for ubuntu:22.04 + docker.io/library/ubuntu:22.04 + ``` - Docker prints the digest of the image after the pull has finished. In the example - above, the digest of the image is: + Docker prints the digest of the image after the pull has finished. In the example + above, the digest of the image is: - ```console - sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - ``` + ```console + sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + ``` - Docker also prints the digest of an image when *pushing* to a registry. This - may be useful if you want to pin to a version of the image you just pushed. + Docker also prints the digest of an image when *pushing* to a registry. This + may be useful if you want to pin to a version of the image you just pushed. - A digest takes the place of the tag when pulling an image, for example, to - pull the above image by digest, run the following command: + A digest takes the place of the tag when pulling an image, for example, to + pull the above image by digest, run the following command: - ```console - $ docker pull ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + ```console + $ docker pull ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d: Pulling from library/ubuntu - Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - Status: Image is up to date for ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - ``` + docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d: Pulling from library/ubuntu + Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + Status: Image is up to date for ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + ``` - Digest can also be used in the `FROM` of a Dockerfile, for example: + Digest can also be used in the `FROM` of a Dockerfile, for example: - ```dockerfile - FROM ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - LABEL org.opencontainers.image.authors="some maintainer " - ``` + ```dockerfile + FROM ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + LABEL org.opencontainers.image.authors="some maintainer " + ``` - > **Note** - > - > Using this feature "pins" an image to a specific version in time. - > Docker does therefore not pull updated versions of an image, which may include - > security updates. If you want to pull an updated image, you need to change the - > digest accordingly. + > **Note** + > + > Using this feature "pins" an image to a specific version in time. + > Docker does therefore not pull updated versions of an image, which may include + > security updates. If you want to pull an updated image, you need to change the + > digest accordingly. - ### Pull from a different registry + ### Pull from a different registry - By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to - manually specify the path of a registry to pull from. For example, if you have - set up a local registry, you can specify its path to pull from it. A registry - path is similar to a URL, but does not contain a protocol specifier (`https://`). + By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to + manually specify the path of a registry to pull from. For example, if you have + set up a local registry, you can specify its path to pull from it. A registry + path is similar to a URL, but does not contain a protocol specifier (`https://`). - The following command pulls the `testing/test-image` image from a local registry - listening on port 5000 (`myregistry.local:5000`): + The following command pulls the `testing/test-image` image from a local registry + listening on port 5000 (`myregistry.local:5000`): - ```console - $ docker image pull myregistry.local:5000/testing/test-image - ``` + ```console + $ docker image pull myregistry.local:5000/testing/test-image + ``` - Registry credentials are managed by [docker login](login.md). + Registry credentials are managed by [docker login](login.md). - Docker uses the `https://` protocol to communicate with a registry, unless the - registry is allowed to be accessed over an insecure connection. Refer to the - [insecure registries](dockerd.md#insecure-registries) section for more information. + Docker uses the `https://` protocol to communicate with a registry, unless the + registry is allowed to be accessed over an insecure connection. Refer to the + [insecure registries](dockerd.md#insecure-registries) section for more information. - ### Pull a repository with multiple images (-a, --all-tags) + ### Pull a repository with multiple images (-a, --all-tags) {#all-tags} - By default, `docker pull` pulls a *single* image from the registry. A repository - can contain multiple images. To pull all images from a repository, provide the - `-a` (or `--all-tags`) option when using `docker pull`. + By default, `docker pull` pulls a *single* image from the registry. A repository + can contain multiple images. To pull all images from a repository, provide the + `-a` (or `--all-tags`) option when using `docker pull`. - This command pulls all images from the `ubuntu` repository: + This command pulls all images from the `ubuntu` repository: - ```console - $ docker image pull --all-tags ubuntu + ```console + $ docker image pull --all-tags ubuntu - Pulling repository ubuntu - ad57ef8d78d7: Download complete - 105182bb5e8b: Download complete - 511136ea3c5a: Download complete - 73bd853d2ea5: Download complete - .... + Pulling repository ubuntu + ad57ef8d78d7: Download complete + 105182bb5e8b: Download complete + 511136ea3c5a: Download complete + 73bd853d2ea5: Download complete + .... - Status: Downloaded newer image for ubuntu - ``` + Status: Downloaded newer image for ubuntu + ``` - After the pull has completed use the `docker image ls` command (or the `docker images` - shorthand) to see the images that were pulled. The example below shows all the - `ubuntu` images that are present locally: + After the pull has completed use the `docker image ls` command (or the `docker images` + shorthand) to see the images that were pulled. The example below shows all the + `ubuntu` images that are present locally: - ```console - $ docker image ls --filter reference=ubuntu - REPOSITORY TAG IMAGE ID CREATED SIZE - ubuntu 18.04 c6ad7e71ba7d 5 weeks ago 63.2MB - ubuntu bionic c6ad7e71ba7d 5 weeks ago 63.2MB - ubuntu 22.04 5ccefbfc0416 2 months ago 78MB - ubuntu focal ff0fea8310f3 2 months ago 72.8MB - ubuntu latest ff0fea8310f3 2 months ago 72.8MB - ubuntu jammy 41ba606c8ab9 3 months ago 79MB - ubuntu 20.04 ba6acccedd29 7 months ago 72.8MB - ``` + ```console + $ docker image ls --filter reference=ubuntu + REPOSITORY TAG IMAGE ID CREATED SIZE + ubuntu 18.04 c6ad7e71ba7d 5 weeks ago 63.2MB + ubuntu bionic c6ad7e71ba7d 5 weeks ago 63.2MB + ubuntu 22.04 5ccefbfc0416 2 months ago 78MB + ubuntu focal ff0fea8310f3 2 months ago 72.8MB + ubuntu latest ff0fea8310f3 2 months ago 72.8MB + ubuntu jammy 41ba606c8ab9 3 months ago 79MB + ubuntu 20.04 ba6acccedd29 7 months ago 72.8MB + ``` - ### Cancel a pull + ### Cancel a pull - Killing the `docker pull` process, for example by pressing `CTRL-c` while it is - running in a terminal, will terminate the pull operation. + Killing the `docker pull` process, for example by pressing `CTRL-c` while it is + running in a terminal, will terminate the pull operation. - ```console - $ docker pull ubuntu + ```console + $ docker pull ubuntu - Using default tag: latest - latest: Pulling from library/ubuntu - a3ed95caeb02: Pulling fs layer - 236608c7b546: Pulling fs layer - ^C - ``` + Using default tag: latest + latest: Pulling from library/ubuntu + a3ed95caeb02: Pulling fs layer + 236608c7b546: Pulling fs layer + ^C + ``` - The Engine terminates a pull operation when the connection between the daemon - and the client (initiating the pull) is cut or lost for any reason or the - command is manually terminated. + The Engine terminates a pull operation when the connection between the daemon + and the client (initiating the pull) is cut or lost for any reason or the + command is manually terminated. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_push.yaml b/_data/engine-cli/docker_push.yaml index a9a9e63b47..dff261b424 100644 --- a/_data/engine-cli/docker_push.yaml +++ b/_data/engine-cli/docker_push.yaml @@ -1,136 +1,152 @@ command: docker push -short: Push an image or a repository to a registry +aliases: docker image push, docker push +short: Upload an image to a registry long: |- - Use `docker image push` to share your images to the [Docker Hub](https://hub.docker.com) - registry or to a self-hosted one. + Use `docker image push` to share your images to the [Docker Hub](https://hub.docker.com) + registry or to a self-hosted one. - Refer to the [`docker image tag`](tag.md) reference for more information about valid - image and tag names. + Refer to the [`docker image tag`](tag.md) reference for more information about valid + image and tag names. - Killing the `docker image push` process, for example by pressing `CTRL-c` while it is - running in a terminal, terminates the push operation. + Killing the `docker image push` process, for example by pressing `CTRL-c` while it is + running in a terminal, terminates the push operation. - Progress bars are shown during docker push, which show the uncompressed size. - The actual amount of data that's pushed will be compressed before sending, so - the uploaded size will not be reflected by the progress bar. + Progress bars are shown during docker push, which show the uncompressed size. + The actual amount of data that's pushed will be compressed before sending, so + the uploaded size will not be reflected by the progress bar. - Registry credentials are managed by [docker login](login.md). + Registry credentials are managed by [docker login](login.md). - ### Concurrent uploads + ### Concurrent uploads - By default the Docker daemon will push five layers of an image at a time. - If you are on a low bandwidth connection this may cause timeout issues and you may want to lower - this via the `--max-concurrent-uploads` daemon option. See the - [daemon documentation](dockerd.md) for more details. + By default the Docker daemon will push five layers of an image at a time. + If you are on a low bandwidth connection this may cause timeout issues and you may want to lower + this via the `--max-concurrent-uploads` daemon option. See the + [daemon documentation](dockerd.md) for more details. usage: docker push [OPTIONS] NAME[:TAG] pname: docker plink: docker.yaml options: -- option: all-tags - shorthand: a - value_type: bool - default_value: "false" - description: Push all tagged images in the repository - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image signing - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress verbose output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all-tags + shorthand: a + value_type: bool + default_value: "false" + description: Push all tags of an image to the repository + details_url: '#all-tags' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image signing + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Push a new image to a registry + ### Push a new image to a registry - First save the new image by finding the container ID (using [`docker container ls`](ps.md)) - and then committing it to a new image name. Note that only `a-z0-9-_.` are - allowed when naming images: + First save the new image by finding the container ID (using [`docker container ls`](ps.md)) + and then committing it to a new image name. Note that only `a-z0-9-_.` are + allowed when naming images: - ```console - $ docker container commit c16378f943fe rhel-httpd:latest - ``` + ```console + $ docker container commit c16378f943fe rhel-httpd:latest + ``` - Now, push the image to the registry using the image ID. In this example the - registry is on host named `registry-host` and listening on port `5000`. To do - this, tag the image with the host name or IP address, and the port of the - registry: + Now, push the image to the registry using the image ID. In this example the + registry is on host named `registry-host` and listening on port `5000`. To do + this, tag the image with the host name or IP address, and the port of the + registry: - ```console - $ docker image tag rhel-httpd:latest registry-host:5000/myadmin/rhel-httpd:latest + ```console + $ docker image tag rhel-httpd:latest registry-host:5000/myadmin/rhel-httpd:latest - $ docker image push registry-host:5000/myadmin/rhel-httpd:latest - ``` + $ docker image push registry-host:5000/myadmin/rhel-httpd:latest + ``` - Check that this worked by running: + Check that this worked by running: - ```console - $ docker image ls - ``` + ```console + $ docker image ls + ``` - You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` - listed. + You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` + listed. - ### Push all tags of an image (-a, --all-tags) + ### Push all tags of an image (-a, --all-tags) {#all-tags} - Use the `-a` (or `--all-tags`) option to push all tags of a local image. + Use the `-a` (or `--all-tags`) option to push all tags of a local image. - The following example creates multiple tags for an image, and pushes all those - tags to Docker Hub. + The following example creates multiple tags for an image, and pushes all those + tags to Docker Hub. - ```console - $ docker image tag myimage registry-host:5000/myname/myimage:latest - $ docker image tag myimage registry-host:5000/myname/myimage:v1.0.1 - $ docker image tag myimage registry-host:5000/myname/myimage:v1.0 - $ docker image tag myimage registry-host:5000/myname/myimage:v1 - ``` + ```console + $ docker image tag myimage registry-host:5000/myname/myimage:latest + $ docker image tag myimage registry-host:5000/myname/myimage:v1.0.1 + $ docker image tag myimage registry-host:5000/myname/myimage:v1.0 + $ docker image tag myimage registry-host:5000/myname/myimage:v1 + ``` - The image is now tagged under multiple names: + The image is now tagged under multiple names: - ```console - $ docker image ls + ```console + $ docker image ls - REPOSITORY TAG IMAGE ID CREATED SIZE - myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB - registry-host:5000/myname/myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB - registry-host:5000/myname/myimage v1 6d5fcfe5ff17 2 hours ago 1.22MB - registry-host:5000/myname/myimage v1.0 6d5fcfe5ff17 2 hours ago 1.22MB - registry-host:5000/myname/myimage v1.0.1 6d5fcfe5ff17 2 hours ago 1.22MB - ``` + REPOSITORY TAG IMAGE ID CREATED SIZE + myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB + registry-host:5000/myname/myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB + registry-host:5000/myname/myimage v1 6d5fcfe5ff17 2 hours ago 1.22MB + registry-host:5000/myname/myimage v1.0 6d5fcfe5ff17 2 hours ago 1.22MB + registry-host:5000/myname/myimage v1.0.1 6d5fcfe5ff17 2 hours ago 1.22MB + ``` - When pushing with the `--all-tags` option, all tags of the `registry-host:5000/myname/myimage` - image are pushed: + When pushing with the `--all-tags` option, all tags of the `registry-host:5000/myname/myimage` + image are pushed: - ```console - $ docker image push --all-tags registry-host:5000/myname/myimage + ```console + $ docker image push --all-tags registry-host:5000/myname/myimage - The push refers to repository [registry-host:5000/myname/myimage] - 195be5f8be1d: Pushed - latest: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 - 195be5f8be1d: Layer already exists - v1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 - 195be5f8be1d: Layer already exists - v1.0: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 - 195be5f8be1d: Layer already exists - v1.0.1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 - ``` + The push refers to repository [registry-host:5000/myname/myimage] + 195be5f8be1d: Pushed + latest: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 + 195be5f8be1d: Layer already exists + v1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 + 195be5f8be1d: Layer already exists + v1.0: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 + 195be5f8be1d: Layer already exists + v1.0.1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_rename.yaml b/_data/engine-cli/docker_rename.yaml index 76632cc667..06577118b7 100644 --- a/_data/engine-cli/docker_rename.yaml +++ b/_data/engine-cli/docker_rename.yaml @@ -1,13 +1,25 @@ command: docker rename +aliases: docker container rename, docker rename short: Rename a container long: The `docker rename` command renames a container. usage: docker rename CONTAINER NEW_NAME pname: docker plink: docker.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker rename my_container my_new_container - ``` + ```console + $ docker rename my_container my_new_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_restart.yaml b/_data/engine-cli/docker_restart.yaml index 48ba5d4b98..3c97eec4a1 100644 --- a/_data/engine-cli/docker_restart.yaml +++ b/_data/engine-cli/docker_restart.yaml @@ -1,24 +1,47 @@ command: docker restart +aliases: docker container restart, docker restart short: Restart one or more containers long: Restart one or more containers usage: docker restart [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml options: -- option: time - shorthand: t - value_type: int - default_value: "10" - description: Seconds to wait for stop before killing the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: signal + shorthand: s + value_type: string + description: Signal to send to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: time + shorthand: t + value_type: int + default_value: "0" + description: Seconds to wait before killing the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker restart my_container - ``` + ```console + $ docker restart my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_rm.yaml b/_data/engine-cli/docker_rm.yaml index 550d7bf7e8..95e6ac2033 100644 --- a/_data/engine-cli/docker_rm.yaml +++ b/_data/engine-cli/docker_rm.yaml @@ -1,129 +1,147 @@ command: docker rm +aliases: docker container rm, docker container remove, docker rm short: Remove one or more containers long: Remove one or more containers usage: docker rm [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force the removal of a running container (uses SIGKILL) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link - shorthand: l - value_type: bool - default_value: "false" - description: Remove the specified link - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volumes - shorthand: v - value_type: bool - default_value: "false" - description: Remove anonymous volumes associated with the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force the removal of a running container (uses SIGKILL) + details_url: '#force' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link + shorthand: l + value_type: bool + default_value: "false" + description: Remove the specified link + details_url: '#link' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volumes + shorthand: v + value_type: bool + default_value: "false" + description: Remove anonymous volumes associated with the container + details_url: '#volumes' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Remove a container + ### Remove a container - This removes the container referenced under the link `/redis`. + This removes the container referenced under the link `/redis`. - ```console - $ docker rm /redis + ```console + $ docker rm /redis - /redis - ``` + /redis + ``` - ### Remove a link specified with `--link` on the default bridge network (--link) + ### Remove a link specified with `--link` on the default bridge network (--link) {#link} - This removes the underlying link between `/webapp` and the `/redis` - containers on the default bridge network, removing all network communication - between the two containers. This does not apply when `--link` is used with - user-specified networks. + This removes the underlying link between `/webapp` and the `/redis` + containers on the default bridge network, removing all network communication + between the two containers. This does not apply when `--link` is used with + user-specified networks. - ```console - $ docker rm --link /webapp/redis + ```console + $ docker rm --link /webapp/redis - /webapp/redis - ``` + /webapp/redis + ``` - ### Force-remove a running container (--force) + ### Force-remove a running container (--force) {#force} - This command force-removes a running container. + This command force-removes a running container. - ```console - $ docker rm --force redis + ```console + $ docker rm --force redis - redis - ``` + redis + ``` - The main process inside the container referenced under the link `redis` will receive - `SIGKILL`, then the container will be removed. + The main process inside the container referenced under the link `redis` will receive + `SIGKILL`, then the container will be removed. - ### Remove all stopped containers + ### Remove all stopped containers - Use the [`docker container prune`](container_prune.md) command to remove all - stopped containers, or refer to the [`docker system prune`](system_prune.md) - command to remove unused containers in addition to other Docker resources, such - as (unused) images and networks. + Use the [`docker container prune`](container_prune.md) command to remove all + stopped containers, or refer to the [`docker system prune`](system_prune.md) + command to remove unused containers in addition to other Docker resources, such + as (unused) images and networks. - Alternatively, you can use the `docker ps` with the `-q` / `--quiet` option to - generate a list of container IDs to remove, and use that list as argument for - the `docker rm` command. + Alternatively, you can use the `docker ps` with the `-q` / `--quiet` option to + generate a list of container IDs to remove, and use that list as argument for + the `docker rm` command. - Combining commands can be more flexible, but is less portable as it depends - on features provided by the shell, and the exact syntax may differ depending on - what shell is used. To use this approach on Windows, consider using PowerShell - or Bash. + Combining commands can be more flexible, but is less portable as it depends + on features provided by the shell, and the exact syntax may differ depending on + what shell is used. To use this approach on Windows, consider using PowerShell + or Bash. - The example below uses `docker ps -q` to print the IDs of all containers that - have exited (`--filter status=exited`), and removes those containers with - the `docker rm` command: + The example below uses `docker ps -q` to print the IDs of all containers that + have exited (`--filter status=exited`), and removes those containers with + the `docker rm` command: - ```console - $ docker rm $(docker ps --filter status=exited -q) - ``` + ```console + $ docker rm $(docker ps --filter status=exited -q) + ``` - Or, using the `xargs` Linux utility; + Or, using the `xargs` Linux utility; - ```console - $ docker ps --filter status=exited -q | xargs docker rm - ``` + ```console + $ docker ps --filter status=exited -q | xargs docker rm + ``` - ### Remove a container and its volumes (-v, --volumes) + ### Remove a container and its volumes (-v, --volumes) {#volumes} - ```console - $ docker rm --volumes redis - redis - ``` + ```console + $ docker rm --volumes redis + redis + ``` - This command removes the container and any volumes associated with it. - Note that if a volume was specified with a name, it will not be removed. + This command removes the container and any volumes associated with it. + Note that if a volume was specified with a name, it will not be removed. - ### Remove a container and selectively remove volumes + ### Remove a container and selectively remove volumes - ```console - $ docker create -v awesome:/foo -v /bar --name hello redis - hello + ```console + $ docker create -v awesome:/foo -v /bar --name hello redis + hello - $ docker rm -v hello - ``` + $ docker rm -v hello + ``` - In this example, the volume for `/foo` remains intact, but the volume for - `/bar` is removed. The same behavior holds for volumes inherited with - `--volumes-from`. + In this example, the volume for `/foo` remains intact, but the volume for + `/bar` is removed. The same behavior holds for volumes inherited with + `--volumes-from`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_rmi.yaml b/_data/engine-cli/docker_rmi.yaml index 3697b458a8..504acd9f29 100644 --- a/_data/engine-cli/docker_rmi.yaml +++ b/_data/engine-cli/docker_rmi.yaml @@ -1,113 +1,127 @@ command: docker rmi +aliases: docker image rm, docker image remove, docker rmi short: Remove one or more images long: |- - Removes (and un-tags) one or more images from the host node. If an image has - multiple tags, using this command with the tag as a parameter only removes the - tag. If the tag is the only one for the image, both the image and the tag are - removed. + Removes (and un-tags) one or more images from the host node. If an image has + multiple tags, using this command with the tag as a parameter only removes the + tag. If the tag is the only one for the image, both the image and the tag are + removed. - This does not remove images from a registry. You cannot remove an image of a - running container unless you use the `-f` option. To see all images on a host - use the [`docker image ls`](images.md) command. + This does not remove images from a registry. You cannot remove an image of a + running container unless you use the `-f` option. To see all images on a host + use the [`docker image ls`](images.md) command. usage: docker rmi [OPTIONS] IMAGE [IMAGE...] pname: docker plink: docker.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force removal of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-prune - value_type: bool - default_value: "false" - description: Do not delete untagged parents - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force removal of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-prune + value_type: bool + default_value: "false" + description: Do not delete untagged parents + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - You can remove an image using its short or long ID, its tag, or its digest. If - an image has one or more tags referencing it, you must remove all of them before - the image is removed. Digest references are removed automatically when an image - is removed by tag. + You can remove an image using its short or long ID, its tag, or its digest. If + an image has one or more tags referencing it, you must remove all of them before + the image is removed. Digest references are removed automatically when an image + is removed by tag. - ```console - $ docker images + ```console + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + REPOSITORY TAG IMAGE ID CREATED SIZE + test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - $ docker rmi fd484f19954f + $ docker rmi fd484f19954f - Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force - 2013/12/11 05:47:16 Error: failed to remove one or more images + Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force + 2013/12/11 05:47:16 Error: failed to remove one or more images - $ docker rmi test1:latest + $ docker rmi test1:latest - Untagged: test1:latest + Untagged: test1:latest - $ docker rmi test2:latest + $ docker rmi test2:latest - Untagged: test2:latest + Untagged: test2:latest - $ docker images + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + REPOSITORY TAG IMAGE ID CREATED SIZE + test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - $ docker rmi test:latest + $ docker rmi test:latest - Untagged: test:latest - Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 - ``` + Untagged: test:latest + Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 + ``` - If you use the `-f` flag and specify the image's short or long ID, then this - command untags and removes all images that match the specified ID. + If you use the `-f` flag and specify the image's short or long ID, then this + command untags and removes all images that match the specified ID. - ```console - $ docker images + ```console + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + REPOSITORY TAG IMAGE ID CREATED SIZE + test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - $ docker rmi -f fd484f19954f + $ docker rmi -f fd484f19954f - Untagged: test1:latest - Untagged: test:latest - Untagged: test2:latest - Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 - ``` + Untagged: test1:latest + Untagged: test:latest + Untagged: test2:latest + Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 + ``` - An image pulled by digest has no tag associated with it: + An image pulled by digest has no tag associated with it: - ```console - $ docker images --digests + ```console + $ docker images --digests - REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE - localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB - ``` + REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE + localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB + ``` - To remove an image using its digest: + To remove an image using its digest: - ```console - $ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf - Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf - Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 - Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 - Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b - ``` + ```console + $ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf + Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf + Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 + Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 + Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_run.yaml b/_data/engine-cli/docker_run.yaml index 14b01ef1be..e26c6feb2a 100644 --- a/_data/engine-cli/docker_run.yaml +++ b/_data/engine-cli/docker_run.yaml @@ -1,1720 +1,1859 @@ command: docker run -short: Run a command in a new container +aliases: docker container run, docker run +short: Create and run a new container from an image long: |- - The `docker run` command first `creates` a writeable container layer over the - specified image, and then `starts` it using the specified command. That is, - `docker run` is equivalent to the API `/containers/create` then - `/containers/(id)/start`. A stopped container can be restarted with all its - previous changes intact using `docker start`. See `docker ps -a` to view a list - of all containers. + The `docker run` command first `creates` a writeable container layer over the + specified image, and then `starts` it using the specified command. That is, + `docker run` is equivalent to the API `/containers/create` then + `/containers/(id)/start`. A stopped container can be restarted with all its + previous changes intact using `docker start`. See `docker ps -a` to view a list + of all containers. - For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/). + For information on connecting a container to a network, see the ["*Docker network overview*"](/network/). usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker plink: docker.yaml options: -- option: add-host - value_type: list - description: Add a custom host-to-IP mapping (host:ip) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: attach - shorthand: a - value_type: list - description: Attach to STDIN, STDOUT or STDERR - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: blkio-weight - value_type: uint16 - default_value: "0" - description: | - Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: blkio-weight-device - value_type: list - default_value: '[]' - description: Block IO weight (relative device weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-add - value_type: list - description: Add Linux capabilities - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-drop - value_type: list - description: Drop Linux capabilities - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroup-parent - value_type: string - description: Optional parent cgroup for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroupns - value_type: string - description: |- - Cgroup namespace to use (host|private) - 'host': Run the container in the Docker host's cgroup namespace - 'private': Run the container in its own private cgroup namespace - '': Use the cgroup namespace as configured by the - default-cgroupns-mode option on the daemon (default) - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cidfile - value_type: string - description: Write the container ID to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-count - value_type: int64 - default_value: "0" - description: CPU count (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: cpu-percent - value_type: int64 - default_value: "0" - description: CPU percent (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-period - value_type: int64 - default_value: "0" - description: Limit CPU real-time period in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-runtime - value_type: int64 - default_value: "0" - description: Limit CPU real-time runtime in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpus - value_type: decimal - description: Number of CPUs - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: Run container in background and print container ID - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device - value_type: list - description: Add a host device to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-cgroup-rule - value_type: list - description: Add a rule to the cgroup allowed devices list - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-read-bps - value_type: list - default_value: '[]' - description: Limit read rate (bytes per second) from a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-read-iops - value_type: list - default_value: '[]' - description: Limit read rate (IO per second) from a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-write-bps - value_type: list - default_value: '[]' - description: Limit write rate (bytes per second) to a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: device-write-iops - value_type: list - default_value: '[]' - description: Limit write rate (IO per second) to a device - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: disable-content-trust - value_type: bool - default_value: "true" - description: Skip image verification - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns - value_type: list - description: Set custom DNS servers - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-opt - value_type: list - description: Set DNS options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-option - value_type: list - description: Set DNS options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-search - value_type: list - description: Set custom DNS search domains - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: domainname - value_type: string - description: Container NIS domain name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: entrypoint - value_type: string - description: Overwrite the default ENTRYPOINT of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env - shorthand: e - value_type: list - description: Set environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-file - value_type: list - description: Read in a file of environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: expose - value_type: list - description: Expose a port or a range of ports - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: gpus - value_type: gpu-request - description: GPU devices to add to the container ('all' to pass all GPUs) - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: group-add - value_type: list - description: Add additional groups to join - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-cmd - value_type: string - description: Command to run to check health - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-interval - value_type: duration - default_value: 0s - description: Time between running the check (ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-retries - value_type: int - default_value: "0" - description: Consecutive failures needed to report unhealthy - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-start-period - value_type: duration - default_value: 0s - description: | - Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-timeout - value_type: duration - default_value: 0s - description: | - Maximum time to allow one check to run (ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: help - value_type: bool - default_value: "false" - description: Print usage - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: hostname - shorthand: h - value_type: string - description: Container host name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: init - value_type: bool - default_value: "false" - description: | - Run an init inside the container that forwards signals and reaps processes - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Keep STDIN open even if not attached - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: io-maxbandwidth - value_type: bytes - default_value: "0" - description: | - Maximum IO bandwidth limit for the system drive (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: io-maxiops - value_type: uint64 - default_value: "0" - description: Maximum IOps limit for the system drive (Windows only) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - os_type: windows -- option: ip - value_type: string - description: IPv4 address (e.g., 172.30.100.104) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ip6 - value_type: string - description: IPv6 address (e.g., 2001:db8::33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ipc - value_type: string - description: IPC mode to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Container isolation technology - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kernel-memory - value_type: bytes - default_value: "0" - description: Kernel memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - shorthand: l - value_type: list - description: Set meta data on a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label-file - value_type: list - description: Read in a line delimited file of labels - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link - value_type: list - description: Add link to another container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: link-local-ip - value_type: list - description: Container IPv4/IPv6 link-local addresses - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-driver - value_type: string - description: Logging driver for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-opt - value_type: list - description: Log driver options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mac-address - value_type: string - description: Container MAC address (e.g., 92:d0:c6:0a:29:33) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-reservation - value_type: bytes - default_value: "0" - description: Memory soft limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swappiness - value_type: int64 - default_value: "-1" - description: Tune container memory swappiness (0 to 100) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mount - value_type: mount - description: Attach a filesystem mount to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: name - value_type: string - description: Assign a name to the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: net - value_type: network - description: Connect a container to a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: net-alias - value_type: list - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: network - description: Connect a container to a network - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network-alias - value_type: list - description: Add network-scoped alias for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-healthcheck - value_type: bool - default_value: "false" - description: Disable any container-specified HEALTHCHECK - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: oom-kill-disable - value_type: bool - default_value: "false" - description: Disable OOM Killer - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: oom-score-adj - value_type: int - default_value: "0" - description: Tune host's OOM preferences (-1000 to 1000) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pid - value_type: string - description: PID namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pids-limit - value_type: int64 - default_value: "0" - description: Tune container pids limit (set -1 for unlimited) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: string - description: Set platform if server is multi-platform capable - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: privileged - value_type: bool - default_value: "false" - description: Give extended privileges to this container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish - shorthand: p - value_type: list - description: Publish a container's port(s) to the host - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish-all - shorthand: P - value_type: bool - default_value: "false" - description: Publish all exposed ports to random ports - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: string - default_value: missing - description: Pull image before running ("always"|"missing"|"never") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: read-only - value_type: bool - default_value: "false" - description: Mount the container's root filesystem as read only - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart - value_type: string - default_value: "no" - description: Restart policy to apply when a container exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rm - value_type: bool - default_value: "false" - description: Automatically remove the container when it exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: runtime - value_type: string - description: Runtime to use for this container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: security-opt - value_type: list - description: Security Options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: shm-size - value_type: bytes - default_value: "0" - description: Size of /dev/shm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sig-proxy - value_type: bool - default_value: "true" - description: Proxy received signals to the process - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-signal - value_type: string - default_value: SIGTERM - description: Signal to stop a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-timeout - value_type: int - default_value: "0" - description: Timeout (in seconds) to stop a container - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: storage-opt - value_type: list - description: Storage driver options for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sysctl - value_type: map - default_value: map[] - description: Sysctl options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tmpfs - value_type: list - description: Mount a tmpfs directory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: ulimit - default_value: '[]' - description: Ulimit options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: userns - value_type: string - description: User namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: uts - value_type: string - description: UTS namespace to use - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volume - shorthand: v - value_type: list - description: Bind mount a volume - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volume-driver - value_type: string - description: Optional volume driver for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volumes-from - value_type: list - description: Mount volumes from the specified container(s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: add-host + value_type: list + description: Add a custom host-to-IP mapping (host:ip) + details_url: '#add-host' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: attach + shorthand: a + value_type: list + description: Attach to STDIN, STDOUT or STDERR + details_url: '#attach' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: blkio-weight + value_type: uint16 + default_value: "0" + description: | + Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: blkio-weight-device + value_type: list + default_value: '[]' + description: Block IO weight (relative device weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-add + value_type: list + description: Add Linux capabilities + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-drop + value_type: list + description: Drop Linux capabilities + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cgroupns + value_type: string + description: |- + Cgroup namespace to use (host|private) + 'host': Run the container in the Docker host's cgroup namespace + 'private': Run the container in its own private cgroup namespace + '': Use the cgroup namespace as configured by the + default-cgroupns-mode option on the daemon (default) + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cidfile + value_type: string + description: Write the container ID to the file + details_url: '#cidfile' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-count + value_type: int64 + default_value: "0" + description: CPU count (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: cpu-percent + value_type: int64 + default_value: "0" + description: CPU percent (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-period + value_type: int64 + default_value: "0" + description: Limit CPU real-time period in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-runtime + value_type: int64 + default_value: "0" + description: Limit CPU real-time runtime in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpus + value_type: decimal + description: Number of CPUs + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: Run container in background and print container ID + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach-keys + value_type: string + description: Override the key sequence for detaching a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device + value_type: list + description: Add a host device to the container + details_url: '#device' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-cgroup-rule + value_type: list + description: Add a rule to the cgroup allowed devices list + details_url: '#device-cgroup-rule' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-read-bps + value_type: list + default_value: '[]' + description: Limit read rate (bytes per second) from a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-read-iops + value_type: list + default_value: '[]' + description: Limit read rate (IO per second) from a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-write-bps + value_type: list + default_value: '[]' + description: Limit write rate (bytes per second) to a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: device-write-iops + value_type: list + default_value: '[]' + description: Limit write rate (IO per second) to a device + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns + value_type: list + description: Set custom DNS servers + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-opt + value_type: list + description: Set DNS options + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-option + value_type: list + description: Set DNS options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-search + value_type: list + description: Set custom DNS search domains + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: domainname + value_type: string + description: Container NIS domain name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: entrypoint + value_type: string + description: Overwrite the default ENTRYPOINT of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env + shorthand: e + value_type: list + description: Set environment variables + details_url: '#env' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: expose + value_type: list + description: Expose a port or a range of ports + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: gpus + value_type: gpu-request + description: GPU devices to add to the container ('all' to pass all GPUs) + details_url: '#gpus' + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: group-add + value_type: list + description: Add additional groups to join + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-cmd + value_type: string + description: Command to run to check health + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-interval + value_type: duration + default_value: 0s + description: Time between running the check (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-retries + value_type: int + default_value: "0" + description: Consecutive failures needed to report unhealthy + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-start-period + value_type: duration + default_value: 0s + description: | + Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-timeout + value_type: duration + default_value: 0s + description: Maximum time to allow one check to run (ms|s|m|h) (default 0s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: hostname + shorthand: h + value_type: string + description: Container host name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: init + value_type: bool + default_value: "false" + description: | + Run an init inside the container that forwards signals and reaps processes + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: interactive + shorthand: i + value_type: bool + default_value: "false" + description: Keep STDIN open even if not attached + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: io-maxbandwidth + value_type: bytes + default_value: "0" + description: Maximum IO bandwidth limit for the system drive (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: io-maxiops + value_type: uint64 + default_value: "0" + description: Maximum IOps limit for the system drive (Windows only) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + os_type: windows + - option: ip + value_type: string + description: IPv4 address (e.g., 172.30.100.104) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ip6 + value_type: string + description: IPv6 address (e.g., 2001:db8::33) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ipc + value_type: string + description: IPC mode to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Container isolation technology + details_url: '#isolation' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: kernel-memory + value_type: bytes + default_value: "0" + description: Kernel memory limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + shorthand: l + value_type: list + description: Set meta data on a container + details_url: '#label' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label-file + value_type: list + description: Read in a line delimited file of labels + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link + value_type: list + description: Add link to another container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: link-local-ip + value_type: list + description: Container IPv4/IPv6 link-local addresses + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-driver + value_type: string + description: Logging driver for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-opt + value_type: list + description: Log driver options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mac-address + value_type: string + description: Container MAC address (e.g., 92:d0:c6:0a:29:33) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + details_url: '#memory' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-reservation + value_type: bytes + default_value: "0" + description: Memory soft limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: | + Swap limit equal to memory plus swap: '-1' to enable unlimited swap + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swappiness + value_type: int64 + default_value: "-1" + description: Tune container memory swappiness (0 to 100) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mount + value_type: mount + description: Attach a filesystem mount to the container + details_url: '#mount' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: name + value_type: string + description: Assign a name to the container + details_url: '#name' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: net + value_type: network + description: Connect a container to a network + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: net-alias + value_type: list + description: Add network-scoped alias for the container + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: network + description: Connect a container to a network + details_url: '#network' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network-alias + value_type: list + description: Add network-scoped alias for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-healthcheck + value_type: bool + default_value: "false" + description: Disable any container-specified HEALTHCHECK + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: oom-kill-disable + value_type: bool + default_value: "false" + description: Disable OOM Killer + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: oom-score-adj + value_type: int + default_value: "0" + description: Tune host's OOM preferences (-1000 to 1000) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pid + value_type: string + description: PID namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pids-limit + value_type: int64 + default_value: "0" + description: Tune container pids limit (set -1 for unlimited) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: privileged + value_type: bool + default_value: "false" + description: Give extended privileges to this container + details_url: '#privileged' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish + shorthand: p + value_type: list + description: Publish a container's port(s) to the host + details_url: '#publish' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish-all + shorthand: P + value_type: bool + default_value: "false" + description: Publish all exposed ports to random ports + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pull + value_type: string + default_value: missing + description: Pull image before running (`always`, `missing`, `never`) + details_url: '#pull' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the pull output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: read-only + value_type: bool + default_value: "false" + description: Mount the container's root filesystem as read only + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart + value_type: string + default_value: "no" + description: Restart policy to apply when a container exits + details_url: '#restart' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rm + value_type: bool + default_value: "false" + description: Automatically remove the container when it exits + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: runtime + value_type: string + description: Runtime to use for this container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: security-opt + value_type: list + description: Security Options + details_url: '#security-opt' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: shm-size + value_type: bytes + default_value: "0" + description: Size of /dev/shm + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sig-proxy + value_type: bool + default_value: "true" + description: Proxy received signals to the process + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-signal + value_type: string + description: Signal to stop the container + details_url: '#stop-signal' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-timeout + value_type: int + default_value: "0" + description: Timeout (in seconds) to stop a container + details_url: '#stop-timeout' + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: storage-opt + value_type: list + description: Storage driver options for the container + details_url: '#storage-opt' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sysctl + value_type: map + default_value: map[] + description: Sysctl options + details_url: '#sysctl' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tmpfs + value_type: list + description: Mount a tmpfs directory + details_url: '#tmpfs' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tty + shorthand: t + value_type: bool + default_value: "false" + description: Allocate a pseudo-TTY + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + details_url: '#ulimit' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: user + shorthand: u + value_type: string + description: 'Username or UID (format: [:])' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: userns + value_type: string + description: User namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: uts + value_type: string + description: UTS namespace to use + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume + shorthand: v + value_type: list + description: Bind mount a volume + details_url: '#volume' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume-driver + value_type: string + description: Optional volume driver for the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volumes-from + value_type: list + description: Mount volumes from the specified container(s) + details_url: '#volumes-from' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workdir + shorthand: w + value_type: string + description: Working directory inside the container + details_url: '#workdir' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Assign name and allocate pseudo-TTY (--name, -it) - - ```console - $ docker run --name test -it debian - - root@d6c0fe130dba:/# exit 13 - $ echo $? - 13 - $ docker ps -a | grep test - d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test - ``` - - This example runs a container named `test` using the `debian:latest` - image. The `-it` instructs Docker to allocate a pseudo-TTY connected to - the container's stdin; creating an interactive `bash` shell in the container. - In the example, the `bash` shell is quit by entering - `exit 13`. This exit code is passed on to the caller of - `docker run`, and is recorded in the `test` container's metadata. - - ### Capture container ID (--cidfile) - - ```console - $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" - ``` - - This will create a container and print `test` to the console. The `cidfile` - flag makes Docker attempt to create a new file and write the container ID to it. - If the file exists already, Docker will return an error. Docker will close this - file when `docker run` exits. - - ### Full container capabilities (--privileged) - - ```console - $ docker run -t -i --rm ubuntu bash - root@bc338942ef20:/# mount -t tmpfs none /mnt - mount: permission denied - ``` - - This will *not* work, because by default, most potentially dangerous kernel - capabilities are dropped; including `cap_sys_admin` (which is required to mount - filesystems). However, the `--privileged` flag will allow it to run: - - ```console - $ docker run -t -i --privileged ubuntu bash - root@50e3f57e16e6:/# mount -t tmpfs none /mnt - root@50e3f57e16e6:/# df -h - Filesystem Size Used Avail Use% Mounted on - none 1.9G 0 1.9G 0% /mnt - ``` - - The `--privileged` flag gives *all* capabilities to the container, and it also - lifts all the limitations enforced by the `device` cgroup controller. In other - words, the container can then do almost everything that the host can do. This - flag exists to allow special use-cases, like running Docker within Docker. - - ### Set working directory (-w, --workdir) - - ```console - $ docker run -w /path/to/dir/ -i -t ubuntu pwd - ``` - - The `-w` lets the command being executed inside directory given, here - `/path/to/dir/`. If the path does not exist it is created inside the container. - - ### Set storage driver options per container (--storage-opt) + ### Assign name and allocate pseudo-TTY (--name, -it) {#name} + + ```console + $ docker run --name test -it debian + + root@d6c0fe130dba:/# exit 13 + $ echo $? + 13 + $ docker ps -a | grep test + d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test + ``` + + This example runs a container named `test` using the `debian:latest` + image. The `-it` instructs Docker to allocate a pseudo-TTY connected to + the container's stdin; creating an interactive `bash` shell in the container. + In the example, the `bash` shell is quit by entering + `exit 13`. This exit code is passed on to the caller of + `docker run`, and is recorded in the `test` container's metadata. + + ### Capture container ID (--cidfile) {#cidfile} + + ```console + $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" + ``` + + This will create a container and print `test` to the console. The `cidfile` + flag makes Docker attempt to create a new file and write the container ID to it. + If the file exists already, Docker will return an error. Docker will close this + file when `docker run` exits. + + ### Full container capabilities (--privileged) {#privileged} + + ```console + $ docker run -t -i --rm ubuntu bash + root@bc338942ef20:/# mount -t tmpfs none /mnt + mount: permission denied + ``` + + This will *not* work, because by default, most potentially dangerous kernel + capabilities are dropped; including `cap_sys_admin` (which is required to mount + filesystems). However, the `--privileged` flag will allow it to run: + + ```console + $ docker run -t -i --privileged ubuntu bash + root@50e3f57e16e6:/# mount -t tmpfs none /mnt + root@50e3f57e16e6:/# df -h + Filesystem Size Used Avail Use% Mounted on + none 1.9G 0 1.9G 0% /mnt + ``` + + The `--privileged` flag gives *all* capabilities to the container, and it also + lifts all the limitations enforced by the `device` cgroup controller. In other + words, the container can then do almost everything that the host can do. This + flag exists to allow special use-cases, like running Docker within Docker. + + ### Set working directory (-w, --workdir) {#workdir} + + ```console + $ docker run -w /path/to/dir/ -i -t ubuntu pwd + ``` + + The `-w` lets the command being executed inside directory given, here + `/path/to/dir/`. If the path does not exist it is created inside the container. + + ### Set storage driver options per container (--storage-opt) {#storage-opt} - ```console - $ docker run -it --storage-opt size=120G fedora /bin/bash - ``` + ```console + $ docker run -it --storage-opt size=120G fedora /bin/bash + ``` - This (size) will allow to set the container filesystem size to 120G at creation time. - This option is only available for the `devicemapper`, `btrfs`, `overlay2`, - `windowsfilter` and `zfs` graph drivers. - For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, - user cannot pass a size less than the Default BaseFS Size. - For the `overlay2` storage driver, the size option is only available if the - backing filesystem is `xfs` and mounted with the `pquota` mount option. - Under these conditions, user can pass any size less than the backing filesystem size. + This (size) will allow to set the container filesystem size to 120G at creation time. + This option is only available for the `devicemapper`, `btrfs`, `overlay2`, + `windowsfilter` and `zfs` graph drivers. + For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, + user cannot pass a size less than the Default BaseFS Size. + For the `overlay2` storage driver, the size option is only available if the + backing filesystem is `xfs` and mounted with the `pquota` mount option. + Under these conditions, user can pass any size less than the backing filesystem size. - ### Mount tmpfs (--tmpfs) + ### Mount tmpfs (--tmpfs) {#tmpfs} - ```console - $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image - ``` + ```console + $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image + ``` - The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, - `noexec`, `nosuid`, `size=65536k` options. + The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, + `noexec`, `nosuid`, `size=65536k` options. - ### Mount volume (-v, --read-only) + ### Mount volume (-v, --read-only) {#volume} - ```console - $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd - ``` + ```console + $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd + ``` - The `-v` flag mounts the current working directory into the container. The `-w` - lets the command being executed inside the current working directory, by - changing into the directory to the value returned by `pwd`. So this - combination executes the command using the container, but inside the - current working directory. + The `-v` flag mounts the current working directory into the container. The `-w` + lets the command being executed inside the current working directory, by + changing into the directory to the value returned by `pwd`. So this + combination executes the command using the container, but inside the + current working directory. - ```console - $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash - ``` + ```console + $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash + ``` - When the host directory of a bind-mounted volume doesn't exist, Docker - will automatically create this directory on the host for you. In the - example above, Docker will create the `/doesnt/exist` - folder before starting your container. + When the host directory of a bind-mounted volume doesn't exist, Docker + will automatically create this directory on the host for you. In the + example above, Docker will create the `/doesnt/exist` + folder before starting your container. - ```console - $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here - ``` + ```console + $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here + ``` - Volumes can be used in combination with `--read-only` to control where - a container writes files. The `--read-only` flag mounts the container's root - filesystem as read only prohibiting writes to locations other than the - specified volumes for the container. + Volumes can be used in combination with `--read-only` to control where + a container writes files. The `--read-only` flag mounts the container's root + filesystem as read only prohibiting writes to locations other than the + specified volumes for the container. - ```console - $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh - ``` + ```console + $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh + ``` - By bind-mounting the Docker Unix socket and statically linked Docker - binary (refer to [get the Linux binary](https://docs.docker.com/engine/install/binaries/#install-static-binaries)), - you give the container the full access to create and manipulate the host's - Docker daemon. + By bind-mounting the Docker Unix socket and statically linked Docker + binary (refer to [get the Linux binary](/engine/install/binaries/#install-static-binaries)), + you give the container the full access to create and manipulate the host's + Docker daemon. - On Windows, the paths must be specified using Windows-style semantics. + On Windows, the paths must be specified using Windows-style semantics. - ```powershell - PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt - Contents of file + ```powershell + PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt + Contents of file - PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt - Contents of file - ``` + PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt + Contents of file + ``` - The following examples will fail when using Windows-based containers, as the - destination of a volume or bind mount inside the container must be one of: - a non-existing or empty directory; or a drive other than C:. Further, the source - of a bind mount must be a local directory, not a file. + The following examples will fail when using Windows-based containers, as the + destination of a volume or bind mount inside the container must be one of: + a non-existing or empty directory; or a drive other than C:. Further, the source + of a bind mount must be a local directory, not a file. - ```powershell - net use z: \\remotemachine\share - docker run -v z:\foo:c:\dest ... - docker run -v \\uncpath\to\directory:c:\dest ... - docker run -v c:\foo\somefile.txt:c:\dest ... - docker run -v c:\foo:c: ... - docker run -v c:\foo:c:\existing-directory-with-contents ... - ``` + ```powershell + net use z: \\remotemachine\share + docker run -v z:\foo:c:\dest ... + docker run -v \\uncpath\to\directory:c:\dest ... + docker run -v c:\foo\somefile.txt:c:\dest ... + docker run -v c:\foo:c: ... + docker run -v c:\foo:c:\existing-directory-with-contents ... + ``` - For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/) + For in-depth information about volumes, refer to [manage data in containers](/storage/volumes/) - ### Add bind mounts or volumes using the --mount flag + ### Add bind mounts or volumes using the --mount flag {#mount} - The `--mount` flag allows you to mount volumes, host-directories and `tmpfs` - mounts in a container. + The `--mount` flag allows you to mount volumes, host-directories and `tmpfs` + mounts in a container. - The `--mount` flag supports most options that are supported by the `-v` or the - `--volume` flag, but uses a different syntax. For in-depth information on the - `--mount` flag, and a comparison between `--volume` and `--mount`, refer to - [Bind mounts](https://docs.docker.com/storage/bind-mounts/). + The `--mount` flag supports most options that are supported by the `-v` or the + `--volume` flag, but uses a different syntax. For in-depth information on the + `--mount` flag, and a comparison between `--volume` and `--mount`, refer to + [Bind mounts](/storage/bind-mounts/). - Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended. + Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended. - Examples: + Examples: - ```console - $ docker run --read-only --mount type=volume,target=/icanwrite busybox touch /icanwrite/here - ``` + ```console + $ docker run --read-only --mount type=volume,target=/icanwrite busybox touch /icanwrite/here + ``` - ```console - $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh - ``` + ```console + $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh + ``` - ### Publish or expose port (-p, --expose) + ### Publish or expose port (-p, --expose) {#publish} - ```console - $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash - ``` + ```console + $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash + ``` - This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host - machine. You can also specify `udp` and `sctp` ports. - The [Docker User Guide](https://docs.docker.com/network/links/) - explains in detail how to manipulate ports in Docker. + This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host + machine. You can also specify `udp` and `sctp` ports. + The [Docker User Guide](/network/links/) + explains in detail how to manipulate ports in Docker. - Note that ports which are not bound to the host (i.e., `-p 80:80` instead of - `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if - you configured UFW to block this specific port, as Docker manages its - own iptables rules. [Read more](https://docs.docker.com/network/iptables/) + Note that ports which are not bound to the host (i.e., `-p 80:80` instead of + `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if + you configured UFW to block this specific port, as Docker manages its + own iptables rules. [Read more](/network/iptables/) - ```console - $ docker run --expose 80 ubuntu bash - ``` + ```console + $ docker run --expose 80 ubuntu bash + ``` - This exposes port `80` of the container without publishing the port to the host - system's interfaces. + This exposes port `80` of the container without publishing the port to the host + system's interfaces. - ### Set the pull policy (--pull) + ### Set the pull policy (--pull) {#pull} - Use the `--pull` flag to set the image pull policy when creating (and running) - the container. + Use the `--pull` flag to set the image pull policy when creating (and running) + the container. - The `--pull` flag can take one of these values: + The `--pull` flag can take one of these values: - | Value | Description | - |:--------------------|:------------------------------------------------------------------------------------------------------------------| - | `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise. | - | `never` | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. | - | `always` | Always perform a pull before creating the container. | + | Value | Description | + |:--------------------|:------------------------------------------------------------------------------------------------------------------| + | `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise. | + | `never` | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. | + | `always` | Always perform a pull before creating the container. | - When creating (and running) a container from an image, the daemon checks if the - image exists in the local image cache. If the image is missing, an error is - returned to the CLI, allowing it to initiate a pull. + When creating (and running) a container from an image, the daemon checks if the + image exists in the local image cache. If the image is missing, an error is + returned to the CLI, allowing it to initiate a pull. - The default (`missing`) is to only pull the image if it is not present in the - daemon's image cache. This default allows you to run images that only exist - locally (for example, images you built from a Dockerfile, but that have not - been pushed to a registry), and reduces networking. + The default (`missing`) is to only pull the image if it is not present in the + daemon's image cache. This default allows you to run images that only exist + locally (for example, images you built from a Dockerfile, but that have not + been pushed to a registry), and reduces networking. - The `always` option always initiates a pull before creating the container. This - option makes sure the image is up-to-date, and prevents you from using outdated - images, but may not be suitable in situations where you want to test a locally - built image before pushing (as pulling the image overwrites the existing image - in the image cache). + The `always` option always initiates a pull before creating the container. This + option makes sure the image is up-to-date, and prevents you from using outdated + images, but may not be suitable in situations where you want to test a locally + built image before pushing (as pulling the image overwrites the existing image + in the image cache). - The `never` option disables (implicit) pulling images when creating containers, - and only uses images that are available in the image cache. If the specified - image is not found, an error is produced, and the container is not created. - This option is useful in situations where networking is not available, or to - prevent images from being pulled implicitly when creating containers. + The `never` option disables (implicit) pulling images when creating containers, + and only uses images that are available in the image cache. If the specified + image is not found, an error is produced, and the container is not created. + This option is useful in situations where networking is not available, or to + prevent images from being pulled implicitly when creating containers. - The following example shows `docker run` with the `--pull=never` option set, - which produces en error as the image is missing in the image-cache: + The following example shows `docker run` with the `--pull=never` option set, + which produces en error as the image is missing in the image-cache: - ```console - $ docker run --pull=never hello-world - docker: Error response from daemon: No such image: hello-world:latest. - ``` + ```console + $ docker run --pull=never hello-world + docker: Error response from daemon: No such image: hello-world:latest. + ``` - ### Set environment variables (-e, --env, --env-file) + ### Set environment variables (-e, --env, --env-file) {#env} - ```console - $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash - ``` + ```console + $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash + ``` - Use the `-e`, `--env`, and `--env-file` flags to set simple (non-array) - environment variables in the container you're running, or overwrite variables - that are defined in the Dockerfile of the image you're running. + Use the `-e`, `--env`, and `--env-file` flags to set simple (non-array) + environment variables in the container you're running, or overwrite variables + that are defined in the Dockerfile of the image you're running. - You can define the variable and its value when running the container: + You can define the variable and its value when running the container: - ```console - $ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR - VAR1=value1 - VAR2=value2 - ``` + ```console + $ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR + VAR1=value1 + VAR2=value2 + ``` - You can also use variables that you've exported to your local environment: + You can also use variables that you've exported to your local environment: - ```console - export VAR1=value1 - export VAR2=value2 + ```console + export VAR1=value1 + export VAR2=value2 - $ docker run --env VAR1 --env VAR2 ubuntu env | grep VAR - VAR1=value1 - VAR2=value2 - ``` + $ docker run --env VAR1 --env VAR2 ubuntu env | grep VAR + VAR1=value1 + VAR2=value2 + ``` - When running the command, the Docker CLI client checks the value the variable - has in your local environment and passes it to the container. - If no `=` is provided and that variable is not exported in your local - environment, the variable won't be set in the container. + When running the command, the Docker CLI client checks the value the variable + has in your local environment and passes it to the container. + If no `=` is provided and that variable is not exported in your local + environment, the variable won't be set in the container. - You can also load the environment variables from a file. This file should use - the syntax `=value` (which sets the variable to the given value) or - `` (which takes the value from the local environment), and `#` for comments. + You can also load the environment variables from a file. This file should use + the syntax `=value` (which sets the variable to the given value) or + `` (which takes the value from the local environment), and `#` for comments. - ```console - $ cat env.list - # This is a comment - VAR1=value1 - VAR2=value2 - USER + ```console + $ cat env.list + # This is a comment + VAR1=value1 + VAR2=value2 + USER - $ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER' - VAR1=value1 - VAR2=value2 - USER=jonzeolla - ``` + $ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER' + VAR1=value1 + VAR2=value2 + USER=jonzeolla + ``` - ### Set metadata on container (-l, --label, --label-file) - - A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: + ### Set metadata on container (-l, --label, --label-file) {#label} + + A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: - ```console - $ docker run -l my-label --label com.example.foo=bar ubuntu bash - ``` - - The `my-label` key doesn't specify a value so the label defaults to an empty - string (`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). - - The `key=value` must be unique to avoid overwriting the label value. If you - specify labels with identical keys but different values, each subsequent value - overwrites the previous. Docker uses the last `key=value` you supply. - - Use the `--label-file` flag to load multiple labels from a file. Delimit each - label in the file with an EOL mark. The example below loads labels from a - labels file in the current directory: - - ```console - $ docker run --label-file ./labels ubuntu bash - ``` - - The label-file format is similar to the format for loading environment - variables. (Unlike environment variables, labels are not visible to processes - running inside a container.) The following example illustrates a label-file - format: + ```console + $ docker run -l my-label --label com.example.foo=bar ubuntu bash + ``` + + The `my-label` key doesn't specify a value so the label defaults to an empty + string (`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). + + The `key=value` must be unique to avoid overwriting the label value. If you + specify labels with identical keys but different values, each subsequent value + overwrites the previous. Docker uses the last `key=value` you supply. + + Use the `--label-file` flag to load multiple labels from a file. Delimit each + label in the file with an EOL mark. The example below loads labels from a + labels file in the current directory: + + ```console + $ docker run --label-file ./labels ubuntu bash + ``` + + The label-file format is similar to the format for loading environment + variables. (Unlike environment variables, labels are not visible to processes + running inside a container.) The following example illustrates a label-file + format: - ```console - com.example.label1="a label" - - # this is a comment - com.example.label2=another\ label - com.example.label3 - ``` + ```console + com.example.label1="a label" + + # this is a comment + com.example.label2=another\ label + com.example.label3 + ``` - You can load multiple label-files by supplying multiple `--label-file` flags. + You can load multiple label-files by supplying multiple `--label-file` flags. - For additional information on working with labels, see [*Labels - custom - metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in - the Docker User Guide. + For additional information on working with labels, see [*Labels - custom + metadata in Docker*](/config/labels-custom-metadata/) in + the Docker User Guide. - ### Connect a container to a network (--network) + ### Connect a container to a network (--network) {#network} - When you start a container use the `--network` flag to connect it to a network. - The following commands create a network named `my-net`, and adds a `busybox` container - to the `my-net` network. + When you start a container use the `--network` flag to connect it to a network. + The following commands create a network named `my-net`, and adds a `busybox` container + to the `my-net` network. - ```console - $ docker network create my-net - $ docker run -itd --network=my-net busybox - ``` - - You can also choose the IP addresses for the container with `--ip` and `--ip6` - flags when you start the container on a user-defined network. - - ```console - $ docker run -itd --network=my-net --ip=10.10.9.75 busybox - ``` - - If you want to add a running container to a network use the `docker network connect` subcommand. - - You can connect multiple containers to the same network. Once connected, the - containers can communicate easily using only another container's IP address - or name. For `overlay` networks or custom plugins that support multi-host - connectivity, containers connected to the same multi-host network but launched - from different Engines can also communicate in this way. - - > **Note** - > - > The default bridge network only allow containers to communicate with each other using - > internal IP addresses. User-created bridge networks provide DNS resolution between - > containers using container names. + ```console + $ docker network create my-net + $ docker run -itd --network=my-net busybox + ``` + + You can also choose the IP addresses for the container with `--ip` and `--ip6` + flags when you start the container on a user-defined network. + + ```console + $ docker run -itd --network=my-net --ip=10.10.9.75 busybox + ``` + + If you want to add a running container to a network use the `docker network connect` subcommand. + + You can connect multiple containers to the same network. Once connected, the + containers can communicate easily using only another container's IP address + or name. For `overlay` networks or custom plugins that support multi-host + connectivity, containers connected to the same multi-host network but launched + from different Engines can also communicate in this way. + + > **Note** + > + > The default bridge network only allow containers to communicate with each other using + > internal IP addresses. User-created bridge networks provide DNS resolution between + > containers using container names. - You can disconnect a container from a network using the `docker network - disconnect` command. + You can disconnect a container from a network using the `docker network + disconnect` command. - ### Mount volumes from container (--volumes-from) + ### Mount volumes from container (--volumes-from) {#volumes-from} - ```console - $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd - ``` + ```console + $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd + ``` - The `--volumes-from` flag mounts all the defined volumes from the referenced - containers. Containers can be specified by repetitions of the `--volumes-from` - argument. The container ID may be optionally suffixed with `:ro` or `:rw` to - mount the volumes in read-only or read-write mode, respectively. By default, - the volumes are mounted in the same mode (read write or read only) as - the reference container. - - Labeling systems like SELinux require that proper labels are placed on volume - content mounted into a container. Without a label, the security system might - prevent the processes running inside the container from using the content. By - default, Docker does not change the labels set by the OS. - - To change the label in the container context, you can add either of two suffixes - `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file - objects on the shared volumes. The `z` option tells Docker that two containers - share the volume content. As a result, Docker labels the content with a shared - content label. Shared volume labels allow all containers to read/write content. - The `Z` option tells Docker to label the content with a private unshared label. - Only the current container can use a private volume. - - ### Attach to STDIN/STDOUT/STDERR (-a, --attach) - - The `--attach` (or `-a`) flag tells `docker run` to bind to the container's - `STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output - and input as needed. - - ```console - $ echo "test" | docker run -i -a stdin ubuntu cat - - ``` - - This pipes data into a container and prints the container's ID by attaching - only to the container's `STDIN`. - - ```console - $ docker run -a stderr ubuntu echo test - ``` - - This isn't going to print anything unless there's an error because we've - only attached to the `STDERR` of the container. The container's logs - still store what's been written to `STDERR` and `STDOUT`. - - ```console - $ cat somefile | docker run -i -a stdin mybuilder dobuild - ``` - - This is a way of using `--attach` to pipe a build file into a container. - The container's ID will be printed after the build is done and the build - logs could be retrieved using `docker logs`. This is - useful if you need to pipe a file or something else into a container and - retrieve the container's ID once the container has finished running. - - See also [the `docker cp` command](cp.md). + The `--volumes-from` flag mounts all the defined volumes from the referenced + containers. Containers can be specified by repetitions of the `--volumes-from` + argument. The container ID may be optionally suffixed with `:ro` or `:rw` to + mount the volumes in read-only or read-write mode, respectively. By default, + the volumes are mounted in the same mode (read write or read only) as + the reference container. + + Labeling systems like SELinux require that proper labels are placed on volume + content mounted into a container. Without a label, the security system might + prevent the processes running inside the container from using the content. By + default, Docker does not change the labels set by the OS. + + To change the label in the container context, you can add either of two suffixes + `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file + objects on the shared volumes. The `z` option tells Docker that two containers + share the volume content. As a result, Docker labels the content with a shared + content label. Shared volume labels allow all containers to read/write content. + The `Z` option tells Docker to label the content with a private unshared label. + Only the current container can use a private volume. + + ### Attach to STDIN/STDOUT/STDERR (-a, --attach) {#attach} + + The `--attach` (or `-a`) flag tells `docker run` to bind to the container's + `STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output + and input as needed. + + ```console + $ echo "test" | docker run -i -a stdin ubuntu cat - + ``` + + This pipes data into a container and prints the container's ID by attaching + only to the container's `STDIN`. + + ```console + $ docker run -a stderr ubuntu echo test + ``` + + This isn't going to print anything unless there's an error because we've + only attached to the `STDERR` of the container. The container's logs + still store what's been written to `STDERR` and `STDOUT`. + + ```console + $ cat somefile | docker run -i -a stdin mybuilder dobuild + ``` - ### Add host device to container (--device) - - ```console - $ docker run -it --rm \ - --device=/dev/sdc:/dev/xvdc \ - --device=/dev/sdd \ - --device=/dev/zero:/dev/foobar \ - ubuntu ls -l /dev/{xvdc,sdd,foobar} - - brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc - brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd - crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/foobar - ``` - - It is often necessary to directly expose devices to a container. The `--device` - option enables that. For example, a specific block storage device or loop - device or audio device can be added to an otherwise unprivileged container - (without the `--privileged` flag) and have the application directly access it. - - By default, the container will be able to `read`, `write` and `mknod` these devices. - This can be overridden using a third `:rwm` set of options to each `--device` - flag. If the container is running in privileged mode, then the permissions specified - will be ignored. + This is a way of using `--attach` to pipe a build file into a container. + The container's ID will be printed after the build is done and the build + logs could be retrieved using `docker logs`. This is + useful if you need to pipe a file or something else into a container and + retrieve the container's ID once the container has finished running. + + See also [the `docker cp` command](cp.md). - ```console - $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc - - Command (m for help): q - $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc - You will not be able to write the partition table. - - Command (m for help): q - - $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk /dev/xvdc - - Command (m for help): q + ### Add host device to container (--device) {#device} - $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc - fdisk: unable to open /dev/xvdc: Operation not permitted - ``` + ```console + $ docker run -it --rm \ + --device=/dev/sdc:/dev/xvdc \ + --device=/dev/sdd \ + --device=/dev/zero:/dev/foobar \ + ubuntu ls -l /dev/{xvdc,sdd,foobar} + + brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc + brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd + crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/foobar + ``` + + It is often necessary to directly expose devices to a container. The `--device` + option enables that. For example, a specific block storage device or loop + device or audio device can be added to an otherwise unprivileged container + (without the `--privileged` flag) and have the application directly access it. - > **Note** - > - > The `--device` option cannot be safely used with ephemeral devices. Block devices - > that may be removed should not be added to untrusted containers with `--device`. + By default, the container will be able to `read`, `write` and `mknod` these devices. + This can be overridden using a third `:rwm` set of options to each `--device` + flag. If the container is running in privileged mode, then the permissions specified + will be ignored. - For Windows, the format of the string passed to the `--device` option is in - the form of `--device=/`. Beginning with Windows Server 2019 - and Windows 10 October 2018 Update, Windows only supports an IdType of - `class` and the Id as a [device interface class - GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). - Refer to the table defined in the [Windows container - docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers) - for a list of container-supported device interface class GUIDs. + ```console + $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc + + Command (m for help): q + $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc + You will not be able to write the partition table. + + Command (m for help): q + + $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk /dev/xvdc + + Command (m for help): q - If this option is specified for a process-isolated Windows container, _all_ - devices that implement the requested device interface class GUID are made - available in the container. For example, the command below makes all COM - ports on the host visible in the container. - - ```powershell - PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019 - ``` + $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc + fdisk: unable to open /dev/xvdc: Operation not permitted + ``` - > **Note** - > - > The `--device` option is only supported on process-isolated Windows containers. - > This option fails if the container isolation is `hyperv` or when running Linux - > Containers on Windows (LCOW). - - ### Using dynamically created devices (--device-cgroup-rule) - - Devices available to a container are assigned at creation time. The - assigned devices will both be added to the cgroup.allow file and - created into the container once it is run. This poses a problem when - a new device needs to be added to running container. - - One of the solutions is to add a more permissive rule to a container - allowing it access to a wider range of devices. For example, supposing - our container needs access to a character device with major `42` and - any number of minor number (added as new devices appear), the - following rule would be added: - - ```console - $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image - ``` - - Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 ` - the required device when it is added. - - > **Note**: initially present devices still need to be explicitly added to the - > `docker run` / `docker create` command. - - ### Access an NVIDIA GPU - - The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to - install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). - Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/) - for more information. - - To use `--gpus`, specify which GPUs (or all) to use. If no value is provided, all - available GPUs are used. The example below exposes all available GPUs. - - ```console - $ docker run -it --rm --gpus all ubuntu nvidia-smi - ``` - - Use the `device` option to specify GPUs. The example below exposes a specific - GPU. - - ```console - $ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi - ``` - - The example below exposes the first and third GPUs. - - ```console - $ docker run -it --rm --gpus '"device=0,2"' nvidia-smi - ``` - - ### Restart policies (--restart) + > **Note** + > + > The `--device` option cannot be safely used with ephemeral devices. Block devices + > that may be removed should not be added to untrusted containers with `--device`. - Use Docker's `--restart` to specify a container's *restart policy*. A restart - policy controls whether the Docker daemon restarts a container after exit. - Docker supports the following restart policies: + For Windows, the format of the string passed to the `--device` option is in + the form of `--device=/`. Beginning with Windows Server 2019 + and Windows 10 October 2018 Update, Windows only supports an IdType of + `class` and the Id as a [device interface class + GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). + Refer to the table defined in the [Windows container + docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers) + for a list of container-supported device interface class GUIDs. - | Policy | Result | - |:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | `no` | Do not automatically restart the container when it exits. This is the default. | - | `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | - | `unless-stopped` | Restart the container unless it is explicitly stopped or Docker itself is stopped or restarted. | - | `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. | + If this option is specified for a process-isolated Windows container, _all_ + devices that implement the requested device interface class GUID are made + available in the container. For example, the command below makes all COM + ports on the host visible in the container. + + ```powershell + PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019 + ``` - ```console - $ docker run --restart=always redis - ``` + > **Note** + > + > The `--device` option is only supported on process-isolated Windows containers, + > and produces an error if the container isolation is `hyperv`. - This will run the `redis` container with a restart policy of **always** - so that if the container exits, Docker will restart it. + ### Using dynamically created devices (--device-cgroup-rule) {#device-cgroup-rule} + + Devices available to a container are assigned at creation time. The + assigned devices will both be added to the cgroup.allow file and + created into the container once it is run. This poses a problem when + a new device needs to be added to running container. + + One of the solutions is to add a more permissive rule to a container + allowing it access to a wider range of devices. For example, supposing + our container needs access to a character device with major `42` and + any number of minor number (added as new devices appear), the + following rule would be added: + + ```console + $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image + ``` + + Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 ` + the required device when it is added. + + > **Note**: initially present devices still need to be explicitly added to the + > `docker run` / `docker create` command. + + ### Access an NVIDIA GPU {#gpus} + + The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to + install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). + Visit [Specify a container's resources](/config/containers/resource_constraints/) + for more information. + + To use `--gpus`, specify which GPUs (or all) to use. If no value is provided, all + available GPUs are used. The example below exposes all available GPUs. + + ```console + $ docker run -it --rm --gpus all ubuntu nvidia-smi + ``` + + Use the `device` option to specify GPUs. The example below exposes a specific + GPU. + + ```console + $ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi + ``` + + The example below exposes the first and third GPUs. + + ```console + $ docker run -it --rm --gpus '"device=0,2"' nvidia-smi + ``` - More detailed information on restart policies can be found in the - [Restart Policies (--restart)](../run.md#restart-policies---restart) - section of the Docker run reference page. + ### Restart policies (--restart) {#restart} - ### Add entries to container hosts file (--add-host) + Use Docker's `--restart` to specify a container's *restart policy*. A restart + policy controls whether the Docker daemon restarts a container after exit. + Docker supports the following restart policies: - You can add other hosts into a container's `/etc/hosts` file by using one or - more `--add-host` flags. This example adds a static address for a host named - `docker`: + | Policy | Result | + |:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `no` | Do not automatically restart the container when it exits. This is the default. | + | `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | + | `unless-stopped` | Restart the container unless it is explicitly stopped or Docker itself is stopped or restarted. | + | `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. | - ```console - $ docker run --add-host=docker:93.184.216.34 --rm -it alpine + ```console + $ docker run --restart=always redis + ``` + + This will run the `redis` container with a restart policy of **always** + so that if the container exits, Docker will restart it. - / # ping docker - PING docker (93.184.216.34): 56 data bytes - 64 bytes from 93.184.216.34: seq=0 ttl=37 time=93.052 ms - 64 bytes from 93.184.216.34: seq=1 ttl=37 time=92.467 ms - 64 bytes from 93.184.216.34: seq=2 ttl=37 time=92.252 ms - ^C - --- docker ping statistics --- - 4 packets transmitted, 4 packets received, 0% packet loss - round-trip min/avg/max = 92.209/92.495/93.052 ms - ``` + More detailed information on restart policies can be found in the + [Restart Policies (--restart)](../run.md#restart-policies---restart) + section of the Docker run reference page. - Sometimes you need to connect to the Docker host from within your - container. To enable this, pass the Docker host's IP address to - the container using the `--add-host` flag. To find the host's address, - use the `ip addr show` command. + ### Add entries to container hosts file (--add-host) {#add-host} - The flags you pass to `ip addr show` depend on whether you are - using IPv4 or IPv6 networking in your containers. Use the following - flags for IPv4 address retrieval for a network device named `eth0`: + You can add other hosts into a container's `/etc/hosts` file by using one or + more `--add-host` flags. This example adds a static address for a host named + `docker`: - ```console - $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print $2}' | cut -d / -f 1 | sed -n 1p` - $ docker run --add-host=docker:${HOSTIP} --rm -it debian - ``` + ```console + $ docker run --add-host=docker:93.184.216.34 --rm -it alpine - For IPv6 use the `-6` flag instead of the `-4` flag. For other network - devices, replace `eth0` with the correct device name (for example `docker0` - for the bridge device). + / # ping docker + PING docker (93.184.216.34): 56 data bytes + 64 bytes from 93.184.216.34: seq=0 ttl=37 time=93.052 ms + 64 bytes from 93.184.216.34: seq=1 ttl=37 time=92.467 ms + 64 bytes from 93.184.216.34: seq=2 ttl=37 time=92.252 ms + ^C + --- docker ping statistics --- + 4 packets transmitted, 4 packets received, 0% packet loss + round-trip min/avg/max = 92.209/92.495/93.052 ms + ``` - ### Set ulimits in container (--ulimit) + Sometimes you need to connect to the Docker host from within your + container. To enable this, pass the Docker host's IP address to + the container using the `--add-host` flag. To find the host's address, + use the `ip addr show` command. - Since setting `ulimit` settings in a container requires extra privileges not - available in the default container, you can set these using the `--ulimit` flag. - `--ulimit` is specified with a soft and hard limit as such: - `=[:]`, for example: + The flags you pass to `ip addr show` depend on whether you are + using IPv4 or IPv6 networking in your containers. Use the following + flags for IPv4 address retrieval for a network device named `eth0`: - ```console - $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" - 1024 - ``` + ```console + $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print $2}' | cut -d / -f 1 | sed -n 1p` + $ docker run --add-host=docker:${HOSTIP} --rm -it debian + ``` - > **Note** - > - > If you do not provide a `hard limit`, the `soft limit` is used - > for both values. If no `ulimits` are set, they are inherited from - > the default `ulimits` set on the daemon. The `as` option is disabled now. - > In other words, the following script is not supported: - > - > ```console - > $ docker run -it --ulimit as=1024 fedora /bin/bash - > ``` + For IPv6 use the `-6` flag instead of the `-4` flag. For other network + devices, replace `eth0` with the correct device name (for example `docker0` + for the bridge device). - The values are sent to the appropriate `syscall` as they are set. - Docker doesn't perform any byte conversion. Take this into account when setting the values. + ### Set ulimits in container (--ulimit) {#ulimit} - #### For `nproc` usage + Since setting `ulimit` settings in a container requires extra privileges not + available in the default container, you can set these using the `--ulimit` flag. + `--ulimit` is specified with a soft and hard limit as such: + `=[:]`, for example: - Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the - maximum number of processes available to a user, not to a container. For example, start four - containers with `daemon` user: + ```console + $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" + 1024 + ``` - ```console - $ docker run -d -u daemon --ulimit nproc=3 busybox top + > **Note** + > + > If you do not provide a `hard limit`, the `soft limit` is used + > for both values. If no `ulimits` are set, they are inherited from + > the default `ulimits` set on the daemon. The `as` option is disabled now. + > In other words, the following script is not supported: + > + > ```console + > $ docker run -it --ulimit as=1024 fedora /bin/bash + > ``` - $ docker run -d -u daemon --ulimit nproc=3 busybox top + The values are sent to the appropriate `syscall` as they are set. + Docker doesn't perform any byte conversion. Take this into account when setting the values. - $ docker run -d -u daemon --ulimit nproc=3 busybox top + #### For `nproc` usage - $ docker run -d -u daemon --ulimit nproc=3 busybox top - ``` + Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the + maximum number of processes available to a user, not to a container. For example, start four + containers with `daemon` user: - The 4th container fails and reports "[8] System error: resource temporarily unavailable" error. - This fails because the caller set `nproc=3` resulting in the first three containers using up - the three processes quota set for the `daemon` user. + ```console + $ docker run -d -u daemon --ulimit nproc=3 busybox top - ### Stop container with signal (--stop-signal) + $ docker run -d -u daemon --ulimit nproc=3 busybox top - The `--stop-signal` flag sets the system call signal that will be sent to the - container to exit. This signal can be a signal name in the format `SIG`, - for instance `SIGKILL`, or an unsigned number that matches a position in the - kernel's syscall table, for instance `9`. + $ docker run -d -u daemon --ulimit nproc=3 busybox top - The default is `SIGTERM` if not specified. + $ docker run -d -u daemon --ulimit nproc=3 busybox top + ``` - ### Optional security options (--security-opt) + The 4th container fails and reports "[8] System error: resource temporarily unavailable" error. + This fails because the caller set `nproc=3` resulting in the first three containers using up + the three processes quota set for the `daemon` user. - On Windows, this flag can be used to specify the `credentialspec` option. - The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. + ### Stop container with signal (--stop-signal) {#stop-signal} - ### Stop container with timeout (--stop-timeout) + The `--stop-signal` flag sets the system call signal that will be sent to the + container to exit. This signal can be a signal name in the format `SIG`, + for instance `SIGKILL`, or an unsigned number that matches a position in the + kernel's syscall table, for instance `9`. - The `--stop-timeout` flag sets the number of seconds to wait for the container - to stop after sending the pre-defined (see `--stop-signal`) system call signal. - If the container does not exit after the timeout elapses, it is forcibly killed - with a `SIGKILL` signal. + The default is defined by [`STOPSIGNAL`](/engine/reference/builder/#stopsignal) + in the image, or `SIGTERM` if the image has no `STOPSIGNAL` defined. - If `--stop-timeout` is set to `-1`, no timeout is applied, and the daemon will - wait indefinitely for the container to exit. + ### Optional security options (--security-opt) {#security-opt} - The default is determined by the daemon, and is 10 seconds for Linux containers, - and 30 seconds for Windows containers. + On Windows, this flag can be used to specify the `credentialspec` option. + The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. - ### Specify isolation technology for container (--isolation) + ### Stop container with timeout (--stop-timeout) {#stop-timeout} - This option is useful in situations where you are running Docker containers on - Windows. The `--isolation=` option sets a container's isolation technology. - On Linux, the only supported is the `default` option which uses Linux namespaces. - These two commands are equivalent on Linux: + The `--stop-timeout` flag sets the number of seconds to wait for the container + to stop after sending the pre-defined (see `--stop-signal`) system call signal. + If the container does not exit after the timeout elapses, it is forcibly killed + with a `SIGKILL` signal. - ```console - $ docker run -d busybox top - $ docker run -d --isolation default busybox top - ``` + If `--stop-timeout` is set to `-1`, no timeout is applied, and the daemon will + wait indefinitely for the container to exit. - On Windows, `--isolation` can take one of these values: + The default is determined by the daemon, and is 10 seconds for Linux containers, + and 30 seconds for Windows containers. - | Value | Description | - |:----------|:-------------------------------------------------------------------------------------------| - | `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | - | `process` | Shared-kernel namespace isolation. | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | + ### Specify isolation technology for container (--isolation) {#isolation} - The default isolation on Windows server operating systems is `process`, and `hyperv` - on Windows client operating systems, such as Windows 10. Process isolation has better - performance, but requires that the image and host use the same kernel version. + This option is useful in situations where you are running Docker containers on + Windows. The `--isolation=` option sets a container's isolation technology. + On Linux, the only supported is the `default` option which uses Linux namespaces. + These two commands are equivalent on Linux: - On Windows server, assuming the default configuration, these commands are equivalent - and result in `process` isolation: + ```console + $ docker run -d busybox top + $ docker run -d --isolation default busybox top + ``` - ```powershell - PS C:\> docker run -d microsoft/nanoserver powershell echo process - PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo process - PS C:\> docker run -d --isolation process microsoft/nanoserver powershell echo process - ``` + On Windows, `--isolation` can take one of these values: - If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, or - are running against a Windows client-based daemon, these commands are equivalent and - result in `hyperv` isolation: + | Value | Description | + |:----------|:-------------------------------------------------------------------------------------------| + | `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | + | `process` | Shared-kernel namespace isolation. | + | `hyperv` | Hyper-V hypervisor partition-based isolation. | - ```powershell - PS C:\> docker run -d microsoft/nanoserver powershell echo hyperv - PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo hyperv - PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hyperv - ``` + The default isolation on Windows server operating systems is `process`, and `hyperv` + on Windows client operating systems, such as Windows 10. Process isolation has better + performance, but requires that the image and host use the same kernel version. - ### Specify hard limits on memory available to containers (-m, --memory) + On Windows server, assuming the default configuration, these commands are equivalent + and result in `process` isolation: - These parameters always set an upper limit on the memory available to the container. On Linux, this - is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`. + ```powershell + PS C:\> docker run -d microsoft/nanoserver powershell echo process + PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo process + PS C:\> docker run -d --isolation process microsoft/nanoserver powershell echo process + ``` - On Windows, this will affect containers differently depending on what type of isolation is used. + If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, or + are running against a Windows client-based daemon, these commands are equivalent and + result in `hyperv` isolation: - - With `process` isolation, Windows will report the full memory of the host system, not the limit to applications running inside the container + ```powershell + PS C:\> docker run -d microsoft/nanoserver powershell echo hyperv + PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo hyperv + PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hyperv + ``` - ```powershell - PS C:\> docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory* + ### Specify hard limits on memory available to containers (-m, --memory) {#memory} - CsTotalPhysicalMemory : 17064509440 - CsPhyicallyInstalledMemory : 16777216 - OsTotalVisibleMemorySize : 16664560 - OsFreePhysicalMemory : 14646720 - OsTotalVirtualMemorySize : 19154928 - OsFreeVirtualMemory : 17197440 - OsInUseVirtualMemory : 1957488 - OsMaxProcessMemorySize : 137438953344 - ``` + These parameters always set an upper limit on the memory available to the container. On Linux, this + is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`. - - With `hyperv` isolation, Windows will create a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory." + On Windows, this will affect containers differently depending on what type of isolation is used. - ```powershell - PS C:\> docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory* + - With `process` isolation, Windows will report the full memory of the host system, not the limit to applications running inside the container - CsTotalPhysicalMemory : 2683355136 - CsPhyicallyInstalledMemory : - OsTotalVisibleMemorySize : 2620464 - OsFreePhysicalMemory : 2306552 - OsTotalVirtualMemorySize : 2620464 - OsFreeVirtualMemory : 2356692 - OsInUseVirtualMemory : 263772 - OsMaxProcessMemorySize : 137438953344 - ``` + ```powershell + PS C:\> docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory* + CsTotalPhysicalMemory : 17064509440 + CsPhyicallyInstalledMemory : 16777216 + OsTotalVisibleMemorySize : 16664560 + OsFreePhysicalMemory : 14646720 + OsTotalVirtualMemorySize : 19154928 + OsFreeVirtualMemory : 17197440 + OsInUseVirtualMemory : 1957488 + OsMaxProcessMemorySize : 137438953344 + ``` - ### Configure namespaced kernel parameters (sysctls) at runtime (--sysctl) + - With `hyperv` isolation, Windows will create a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory." - The `--sysctl` sets namespaced kernel parameters (sysctls) in the - container. For example, to turn on IP forwarding in the containers - network namespace, run this command: + ```powershell + PS C:\> docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory* - ```console - $ docker run --sysctl net.ipv4.ip_forward=1 someimage - ``` + CsTotalPhysicalMemory : 2683355136 + CsPhyicallyInstalledMemory : + OsTotalVisibleMemorySize : 2620464 + OsFreePhysicalMemory : 2306552 + OsTotalVirtualMemorySize : 2620464 + OsFreeVirtualMemory : 2356692 + OsInUseVirtualMemory : 263772 + OsMaxProcessMemorySize : 137438953344 + ``` - > **Note** - > - > Not all sysctls are namespaced. Docker does not support changing sysctls - > inside of a container that also modify the host system. As the kernel - > evolves we expect to see more sysctls become namespaced. - #### Currently supported sysctls + ### Configure namespaced kernel parameters (sysctls) at runtime (--sysctl) {#sysctl} - IPC Namespace: + The `--sysctl` sets namespaced kernel parameters (sysctls) in the + container. For example, to turn on IP forwarding in the containers + network namespace, run this command: - - `kernel.msgmax`, `kernel.msgmnb`, `kernel.msgmni`, `kernel.sem`, - `kernel.shmall`, `kernel.shmmax`, `kernel.shmmni`, `kernel.shm_rmid_forced`. - - Sysctls beginning with `fs.mqueue.*` - - If you use the `--ipc=host` option these sysctls are not allowed. + ```console + $ docker run --sysctl net.ipv4.ip_forward=1 someimage + ``` - Network Namespace: + > **Note** + > + > Not all sysctls are namespaced. Docker does not support changing sysctls + > inside of a container that also modify the host system. As the kernel + > evolves we expect to see more sysctls become namespaced. - - Sysctls beginning with `net.*` - - If you use the `--network=host` option using these sysctls are not allowed. + #### Currently supported sysctls + + IPC Namespace: + + - `kernel.msgmax`, `kernel.msgmnb`, `kernel.msgmni`, `kernel.sem`, + `kernel.shmall`, `kernel.shmmax`, `kernel.shmmni`, `kernel.shm_rmid_forced`. + - Sysctls beginning with `fs.mqueue.*` + - If you use the `--ipc=host` option these sysctls are not allowed. + + Network Namespace: + + - Sysctls beginning with `net.*` + - If you use the `--network=host` option using these sysctls are not allowed. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_save.yaml b/_data/engine-cli/docker_save.yaml index ffc176385f..9de39c4a02 100644 --- a/_data/engine-cli/docker_save.yaml +++ b/_data/engine-cli/docker_save.yaml @@ -1,58 +1,71 @@ command: docker save +aliases: docker image save, docker save short: Save one or more images to a tar archive (streamed to STDOUT by default) long: |- - Produces a tarred repository to the standard output stream. - Contains all parent layers, and all tags + versions, or specified `repo:tag`, for - each argument provided. + Produces a tarred repository to the standard output stream. + Contains all parent layers, and all tags + versions, or specified `repo:tag`, for + each argument provided. usage: docker save [OPTIONS] IMAGE [IMAGE...] pname: docker plink: docker.yaml options: -- option: output - shorthand: o - value_type: string - description: Write to a file, instead of STDOUT - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: output + shorthand: o + value_type: string + description: Write to a file, instead of STDOUT + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Create a backup that can then be used with `docker load`. + ### Create a backup that can then be used with `docker load`. - ```console - $ docker save busybox > busybox.tar + ```console + $ docker save busybox > busybox.tar - $ ls -sh busybox.tar + $ ls -sh busybox.tar - 2.7M busybox.tar + 2.7M busybox.tar - $ docker save --output busybox.tar busybox + $ docker save --output busybox.tar busybox - $ ls -sh busybox.tar + $ ls -sh busybox.tar - 2.7M busybox.tar + 2.7M busybox.tar - $ docker save -o fedora-all.tar fedora + $ docker save -o fedora-all.tar fedora - $ docker save -o fedora-latest.tar fedora:latest - ``` + $ docker save -o fedora-latest.tar fedora:latest + ``` - ### Save an image to a tar.gz file using gzip + ### Save an image to a tar.gz file using gzip - You can use gzip to save the image file and make the backup smaller. + You can use gzip to save the image file and make the backup smaller. - ```console - $ docker save myimage:latest | gzip > myimage_latest.tar.gz - ``` + ```console + $ docker save myimage:latest | gzip > myimage_latest.tar.gz + ``` - ### Cherry-pick particular tags + ### Cherry-pick particular tags - You can even cherry-pick particular tags of an image repository. + You can even cherry-pick particular tags of an image repository. - ```console - $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy - ``` + ```console + $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_search.yaml b/_data/engine-cli/docker_search.yaml index 31dd1730a1..e76914a67b 100644 --- a/_data/engine-cli/docker_search.yaml +++ b/_data/engine-cli/docker_search.yaml @@ -1,200 +1,219 @@ command: docker search -short: Search the Docker Hub for images +short: Search Docker Hub for images long: Search [Docker Hub](https://hub.docker.com) for images usage: docker search [OPTIONS] TERM pname: docker plink: docker.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print search using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: limit - value_type: int - default_value: "25" - description: Max number of search results - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: Pretty-print search using a Go template + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: limit + value_type: int + default_value: "0" + description: Max number of search results + details_url: '#limit' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + details_url: '#no-trunc' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Search images by name + ### Search images by name - This example displays images with a name containing 'busybox': + This example displays images with a name containing 'busybox': - ```console - $ docker search busybox + ```console + $ docker search busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - busybox Busybox base image. 316 [OK] - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] - odise/busybox-python 2 [OK] - azukiapp/busybox This image is meant to be used as the base... 2 [OK] - ofayau/busybox-jvm Prepare busybox to install a 32 bits JVM. 1 [OK] - shingonoide/archlinux-busybox Arch Linux, a lightweight and flexible Lin... 1 [OK] - odise/busybox-curl 1 [OK] - ofayau/busybox-libc32 Busybox with 32 bits (and 64 bits) libs 1 [OK] - peelsky/zulu-openjdk-busybox 1 [OK] - skomma/busybox-data Docker image suitable for data volume cont... 1 [OK] - elektritter/busybox-teamspeak Lightweight teamspeak3 container based on... 1 [OK] - socketplane/busybox 1 [OK] - oveits/docker-nginx-busybox This is a tiny NginX docker image based on... 0 [OK] - ggtools/busybox-ubuntu Busybox ubuntu version with extra goodies 0 [OK] - nikfoundas/busybox-confd Minimal busybox based distribution of confd 0 [OK] - openshift/busybox-http-app 0 [OK] - jllopis/busybox 0 [OK] - swyckoff/busybox 0 [OK] - powellquiring/busybox 0 [OK] - williamyeh/busybox-sh Docker image for BusyBox's sh 0 [OK] - simplexsys/busybox-cli-powered Docker busybox images, with a few often us... 0 [OK] - fhisamoto/busybox-java Busybox java 0 [OK] - scottabernethy/busybox 0 [OK] - marclop/busybox-solr - ``` + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + busybox Busybox base image. 316 [OK] + progrium/busybox 50 [OK] + radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] + odise/busybox-python 2 [OK] + azukiapp/busybox This image is meant to be used as the base... 2 [OK] + ofayau/busybox-jvm Prepare busybox to install a 32 bits JVM. 1 [OK] + shingonoide/archlinux-busybox Arch Linux, a lightweight and flexible Lin... 1 [OK] + odise/busybox-curl 1 [OK] + ofayau/busybox-libc32 Busybox with 32 bits (and 64 bits) libs 1 [OK] + peelsky/zulu-openjdk-busybox 1 [OK] + skomma/busybox-data Docker image suitable for data volume cont... 1 [OK] + elektritter/busybox-teamspeak Lightweight teamspeak3 container based on... 1 [OK] + socketplane/busybox 1 [OK] + oveits/docker-nginx-busybox This is a tiny NginX docker image based on... 0 [OK] + ggtools/busybox-ubuntu Busybox ubuntu version with extra goodies 0 [OK] + nikfoundas/busybox-confd Minimal busybox based distribution of confd 0 [OK] + openshift/busybox-http-app 0 [OK] + jllopis/busybox 0 [OK] + swyckoff/busybox 0 [OK] + powellquiring/busybox 0 [OK] + williamyeh/busybox-sh Docker image for BusyBox's sh 0 [OK] + simplexsys/busybox-cli-powered Docker busybox images, with a few often us... 0 [OK] + fhisamoto/busybox-java Busybox java 0 [OK] + scottabernethy/busybox 0 [OK] + marclop/busybox-solr + ``` - ### Display non-truncated description (--no-trunc) + ### Display non-truncated description (--no-trunc) {#no-trunc} - This example displays images with a name containing 'busybox', - at least 3 stars and the description isn't truncated in the output: + This example displays images with a name containing 'busybox', + at least 3 stars and the description isn't truncated in the output: - ```console - $ docker search --filter=stars=3 --no-trunc busybox + ```console + $ docker search --filter=stars=3 --no-trunc busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - busybox Busybox base image. 325 [OK] - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors. 8 [OK] - ``` + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + busybox Busybox base image. 325 [OK] + progrium/busybox 50 [OK] + radial/busyboxplus Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors. 8 [OK] + ``` - ### Limit search results (--limit) + ### Limit search results (--limit) {#limit} - The flag `--limit` is the maximum number of results returned by a search. This value could - be in the range between 1 and 100. The default value of `--limit` is 25. + The flag `--limit` is the maximum number of results returned by a search. If no + value is set, the default is set by the daemon. - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more - than one filter, then pass multiple flags (e.g. `--filter is-automated=true --filter stars=3`) + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more + than one filter, then pass multiple flags (e.g. `--filter is-automated=true --filter stars=3`) - The currently supported filters are: + The currently supported filters are: - - stars (int - number of stars the image has) - - is-automated (boolean - true or false) - is the image automated or not - - is-official (boolean - true or false) - is the image official or not + - stars (int - number of stars the image has) + - is-automated (boolean - true or false) - is the image automated or not + - is-official (boolean - true or false) - is the image official or not - #### stars + #### stars - This example displays images with a name containing 'busybox' and at - least 3 stars: + This example displays images with a name containing 'busybox' and at + least 3 stars: - ```console - $ docker search --filter stars=3 busybox + ```console + $ docker search --filter stars=3 busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - busybox Busybox base image. 325 [OK] - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] - ``` + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + busybox Busybox base image. 325 [OK] + progrium/busybox 50 [OK] + radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] + ``` - #### is-automated + #### is-automated - This example displays images with a name containing 'busybox' - and are automated builds: + This example displays images with a name containing 'busybox' + and are automated builds: - ```console - $ docker search --filter is-automated=true busybox + ```console + $ docker search --filter is-automated=true busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] - ``` + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + progrium/busybox 50 [OK] + radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] + ``` - #### is-official + #### is-official - This example displays images with a name containing 'busybox', at least - 3 stars and are official builds: + This example displays images with a name containing 'busybox', at least + 3 stars and are official builds: - ```console - $ docker search --filter is-official=true --filter stars=3 busybox + ```console + $ docker search --filter is-official=true --filter stars=3 busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - busybox Busybox base image. 325 [OK] - ``` + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + busybox Busybox base image. 325 [OK] + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) pretty-prints search output - using a Go template. + The formatting option (`--format`) pretty-prints search output + using a Go template. - Valid placeholders for the Go template are: + Valid placeholders for the Go template are: - | Placeholder | Description | - |----------------|-----------------------------------| - | `.Name` | Image Name | - | `.Description` | Image description | - | `.StarCount` | Number of stars for the image | - | `.IsOfficial` | "OK" if image is official | - | `.IsAutomated` | "OK" if image build was automated | + | Placeholder | Description | + |----------------|-----------------------------------| + | `.Name` | Image Name | + | `.Description` | Image description | + | `.StarCount` | Number of stars for the image | + | `.IsOfficial` | "OK" if image is official | + | `.IsAutomated` | "OK" if image build was automated | - When you use the `--format` option, the `search` command will - output the data exactly as the template declares. If you use the - `table` directive, column headers are included as well. + When you use the `--format` option, the `search` command will + output the data exactly as the template declares. If you use the + `table` directive, column headers are included as well. - The following example uses a template without headers and outputs the - `Name` and `StarCount` entries separated by a colon (`:`) for all images: + The following example uses a template without headers and outputs the + `Name` and `StarCount` entries separated by a colon (`:`) for all images: - ```console - $ docker search --format "{{.Name}}: {{.StarCount}}" nginx + ```console + $ docker search --format "{{.Name}}: {{.StarCount}}" nginx - nginx: 5441 - jwilder/nginx-proxy: 953 - richarvey/nginx-php-fpm: 353 - million12/nginx-php: 75 - webdevops/php-nginx: 70 - h3nrik/nginx-ldap: 35 - bitnami/nginx: 23 - evild/alpine-nginx: 14 - million12/nginx: 9 - maxexcloo/nginx: 7 - ``` + nginx: 5441 + jwilder/nginx-proxy: 953 + richarvey/nginx-php-fpm: 353 + million12/nginx-php: 75 + webdevops/php-nginx: 70 + h3nrik/nginx-ldap: 35 + bitnami/nginx: 23 + evild/alpine-nginx: 14 + million12/nginx: 9 + maxexcloo/nginx: 7 + ``` - This example outputs a table format: + This example outputs a table format: - ```console - $ docker search --format "table {{.Name}}\t{{.IsAutomated}}\t{{.IsOfficial}}" nginx + ```console + $ docker search --format "table {{.Name}}\t{{.IsAutomated}}\t{{.IsOfficial}}" nginx - NAME AUTOMATED OFFICIAL - nginx [OK] - jwilder/nginx-proxy [OK] - richarvey/nginx-php-fpm [OK] - jrcs/letsencrypt-nginx-proxy-companion [OK] - million12/nginx-php [OK] - webdevops/php-nginx [OK] - ``` + NAME AUTOMATED OFFICIAL + nginx [OK] + jwilder/nginx-proxy [OK] + richarvey/nginx-php-fpm [OK] + jrcs/letsencrypt-nginx-proxy-companion [OK] + million12/nginx-php [OK] + webdevops/php-nginx [OK] + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_secret.yaml b/_data/engine-cli/docker_secret.yaml index 9ec8a70621..d51c026473 100644 --- a/_data/engine-cli/docker_secret.yaml +++ b/_data/engine-cli/docker_secret.yaml @@ -1,19 +1,30 @@ command: docker secret -short: Manage Docker secrets +short: Manage Swarm secrets long: Manage secrets. usage: docker secret pname: docker plink: docker.yaml cname: -- docker secret create -- docker secret inspect -- docker secret ls -- docker secret rm + - docker secret create + - docker secret inspect + - docker secret ls + - docker secret rm clink: -- docker_secret_create.yaml -- docker_secret_inspect.yaml -- docker_secret_ls.yaml -- docker_secret_rm.yaml + - docker_secret_create.yaml + - docker_secret_inspect.yaml + - docker_secret_ls.yaml + - docker_secret_rm.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_secret_create.yaml b/_data/engine-cli/docker_secret_create.yaml index f58aa284c5..f5ccfd9ea2 100644 --- a/_data/engine-cli/docker_secret_create.yaml +++ b/_data/engine-cli/docker_secret_create.yaml @@ -1,107 +1,122 @@ command: docker secret create short: Create a secret from a file or STDIN as content long: |- - Creates a secret using standard input or from a file for the secret content. + Creates a secret using standard input or from a file for the secret content. - For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/). + For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/). - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker secret create [OPTIONS] SECRET [file|-] pname: docker secret plink: docker_secret.yaml options: -- option: driver - shorthand: d - value_type: string - description: Secret driver - deprecated: false - min_api_version: "1.31" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - shorthand: l - value_type: list - description: Secret labels - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: template-driver - value_type: string - description: Template driver - deprecated: false - min_api_version: "1.37" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: driver + shorthand: d + value_type: string + description: Secret driver + deprecated: false + hidden: false + min_api_version: "1.31" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + shorthand: l + value_type: list + description: Secret labels + details_url: '#label' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: template-driver + value_type: string + description: Template driver + deprecated: false + hidden: false + min_api_version: "1.37" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Create a secret + ### Create a secret - ```console - $ printf "my super secret password" | docker secret create my_secret - + ```console + $ printf "my super secret password" | docker secret create my_secret - - onakdyv307se2tl7nl20anokv + onakdyv307se2tl7nl20anokv - $ docker secret ls + $ docker secret ls - ID NAME CREATED UPDATED - onakdyv307se2tl7nl20anokv my_secret 6 seconds ago 6 seconds ago - ``` + ID NAME CREATED UPDATED + onakdyv307se2tl7nl20anokv my_secret 6 seconds ago 6 seconds ago + ``` - ### Create a secret with a file + ### Create a secret with a file - ```console - $ docker secret create my_secret ./secret.json + ```console + $ docker secret create my_secret ./secret.json - dg426haahpi5ezmkkj5kyl3sn + dg426haahpi5ezmkkj5kyl3sn - $ docker secret ls + $ docker secret ls - ID NAME CREATED UPDATED - dg426haahpi5ezmkkj5kyl3sn my_secret 7 seconds ago 7 seconds ago - ``` + ID NAME CREATED UPDATED + dg426haahpi5ezmkkj5kyl3sn my_secret 7 seconds ago 7 seconds ago + ``` - ### Create a secret with labels (--label) + ### Create a secret with labels (--label) {#label} - ```console - $ docker secret create \ - --label env=dev \ - --label rev=20170324 \ - my_secret ./secret.json + ```console + $ docker secret create \ + --label env=dev \ + --label rev=20170324 \ + my_secret ./secret.json - eo7jnzguqgtpdah3cm5srfb97 - ``` + eo7jnzguqgtpdah3cm5srfb97 + ``` - ```console - $ docker secret inspect my_secret + ```console + $ docker secret inspect my_secret - [ - { - "ID": "eo7jnzguqgtpdah3cm5srfb97", - "Version": { - "Index": 17 - }, - "CreatedAt": "2017-03-24T08:15:09.735271783Z", - "UpdatedAt": "2017-03-24T08:15:09.735271783Z", - "Spec": { - "Name": "my_secret", - "Labels": { - "env": "dev", - "rev": "20170324" - } - } - } - ] - ``` + [ + { + "ID": "eo7jnzguqgtpdah3cm5srfb97", + "Version": { + "Index": 17 + }, + "CreatedAt": "2017-03-24T08:15:09.735271783Z", + "UpdatedAt": "2017-03-24T08:15:09.735271783Z", + "Spec": { + "Name": "my_secret", + "Labels": { + "env": "dev", + "rev": "20170324" + } + } + } + ] + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_secret_inspect.yaml b/_data/engine-cli/docker_secret_inspect.yaml index b62135b9bf..85e8ca0598 100644 --- a/_data/engine-cli/docker_secret_inspect.yaml +++ b/_data/engine-cli/docker_secret_inspect.yaml @@ -1,95 +1,113 @@ command: docker secret inspect short: Display detailed information on one or more secrets long: |- - Inspects the specified secret. + Inspects the specified secret. - By default, this renders all results in a JSON array. If a format is specified, - the given template will be executed for each result. + By default, this renders all results in a JSON array. If a format is specified, + the given template will be executed for each result. - Go's [text/template](https://golang.org/pkg/text/template/) package - describes all the details of the format. + Go's [text/template](https://golang.org/pkg/text/template/) package + describes all the details of the format. - For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/). + For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/). - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker secret inspect [OPTIONS] SECRET [SECRET...] pname: docker secret plink: docker_secret.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pretty - value_type: bool - default_value: "false" - description: Print the information in a human friendly format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pretty + value_type: bool + default_value: "false" + description: Print the information in a human friendly format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Inspect a secret by name or ID + ### Inspect a secret by name or ID - You can inspect a secret, either by its *name*, or *ID* + You can inspect a secret, either by its *name*, or *ID* - For example, given the following secret: + For example, given the following secret: - ```console - $ docker secret ls + ```console + $ docker secret ls - ID NAME CREATED UPDATED - eo7jnzguqgtpdah3cm5srfb97 my_secret 3 minutes ago 3 minutes ago - ``` + ID NAME CREATED UPDATED + eo7jnzguqgtpdah3cm5srfb97 my_secret 3 minutes ago 3 minutes ago + ``` - ```console - $ docker secret inspect secret.json - ``` + ```console + $ docker secret inspect secret.json + ``` - The output is in JSON format, for example: + The output is in JSON format, for example: - ```json - [ - { - "ID": "eo7jnzguqgtpdah3cm5srfb97", - "Version": { - "Index": 17 - }, - "CreatedAt": "2017-03-24T08:15:09.735271783Z", - "UpdatedAt": "2017-03-24T08:15:09.735271783Z", - "Spec": { - "Name": "my_secret", - "Labels": { - "env": "dev", - "rev": "20170324" + ```json + [ + { + "ID": "eo7jnzguqgtpdah3cm5srfb97", + "Version": { + "Index": 17 + }, + "CreatedAt": "2017-03-24T08:15:09.735271783Z", + "UpdatedAt": "2017-03-24T08:15:09.735271783Z", + "Spec": { + "Name": "my_secret", + "Labels": { + "env": "dev", + "rev": "20170324" + } } } - } - ] - ``` + ] + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - You can use the --format option to obtain specific information about a - secret. The following example command outputs the creation time of the - secret. + You can use the --format option to obtain specific information about a + secret. The following example command outputs the creation time of the + secret. - ```console - $ docker secret inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97 + ```console + $ docker secret inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97 - 2017-03-24 08:15:09.735271783 +0000 UTC - ``` + 2017-03-24 08:15:09.735271783 +0000 UTC + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_secret_ls.yaml b/_data/engine-cli/docker_secret_ls.yaml index fd63d8a023..13b10e2bc6 100644 --- a/_data/engine-cli/docker_secret_ls.yaml +++ b/_data/engine-cli/docker_secret_ls.yaml @@ -1,160 +1,188 @@ command: docker secret ls -aliases: list +aliases: docker secret ls, docker secret list short: List secrets long: |- - Run this command on a manager node to list the secrets in the swarm. + Run this command on a manager node to list the secrets in the swarm. - For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/). + For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/). - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker secret ls [OPTIONS] pname: docker secret plink: docker_secret.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print secrets using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker secret ls + ```console + $ docker secret ls - ID NAME CREATED UPDATED - 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago - 9u9hk4br2ej0wgngkga6rp4hq my_secret 5 weeks ago 5 weeks ago - mem02h8n73mybpgqjf0kfi1n0 test_secret 3 seconds ago 3 seconds ago - ``` + ID NAME CREATED UPDATED + 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago + 9u9hk4br2ej0wgngkga6rp4hq my_secret 5 weeks ago 5 weeks ago + mem02h8n73mybpgqjf0kfi1n0 test_secret 3 seconds ago 3 seconds ago + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more - than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) - The currently supported filters are: + The currently supported filters are: - - [id](#id) (secret's ID) - - [label](#label) (`label=` or `label==`) - - [name](#name) (secret's name) + - [id](#id) (secret's ID) + - [label](#label) (`label=` or `label==`) + - [name](#name) (secret's name) - #### id + #### id - The `id` filter matches all or prefix of a secret's id. + The `id` filter matches all or prefix of a secret's id. - ```console - $ docker secret ls -f "id=6697bflskwj1998km1gnnjr38" + ```console + $ docker secret ls -f "id=6697bflskwj1998km1gnnjr38" - ID NAME CREATED UPDATED - 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago - ``` + ID NAME CREATED UPDATED + 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago + ``` - #### label + #### label - The `label` filter matches secrets based on the presence of a `label` alone or - a `label` and a value. + The `label` filter matches secrets based on the presence of a `label` alone or + a `label` and a value. - The following filter matches all secrets with a `project` label regardless of - its value: + The following filter matches all secrets with a `project` label regardless of + its value: - ```console - $ docker secret ls --filter label=project + ```console + $ docker secret ls --filter label=project - ID NAME CREATED UPDATED - mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago - ``` + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago + ``` - The following filter matches only services with the `project` label with the - `project-a` value. + The following filter matches only services with the `project` label with the + `project-a` value. - ```console - $ docker service ls --filter label=project=test + ```console + $ docker service ls --filter label=project=test - ID NAME CREATED UPDATED - mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago - ``` + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago + ``` - #### name + #### name - The `name` filter matches on all or prefix of a secret's name. + The `name` filter matches on all or prefix of a secret's name. - The following filter matches secret with a name containing a prefix of `test`. + The following filter matches secret with a name containing a prefix of `test`. - ```console - $ docker secret ls --filter name=test_secret + ```console + $ docker secret ls --filter name=test_secret - ID NAME CREATED UPDATED - mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago - ``` + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) pretty prints secrets output - using a Go template. + The formatting option (`--format`) pretty prints secrets output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |--------------|--------------------------------------------------------------------------------------| - | `.ID` | Secret ID | - | `.Name` | Secret name | - | `.CreatedAt` | Time when the secret was created | - | `.UpdatedAt` | Time when the secret was updated | - | `.Labels` | All labels assigned to the secret | - | `.Label` | Value of a specific label for this secret. For example `{{.Label "secret.ssh.key"}}` | + | Placeholder | Description | + |--------------|--------------------------------------------------------------------------------------| + | `.ID` | Secret ID | + | `.Name` | Secret name | + | `.CreatedAt` | Time when the secret was created | + | `.UpdatedAt` | Time when the secret was updated | + | `.Labels` | All labels assigned to the secret | + | `.Label` | Value of a specific label for this secret. For example `{{.Label "secret.ssh.key"}}` | - When using the `--format` option, the `secret ls` command will either - output the data exactly as the template declares or, when using the - `table` directive, will include column headers as well. + When using the `--format` option, the `secret ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, will include column headers as well. - The following example uses a template without headers and outputs the - `ID` and `Name` entries separated by a colon (`:`) for all images: + The following example uses a template without headers and outputs the + `ID` and `Name` entries separated by a colon (`:`) for all images: - ```console - $ docker secret ls --format "{{.ID}}: {{.Name}}" + ```console + $ docker secret ls --format "{{.ID}}: {{.Name}}" - 77af4d6b9913: secret-1 - b6fa739cedf5: secret-2 - 78a85c484f71: secret-3 - ``` + 77af4d6b9913: secret-1 + b6fa739cedf5: secret-2 + 78a85c484f71: secret-3 + ``` - To list all secrets with their name and created date in a table format you - can use: + To list all secrets with their name and created date in a table format you + can use: - ```console - $ docker secret ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}" + ```console + $ docker secret ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}" - ID NAME CREATED - 77af4d6b9913 secret-1 5 minutes ago - b6fa739cedf5 secret-2 3 hours ago - 78a85c484f71 secret-3 10 days ago - ``` + ID NAME CREATED + 77af4d6b9913 secret-1 5 minutes ago + b6fa739cedf5 secret-2 3 hours ago + 78a85c484f71 secret-3 10 days ago + ``` + + To list all secrets in JSON format, use the `json` directive: + ```console + $ docker secret ls --format json + {"CreatedAt":"28 seconds ago","Driver":"","ID":"4y7hvwrt1u8e9uxh5ygqj7mzc","Labels":"","Name":"mysecret","UpdatedAt":"28 seconds ago"} + ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_secret_rm.yaml b/_data/engine-cli/docker_secret_rm.yaml index 0d48a85a68..2dd46038c3 100644 --- a/_data/engine-cli/docker_secret_rm.yaml +++ b/_data/engine-cli/docker_secret_rm.yaml @@ -1,32 +1,43 @@ command: docker secret rm -aliases: remove +aliases: docker secret rm, docker secret remove short: Remove one or more secrets long: |- - Removes the specified secrets from the swarm. + Removes the specified secrets from the swarm. - For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/). + For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/). - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker secret rm SECRET [SECRET...] pname: docker secret plink: docker_secret.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - This example removes a secret: + This example removes a secret: - ```console - $ docker secret rm secret.json - sapth4csdo5b6wz2p5uimh5xg - ``` + ```console + $ docker secret rm secret.json + sapth4csdo5b6wz2p5uimh5xg + ``` - > **Warning** - > - > Unlike `docker rm`, this command does not ask for confirmation before removing - > a secret. + > **Warning** + > + > Unlike `docker rm`, this command does not ask for confirmation before removing + > a secret. deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_service.yaml b/_data/engine-cli/docker_service.yaml index 8a3e62ccdd..827db3f1fb 100644 --- a/_data/engine-cli/docker_service.yaml +++ b/_data/engine-cli/docker_service.yaml @@ -1,37 +1,48 @@ command: docker service -short: Manage services +short: Manage Swarm services long: |- - Manage services. + Manage Swarm services. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service pname: docker plink: docker.yaml cname: -- docker service create -- docker service inspect -- docker service logs -- docker service ls -- docker service ps -- docker service rm -- docker service rollback -- docker service scale -- docker service update + - docker service create + - docker service inspect + - docker service logs + - docker service ls + - docker service ps + - docker service rm + - docker service rollback + - docker service scale + - docker service update clink: -- docker_service_create.yaml -- docker_service_inspect.yaml -- docker_service_logs.yaml -- docker_service_ls.yaml -- docker_service_ps.yaml -- docker_service_rm.yaml -- docker_service_rollback.yaml -- docker_service_scale.yaml -- docker_service_update.yaml + - docker_service_create.yaml + - docker_service_inspect.yaml + - docker_service_logs.yaml + - docker_service_ls.yaml + - docker_service_ps.yaml + - docker_service_rm.yaml + - docker_service_rollback.yaml + - docker_service_scale.yaml + - docker_service_update.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_create.yaml b/_data/engine-cli/docker_service_create.yaml index feff327953..817c9716a0 100644 --- a/_data/engine-cli/docker_service_create.yaml +++ b/_data/engine-cli/docker_service_create.yaml @@ -1,1754 +1,1849 @@ command: docker service create short: Create a new service long: |- - Creates a service as described by the specified parameters. + Creates a service as described by the specified parameters. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker service plink: docker_service.yaml options: -- option: cap-add - value_type: list - description: Add Linux capabilities - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-drop - value_type: list - description: Drop Linux capabilities - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: config - value_type: config - description: Specify configurations to expose to the service - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: constraint - value_type: list - description: Placement constraints - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: container-label - value_type: list - description: Container labels - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: credential-spec - value_type: credential-spec - description: Credential spec for managed service account (Windows only) - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: | - Exit immediately instead of waiting for the service to converge - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns - value_type: list - description: Set custom DNS servers - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-option - value_type: list - description: Set DNS options - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-search - value_type: list - description: Set custom DNS search domains - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: endpoint-mode - value_type: string - default_value: vip - description: Endpoint mode (vip or dnsrr) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: entrypoint - value_type: command - description: Overwrite the default ENTRYPOINT of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env - shorthand: e - value_type: list - description: Set environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-file - value_type: list - description: Read in a file of environment variables - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: generic-resource - value_type: list - description: User defined resources - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: group - value_type: list - description: Set one or more supplementary user groups for the container - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-cmd - value_type: string - description: Command to run to check health - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-interval - value_type: duration - description: Time between running the check (ms|s|m|h) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-retries - value_type: int - default_value: "0" - description: Consecutive failures needed to report unhealthy - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-start-period - value_type: duration - description: | - Start period for the container to initialize before counting retries towards unstable (ms|s|m|h) - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-timeout - value_type: duration - description: Maximum time to allow one check to run (ms|s|m|h) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: host - value_type: list - description: Set one or more custom host-to-IP mappings (host:ip) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: hostname - value_type: string - description: Container hostname - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: init - value_type: bool - default_value: "false" - description: | - Use an init inside each service container to forward signals and reap processes - deprecated: false - min_api_version: "1.37" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Service container isolation mode - deprecated: false - min_api_version: "1.35" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - shorthand: l - value_type: list - description: Service labels - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: limit-cpu - value_type: decimal - description: Limit CPUs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: limit-memory - value_type: bytes - default_value: "0" - description: Limit Memory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: limit-pids - value_type: int64 - default_value: "0" - description: Limit maximum number of processes (default 0 = unlimited) - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: true -- option: log-driver - value_type: string - description: Logging driver for service - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-opt - value_type: list - description: Logging driver options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: max-concurrent - value_type: uint - description: | - Number of job tasks to run concurrently (default equal to --replicas) - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mode - value_type: string - default_value: replicated - description: | - Service mode (replicated, global, replicated-job, or global-job) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mount - value_type: mount - description: Attach a filesystem mount to the service - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: name - value_type: string - description: Service name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: network - description: Network attachments - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-healthcheck - value_type: bool - default_value: "false" - description: Disable any container-specified HEALTHCHECK - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-resolve-image - value_type: bool - default_value: "false" - description: | - Do not query the registry to resolve image digest and supported platforms - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: placement-pref - value_type: pref - description: Add a placement preference - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish - shorthand: p - value_type: port - description: Publish a port as a node port - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress progress output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: read-only - value_type: bool - default_value: "false" - description: Mount the container's root filesystem as read only - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: replicas - value_type: uint - description: Number of tasks - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: replicas-max-per-node - value_type: uint64 - default_value: "0" - description: Maximum number of tasks per node (default 0 = unlimited) - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: reserve-cpu - value_type: decimal - description: Reserve CPUs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: reserve-memory - value_type: bytes - default_value: "0" - description: Reserve Memory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart-condition - value_type: string - description: | - Restart when condition is met ("none"|"on-failure"|"any") (default "any") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart-delay - value_type: duration - description: Delay between restart attempts (ns|us|ms|s|m|h) (default 5s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart-max-attempts - value_type: uint - description: Maximum number of restarts before giving up - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart-window - value_type: duration - description: Window used to evaluate the restart policy (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-delay - value_type: duration - default_value: 0s - description: Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s) - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-failure-action - value_type: string - description: | - Action on rollback failure ("pause"|"continue") (default "pause") - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-max-failure-ratio - value_type: float - default_value: "0" - description: Failure rate to tolerate during a rollback (default 0) - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-monitor - value_type: duration - default_value: 0s - description: | - Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) (default 5s) - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-order - value_type: string - description: | - Rollback order ("start-first"|"stop-first") (default "stop-first") - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-parallelism - value_type: uint64 - default_value: "1" - description: | - Maximum number of tasks rolled back simultaneously (0 to roll back all at once) - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: secret - value_type: secret - description: Specify secrets to expose to the service - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-grace-period - value_type: duration - description: | - Time to wait before force killing a container (ns|us|ms|s|m|h) (default 10s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-signal - value_type: string - description: Signal to stop the container - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sysctl - value_type: list - description: Sysctl options - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: ulimit - default_value: '[]' - description: Ulimit options - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-delay - value_type: duration - default_value: 0s - description: Delay between updates (ns|us|ms|s|m|h) (default 0s) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-failure-action - value_type: string - description: | - Action on update failure ("pause"|"continue"|"rollback") (default "pause") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-max-failure-ratio - value_type: float - default_value: "0" - description: Failure rate to tolerate during an update (default 0) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-monitor - value_type: duration - default_value: 0s - description: | - Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 5s) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-order - value_type: string - description: | - Update order ("start-first"|"stop-first") (default "stop-first") - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-parallelism - value_type: uint64 - default_value: "1" - description: | - Maximum number of tasks updated simultaneously (0 to update all at once) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: with-registry-auth - value_type: bool - default_value: "false" - description: Send registry authentication details to swarm agents - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: cap-add + value_type: list + description: Add Linux capabilities + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-drop + value_type: list + description: Drop Linux capabilities + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: config + value_type: config + description: Specify configurations to expose to the service + details_url: '#config' + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: constraint + value_type: list + description: Placement constraints + details_url: '#constraint' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: container-label + value_type: list + description: Container labels + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: credential-spec + value_type: credential-spec + description: Credential spec for managed service account (Windows only) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: Exit immediately instead of waiting for the service to converge + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns + value_type: list + description: Set custom DNS servers + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-option + value_type: list + description: Set DNS options + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-search + value_type: list + description: Set custom DNS search domains + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: endpoint-mode + value_type: string + default_value: vip + description: Endpoint mode (vip or dnsrr) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: entrypoint + value_type: command + description: Overwrite the default ENTRYPOINT of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env + shorthand: e + value_type: list + description: Set environment variables + details_url: '#env' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: generic-resource + value_type: list + description: User defined resources + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: group + value_type: list + description: Set one or more supplementary user groups for the container + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-cmd + value_type: string + description: Command to run to check health + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-interval + value_type: duration + description: Time between running the check (ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-retries + value_type: int + default_value: "0" + description: Consecutive failures needed to report unhealthy + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-start-period + value_type: duration + description: | + Start period for the container to initialize before counting retries towards unstable (ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-timeout + value_type: duration + description: Maximum time to allow one check to run (ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: host + value_type: list + description: Set one or more custom host-to-IP mappings (host:ip) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: hostname + value_type: string + description: Container hostname + details_url: '#hostname' + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: init + value_type: bool + default_value: "false" + description: | + Use an init inside each service container to forward signals and reap processes + deprecated: false + hidden: false + min_api_version: "1.37" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Service container isolation mode + details_url: '#isolation' + deprecated: false + hidden: false + min_api_version: "1.35" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label + shorthand: l + value_type: list + description: Service labels + details_url: '#label' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: limit-cpu + value_type: decimal + description: Limit CPUs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: limit-memory + value_type: bytes + default_value: "0" + description: Limit Memory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: limit-pids + value_type: int64 + default_value: "0" + description: Limit maximum number of processes (default 0 = unlimited) + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-driver + value_type: string + description: Logging driver for service + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-opt + value_type: list + description: Logging driver options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: max-concurrent + value_type: uint + description: | + Number of job tasks to run concurrently (default equal to --replicas) + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mode + value_type: string + default_value: replicated + description: | + Service mode (`replicated`, `global`, `replicated-job`, `global-job`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mount + value_type: mount + description: Attach a filesystem mount to the service + details_url: '#mount' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: name + value_type: string + description: Service name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network + value_type: network + description: Network attachments + details_url: '#network' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-healthcheck + value_type: bool + default_value: "false" + description: Disable any container-specified HEALTHCHECK + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-resolve-image + value_type: bool + default_value: "false" + description: | + Do not query the registry to resolve image digest and supported platforms + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: placement-pref + value_type: pref + description: Add a placement preference + details_url: '#placement-pref' + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish + shorthand: p + value_type: port + description: Publish a port as a node port + details_url: '#publish' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress progress output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: read-only + value_type: bool + default_value: "false" + description: Mount the container's root filesystem as read only + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: replicas + value_type: uint + description: Number of tasks + details_url: '#replicas' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: replicas-max-per-node + value_type: uint64 + default_value: "0" + description: Maximum number of tasks per node (default 0 = unlimited) + details_url: '#replicas-max-per-node' + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: reserve-cpu + value_type: decimal + description: Reserve CPUs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: reserve-memory + value_type: bytes + default_value: "0" + description: Reserve Memory + details_url: '#reserve-memory' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart-condition + value_type: string + description: | + Restart when condition is met (`none`, `on-failure`, `any`) (default `any`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart-delay + value_type: duration + description: Delay between restart attempts (ns|us|ms|s|m|h) (default 5s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart-max-attempts + value_type: uint + description: Maximum number of restarts before giving up + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart-window + value_type: duration + description: Window used to evaluate the restart policy (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-delay + value_type: duration + default_value: 0s + description: Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-failure-action + value_type: string + description: Action on rollback failure (`pause`, `continue`) (default `pause`) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-max-failure-ratio + value_type: float + default_value: "0" + description: Failure rate to tolerate during a rollback (default 0) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-monitor + value_type: duration + default_value: 0s + description: | + Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) (default 5s) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-order + value_type: string + description: | + Rollback order (`start-first`, `stop-first`) (default `stop-first`) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-parallelism + value_type: uint64 + default_value: "1" + description: | + Maximum number of tasks rolled back simultaneously (0 to roll back all at once) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: secret + value_type: secret + description: Specify secrets to expose to the service + details_url: '#secret' + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-grace-period + value_type: duration + description: | + Time to wait before force killing a container (ns|us|ms|s|m|h) (default 10s) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-signal + value_type: string + description: Signal to stop the container + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sysctl + value_type: list + description: Sysctl options + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tty + shorthand: t + value_type: bool + default_value: "false" + description: Allocate a pseudo-TTY + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-delay + value_type: duration + default_value: 0s + description: Delay between updates (ns|us|ms|s|m|h) (default 0s) + details_url: '#update-delay' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-failure-action + value_type: string + description: | + Action on update failure (`pause`, `continue`, `rollback`) (default `pause`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-max-failure-ratio + value_type: float + default_value: "0" + description: Failure rate to tolerate during an update (default 0) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-monitor + value_type: duration + default_value: 0s + description: | + Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 5s) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-order + value_type: string + description: Update order (`start-first`, `stop-first`) (default `stop-first`) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-parallelism + value_type: uint64 + default_value: "1" + description: | + Maximum number of tasks updated simultaneously (0 to update all at once) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: user + shorthand: u + value_type: string + description: 'Username or UID (format: [:])' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: with-registry-auth + value_type: bool + default_value: "false" + description: Send registry authentication details to swarm agents + details_url: '#with-registry-auth' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workdir + shorthand: w + value_type: string + description: Working directory inside the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Create a service + ### Create a service - ```console - $ docker service create --name redis redis:3.0.6 + ```console + $ docker service create --name redis redis:3.0.6 - dmu1ept4cxcfe8k8lhtux3ro3 + dmu1ept4cxcfe8k8lhtux3ro3 - $ docker service create --mode global --name redis2 redis:3.0.6 + $ docker service create --mode global --name redis2 redis:3.0.6 - a8q9dasaafudfs8q8w32udass + a8q9dasaafudfs8q8w32udass - $ docker service ls + $ docker service ls - ID NAME MODE REPLICAS IMAGE - dmu1ept4cxcf redis replicated 1/1 redis:3.0.6 - a8q9dasaafud redis2 global 1/1 redis:3.0.6 - ``` + ID NAME MODE REPLICAS IMAGE + dmu1ept4cxcf redis replicated 1/1 redis:3.0.6 + a8q9dasaafud redis2 global 1/1 redis:3.0.6 + ``` - #### Create a service using an image on a private registry (--with-registry-auth) + #### Create a service using an image on a private registry (--with-registry-auth) {#with-registry-auth} - If your image is available on a private registry which requires login, use the - `--with-registry-auth` flag with `docker service create`, after logging in. If - your image is stored on `registry.example.com`, which is a private registry, use - a command like the following: + If your image is available on a private registry which requires login, use the + `--with-registry-auth` flag with `docker service create`, after logging in. If + your image is stored on `registry.example.com`, which is a private registry, use + a command like the following: - ```console - $ docker login registry.example.com + ```console + $ docker login registry.example.com - $ docker service create \ - --with-registry-auth \ - --name my_service \ - registry.example.com/acme/my_image:latest - ``` + $ docker service create \ + --with-registry-auth \ + --name my_service \ + registry.example.com/acme/my_image:latest + ``` - This passes the login token from your local client to the swarm nodes where the - service is deployed, using the encrypted WAL logs. With this information, the - nodes are able to log into the registry and pull the image. + This passes the login token from your local client to the swarm nodes where the + service is deployed, using the encrypted WAL logs. With this information, the + nodes are able to log into the registry and pull the image. - ### Create a service with 5 replica tasks (--replicas) + ### Create a service with 5 replica tasks (--replicas) {#replicas} - Use the `--replicas` flag to set the number of replica tasks for a replicated - service. The following command creates a `redis` service with `5` replica tasks: + Use the `--replicas` flag to set the number of replica tasks for a replicated + service. The following command creates a `redis` service with `5` replica tasks: - ```console - $ docker service create --name redis --replicas=5 redis:3.0.6 + ```console + $ docker service create --name redis --replicas=5 redis:3.0.6 - 4cdgfyky7ozwh3htjfw0d12qv - ``` + 4cdgfyky7ozwh3htjfw0d12qv + ``` - The above command sets the *desired* number of tasks for the service. Even - though the command returns immediately, actual scaling of the service may take - some time. The `REPLICAS` column shows both the *actual* and *desired* number - of replica tasks for the service. + The above command sets the *desired* number of tasks for the service. Even + though the command returns immediately, actual scaling of the service may take + some time. The `REPLICAS` column shows both the *actual* and *desired* number + of replica tasks for the service. - In the following example the desired state is `5` replicas, but the current - number of `RUNNING` tasks is `3`: + In the following example the desired state is `5` replicas, but the current + number of `RUNNING` tasks is `3`: - ```console - $ docker service ls + ```console + $ docker service ls - ID NAME MODE REPLICAS IMAGE - 4cdgfyky7ozw redis replicated 3/5 redis:3.0.7 - ``` + ID NAME MODE REPLICAS IMAGE + 4cdgfyky7ozw redis replicated 3/5 redis:3.0.7 + ``` - Once all the tasks are created and `RUNNING`, the actual number of tasks is - equal to the desired number: + Once all the tasks are created and `RUNNING`, the actual number of tasks is + equal to the desired number: - ```console - $ docker service ls + ```console + $ docker service ls - ID NAME MODE REPLICAS IMAGE - 4cdgfyky7ozw redis replicated 5/5 redis:3.0.7 - ``` + ID NAME MODE REPLICAS IMAGE + 4cdgfyky7ozw redis replicated 5/5 redis:3.0.7 + ``` - ### Create a service with secrets (--secret) + ### Create a service with secrets (--secret) {#secret} - Use the `--secret` flag to give a container access to a - [secret](secret_create.md). + Use the `--secret` flag to give a container access to a + [secret](secret_create.md). - Create a service specifying a secret: + Create a service specifying a secret: - ```console - $ docker service create --name redis --secret secret.json redis:3.0.6 + ```console + $ docker service create --name redis --secret secret.json redis:3.0.6 - 4cdgfyky7ozwh3htjfw0d12qv - ``` + 4cdgfyky7ozwh3htjfw0d12qv + ``` - Create a service specifying the secret, target, user/group ID, and mode: + Create a service specifying the secret, target, user/group ID, and mode: - ```console - $ docker service create --name redis \ - --secret source=ssh-key,target=ssh \ - --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \ - redis:3.0.6 + ```console + $ docker service create --name redis \ + --secret source=ssh-key,target=ssh \ + --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \ + redis:3.0.6 - 4cdgfyky7ozwh3htjfw0d12qv - ``` + 4cdgfyky7ozwh3htjfw0d12qv + ``` - To grant a service access to multiple secrets, use multiple `--secret` flags. + 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. - If no target is specified, the name of the secret is used as the in memory file - in the container. If a target is specified, that is used as the filename. In the - example above, two files are created: `/run/secrets/ssh` and - `/run/secrets/app` for each of the secret targets specified. + Secrets are located in `/run/secrets` in the container if no target is specified. + If no target is specified, the name of the secret is used as the in memory file + in the container. If a target is specified, that is used as the filename. In the + example above, two files are created: `/run/secrets/ssh` and + `/run/secrets/app` for each of the secret targets specified. - ### Create a service with configs (--config) + ### Create a service with configs (--config) {#config} - Use the `--config` flag to give a container access to a - [config](config_create.md). + Use the `--config` flag to give a container access to a + [config](config_create.md). - Create a service with a config. The config will be mounted into `redis-config`, - be owned by the user who runs the command inside the container (often `root`), - and have file mode `0444` or world-readable. You can specify the `uid` and `gid` - as numerical IDs or names. When using names, the provided group/user names must - pre-exist in the container. The `mode` is specified as a 4-number sequence such - as `0755`. + Create a service with a config. The config will be mounted into `redis-config`, + be owned by the user who runs the command inside the container (often `root`), + and have file mode `0444` or world-readable. You can specify the `uid` and `gid` + as numerical IDs or names. When using names, the provided group/user names must + pre-exist in the container. The `mode` is specified as a 4-number sequence such + as `0755`. - ```console - $ docker service create --name=redis --config redis-conf redis:3.0.6 - ``` + ```console + $ docker service create --name=redis --config redis-conf redis:3.0.6 + ``` - Create a service with a config and specify the target location and file mode: + Create a service with a config and specify the target location and file mode: - ```console - $ docker service create --name redis \ - --config source=redis-conf,target=/etc/redis/redis.conf,mode=0400 redis:3.0.6 - ``` + ```console + $ docker service create --name redis \ + --config source=redis-conf,target=/etc/redis/redis.conf,mode=0400 redis:3.0.6 + ``` - To grant a service access to multiple configs, use multiple `--config` flags. + To grant a service access to multiple configs, use multiple `--config` flags. - Configs are located in `/` in the container if no target is specified. If no - target is specified, the name of the config is used as the name of the file in - the container. If a target is specified, that is used as the filename. + Configs are located in `/` in the container if no target is specified. If no + target is specified, the name of the config is used as the name of the file in + the container. If a target is specified, that is used as the filename. - ### Create a service with a rolling update policy + ### Create a service with a rolling update policy {#update-delay} - ```console - $ docker service create \ - --replicas 10 \ - --name redis \ - --update-delay 10s \ - --update-parallelism 2 \ - redis:3.0.6 - ``` - - When you run a [service update](service_update.md), the scheduler updates a - maximum of 2 tasks at a time, with `10s` between updates. For more information, - refer to the [rolling updates - tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/). - - ### Set environment variables (-e, --env) - - This sets an environment variable for all tasks in a service. For example: - - ```console - $ 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. - - ```console - $ 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) - - This option sets the docker service containers hostname to a specific string. - For example: - - ```console - $ docker service create --name redis --hostname myredis redis:3.0.6 - ``` - - ### Set metadata on a service (-l, --label) - - A label is a `key=value` pair that applies metadata to a service. To label a - service with two labels: - - ```console - $ docker service create \ - --name redis_2 \ - --label com.example.foo="bar" \ - --label bar=baz \ - redis:3.0.6 - ``` - - For more information about labels, refer to [apply custom - metadata](https://docs.docker.com/config/labels-custom-metadata/). - - ### Add bind mounts, volumes or memory filesystems (--mount) - - Docker supports three different kinds of mounts, which allow containers to read - from or write to files or directories, either on the host operating system, or - on memory filesystems. These types are _data volumes_ (often referred to simply - as volumes), _bind mounts_, _tmpfs_, and _named pipes_. - - A **bind mount** makes a file or directory on the host available to the - container it is mounted within. A bind mount may be either read-only or - read-write. For example, a container might share its host's DNS information by - means of a bind mount of the host's `/etc/resolv.conf` or a container might - write logs to its host's `/var/log/myContainerLogs` directory. If you use - bind mounts and your host and containers have different notions of permissions, - access controls, or other such details, you will run into portability issues. - - A **named volume** is a mechanism for decoupling persistent data needed by your - container from the image used to create the container and from the host machine. - Named volumes are created and managed by Docker, and a named volume persists - even when no container is currently using it. Data in named volumes can be - shared between a container and the host machine, as well as between multiple - containers. Docker uses a _volume driver_ to create, manage, and mount volumes. - You can back up or restore volumes using Docker commands. - - A **tmpfs** mounts a tmpfs inside a container for volatile data. - - A **npipe** mounts a named pipe from the host into the container. - - Consider a situation where your image starts a lightweight web server. You could - use that image as a base image, copy in your website's HTML files, and package - that into another image. Each time your website changed, you'd need to update - the new image and redeploy all of the containers serving your website. A better - solution is to store the website in a named volume which is attached to each of - your web server containers when they start. To update the website, you just - update the named volume. - - For more information about named volumes, see - [Data Volumes](https://docs.docker.com/storage/volumes/). - - The following table describes options which apply to both bind mounts and named - volumes in a service: - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OptionRequiredDescription
type -

The type of mount, can be either volume, bind, tmpfs, or npipe. Defaults to volume if no type is specified.

-
    -
  • volume: mounts a managed volume - into the container.
  • bind: - bind-mounts a directory or file from the host into the container.
    • -
  • tmpfs: mount a tmpfs in the container
    • -
  • npipe: mounts named pipe from the host into the container (Windows containers only).
    • -
-
src or sourcefor type=bind and type=npipe -
    -
  • - type=volume: src is an optional way to specify the name of the volume (for example, src=my-volume). - If the named volume does not exist, it is automatically created. If no src is specified, the volume is - assigned a random name which is guaranteed to be unique on the host, but may not be unique cluster-wide. - A randomly-named volume has the same lifecycle as its container and is destroyed when the container - is destroyed (which is upon service update, or when scaling or re-balancing the service) -
    • -
  • - type=bind: src is required, and specifies an absolute path to the file or directory to bind-mount - (for example, src=/path/on/host/). An error is produced if the file or directory does not exist. -
    • -
  • - type=tmpfs: src is not supported. -
    • -
-

dst or destination or target

yes -

Mount path inside the container, for example /some/path/in/container/. - If the path does not exist in the container's filesystem, the Engine creates - a directory at the specified location before mounting the volume or bind mount.

-

readonly or ro

 -

The Engine mounts binds and volumes read-write unless readonly option - is given when mounting the bind or volume. Note that setting readonly for a - bind-mount does not make its submounts readonly on the current Linux implementation. See also bind-nonrecursive.

-
    -
  • true or 1 or no value: Mounts the bind or volume read-only.
    • -
  • false or 0: Mounts the bind or volume read-write.
    • -
-
- - #### Options for Bind Mounts - - The following options can only be used for bind mounts (`type=bind`): - - - - - - - - - - - - - - - - - - - -
OptionDescription
bind-propagation -

See the bind propagation section.

-
consistency -

The consistency requirements for the mount; one of

-
    -
  • default: Equivalent to consistent.
    • -
  • consistent: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.
    • -
  • cached: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.
    • -
  • delegated: 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.
    • -
-
bind-nonrecursive - By default, submounts are recursively bind-mounted as well. However, this behavior can be confusing when a - bind mount is configured with readonly option, because submounts are not mounted as read-only. - Set bind-nonrecursive to disable recursive bind-mount.
-
- A value is optional:
-
-
    -
  • true or 1: Disables recursive bind-mount.
    • -
  • false or 0: Default if you do not provide a value. Enables recursive bind-mount.
    • -
-
- - ##### Bind propagation - - Bind propagation refers to whether or not mounts created within a given - bind mount or named volume can be propagated to replicas of that mount. Consider - a mount point `/mnt`, which is also mounted on `/tmp`. The propagation settings - control whether a mount on `/tmp/a` would also be available on `/mnt/a`. Each - propagation setting has a recursive counterpoint. In the case of recursion, - consider that `/tmp/a` is also mounted as `/foo`. The propagation settings - control whether `/mnt/a` and/or `/tmp/a` would exist. - - The `bind-propagation` option defaults to `rprivate` for both bind mounts and - volume mounts, and is only configurable for bind mounts. In other words, named - volumes do not support bind propagation. - - - **`shared`**: Sub-mounts of the original mount are exposed to replica mounts, - and sub-mounts of replica mounts are also propagated to the - original mount. - - **`slave`**: similar to a shared mount, but only in one direction. If the - original mount exposes a sub-mount, the replica mount can see it. - However, if the replica mount exposes a sub-mount, the original - mount cannot see it. - - **`private`**: The mount is private. Sub-mounts within it are not exposed to - replica mounts, and sub-mounts of replica mounts are not - exposed to the original mount. - - **`rshared`**: The same as shared, but the propagation also extends to and from - mount points nested within any of the original or replica mount - points. - - **`rslave`**: The same as `slave`, but the propagation also extends to and from - mount points nested within any of the original or replica mount - points. - - **`rprivate`**: The default. The same as `private`, meaning that no mount points - anywhere within the original or replica mount points propagate - in either direction. - - For more information about bind propagation, see the - [Linux kernel documentation for shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt). - - #### Options for named volumes - - The following options can only be used for named volumes (`type=volume`): - - - - - - - - - - - - - - - - - - - - - - - -
OptionDescription
volume-driver -

Name of the volume-driver plugin to use for the volume. Defaults to - "local", to use the local volume driver to create the volume if the - volume does not exist.

-
volume-label - One or more custom metadata ("labels") to apply to the volume upon - creation. For example, - volume-label=mylabel=hello-world,my-other-label=hello-mars. For more - information about labels, refer to - apply custom metadata. -
volume-nocopy - By default, if you attach an empty volume to a container, and files or - directories already existed at the mount-path in the container (dst), - the Engine copies those files and directories into the volume, allowing - the host to access them. Set volume-nocopy to disable copying files - from the container's filesystem to the volume and mount the empty volume.
-
- A value is optional:
-
-
    -
  • true or 1: Default if you do not provide a value. Disables copying.
    • -
  • false or 0: Enables copying.
    • -
-
volume-opt - Options specific to a given volume driver, which will be passed to the - driver when creating the volume. Options are provided as a comma-separated - list of key/value pairs, for example, - volume-opt=some-option=some-value,volume-opt=some-other-option=some-other-value. - For available options for a given driver, refer to that driver's - documentation. -
- - - #### Options for tmpfs - - The following options can only be used for tmpfs mounts (`type=tmpfs`); - - - - - - - - - - - - - - - -
OptionDescription
tmpfs-sizeSize of the tmpfs mount in bytes. Unlimited by default in Linux.
tmpfs-modeFile mode of the tmpfs in octal. (e.g. "700" or "0700".) Defaults to "1777" in Linux.
- - - #### Differences between "--mount" and "--volume" - - The `--mount` flag supports most options that are supported by the `-v` - or `--volume` flag for `docker run`, with some important exceptions: - - - The `--mount` flag allows you to specify a volume driver and volume driver - options *per volume*, without creating the volumes in advance. In contrast, - `docker run` allows you to specify a single volume driver which is shared - by all volumes, using the `--volume-driver` flag. - - - The `--mount` flag allows you to specify custom metadata ("labels") for a volume, - before the volume is created. - - - When you use `--mount` with `type=bind`, the host-path must refer to an *existing* - path on the host. The path will not be created for you and the service will fail - with an error if the path does not exist. - - - The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags, - which are used for `selinux` labeling. - - #### Create a service using a named volume - - The following example creates a service that uses a named volume: - - ```console - $ docker service create \ - --name my-service \ - --replicas 3 \ - --mount type=volume,source=my-volume,destination=/path/in/container,volume-label="color=red",volume-label="shape=round" \ - nginx:alpine - ``` - - For each replica of the service, the engine requests a volume named "my-volume" - from the default ("local") volume driver where the task is deployed. If the - volume does not exist, the engine creates a new volume and applies the "color" - and "shape" labels. - - When the task is started, the volume is mounted on `/path/in/container/` inside - the container. - - Be aware that the default ("local") volume is a locally scoped volume driver. - This means that depending on where a task is deployed, either that task gets a - *new* volume named "my-volume", or shares the same "my-volume" with other tasks - of the same service. Multiple containers writing to a single shared volume can - cause data corruption if the software running inside the container is not - designed to handle concurrent processes writing to the same location. Also take - into account that containers can be re-scheduled by the Swarm orchestrator and - be deployed on a different node. - - #### Create a service that uses an anonymous volume - - The following command creates a service with three replicas with an anonymous - volume on `/path/in/container`: - - ```console - $ docker service create \ - --name my-service \ - --replicas 3 \ - --mount type=volume,destination=/path/in/container \ - nginx:alpine - ``` - - In this example, no name (`source`) is specified for the volume, so a new volume - is created for each task. This guarantees that each task gets its own volume, - and volumes are not shared between tasks. Anonymous volumes are removed after - the task using them is complete. - - #### Create a service that uses a bind-mounted host directory - - The following example bind-mounts a host directory at `/path/in/container` in - the containers backing the service: - - ```console - $ docker service create \ - --name my-service \ - --mount type=bind,source=/path/on/host,destination=/path/in/container \ - nginx:alpine - ``` - - ### Set service mode (--mode) - - The service mode determines whether this is a _replicated_ service or a _global_ - service. A replicated service runs as many tasks as specified, while a global - service runs on each active node in the swarm. - - The following command creates a global service: - - ```console - $ docker service create \ - --name redis_2 \ - --mode global \ - redis:3.0.6 - ``` - - ### Specify service constraints (--constraint) - - You can limit the set of nodes where a task can be scheduled by defining - constraint expressions. Constraint expressions can either use a _match_ (`==`) - or _exclude_ (`!=`) rule. Multiple constraints find nodes that satisfy every - expression (AND match). Constraints can match node or Docker Engine labels as - follows: - - | node attribute | matches | example | - |----------------------|--------------------------------|-----------------------------------------------| - | `node.id` | Node ID | `node.id==2ivku8v2gvtg4` | - | `node.hostname` | Node hostname | `node.hostname!=node-2` | - | `node.role` | Node role (`manager`/`worker`) | `node.role==manager` | - | `node.platform.os` | Node operating system | `node.platform.os==windows` | - | `node.platform.arch` | Node architecture | `node.platform.arch==x86_64` | - | `node.labels` | User-defined node labels | `node.labels.security==high` | - | `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-22.04` | - - `engine.labels` apply to Docker Engine labels like operating system, drivers, - etc. Swarm administrators add `node.labels` for operational purposes by using - the [`docker node update`](node_update.md) command. - - For example, the following limits tasks for the redis service to nodes where the - node type label equals queue: - - ```console - $ docker service create \ - --name redis_2 \ - --constraint node.platform.os==linux \ - --constraint node.labels.type==queue \ - redis:3.0.6 - ``` - - If the service constraints exclude all nodes in the cluster, a message is printed - that no suitable node is found, but the scheduler will start a reconciliation - loop and deploy the service once a suitable node becomes available. - - In the example below, no node satisfying the constraint was found, causing the - service to not reconcile with the desired state: - - ```console - $ docker service create \ - --name web \ - --constraint node.labels.region==east \ - nginx:alpine - - lx1wrhhpmbbu0wuk0ybws30bc - overall progress: 0 out of 1 tasks - 1/1: no suitable node (scheduling constraints not satisfied on 5 nodes) - - $ docker service ls - ID NAME MODE REPLICAS IMAGE PORTS - b6lww17hrr4e web replicated 0/1 nginx:alpine - ``` - - After adding the `region=east` label to a node in the cluster, the service - reconciles, and the desired number of replicas are deployed: - - ```console - $ docker node update --label-add region=east yswe2dm4c5fdgtsrli1e8ya5l - yswe2dm4c5fdgtsrli1e8ya5l - - $ docker service ls - ID NAME MODE REPLICAS IMAGE PORTS - b6lww17hrr4e web replicated 1/1 nginx:alpine - ``` - - ### Specify service placement preferences (--placement-pref) - - You can set up the service to divide tasks evenly over different categories of - nodes. One example of where this can be useful is to balance tasks over a set - of datacenters or availability zones. The example below illustrates this: - - ```console - $ docker service create \ - --replicas 9 \ - --name redis_2 \ - --placement-pref spread=node.labels.datacenter \ - redis:3.0.6 - ``` - - This uses `--placement-pref` with a `spread` strategy (currently the only - supported strategy) to spread tasks evenly over the values of the `datacenter` - node label. In this example, we assume that every node has a `datacenter` node - label attached to it. If there are three different values of this label among - nodes in the swarm, one third of the tasks will be placed on the nodes - associated with each value. This is true even if there are more nodes with one - value than another. For example, consider the following set of nodes: - - - Three nodes with `node.labels.datacenter=east` - - Two nodes with `node.labels.datacenter=south` - - One node with `node.labels.datacenter=west` - - Since we are spreading over the values of the `datacenter` label and the - service has 9 replicas, 3 replicas will end up in each datacenter. There are - three nodes associated with the value `east`, so each one will get one of the - three replicas reserved for this value. There are two nodes with the value - `south`, and the three replicas for this value will be divided between them, - with one receiving two replicas and another receiving just one. Finally, `west` - has a single node that will get all three replicas reserved for `west`. - - If the nodes in one category (for example, those with - `node.labels.datacenter=south`) can't handle their fair share of tasks due to - constraints or resource limitations, the extra tasks will be assigned to other - nodes instead, if possible. - - Both engine labels and node labels are supported by placement preferences. The - example above uses a node label, because the label is referenced with - `node.labels.datacenter`. To spread over the values of an engine label, use - `--placement-pref spread=engine.labels.`. - - It is possible to add multiple placement preferences to a service. This - establishes a hierarchy of preferences, so that tasks are first divided over - one category, and then further divided over additional categories. One example - of where this may be useful is dividing tasks fairly between datacenters, and - then splitting the tasks within each datacenter over a choice of racks. To add - multiple placement preferences, specify the `--placement-pref` flag multiple - times. The order is significant, and the placement preferences will be applied - in the order given when making scheduling decisions. - - The following example sets up a service with multiple placement preferences. - Tasks are spread first over the various datacenters, and then over racks - (as indicated by the respective labels): - - ```console - $ docker service create \ - --replicas 9 \ - --name redis_2 \ - --placement-pref 'spread=node.labels.datacenter' \ - --placement-pref 'spread=node.labels.rack' \ - redis:3.0.6 - ``` - - When updating a service with `docker service update`, `--placement-pref-add` - appends a new placement preference after all existing placement preferences. - `--placement-pref-rm` removes an existing placement preference that matches the - argument. - - ### Specify memory requirements and constraints for a service (--reserve-memory and --limit-memory) - - If your service needs a minimum amount of memory in order to run correctly, - you can use `--reserve-memory` to specify that the service should only be - scheduled on a node with this much memory available to reserve. If no node is - available that meets the criteria, the task is not scheduled, but remains in a - pending state. - - The following example requires that 4GB of memory be available and reservable - on a given node before scheduling the service to run on that node. - - ```console - $ docker service create --reserve-memory=4GB --name=too-big nginx:alpine - ``` - - The managers won't schedule a set of containers on a single node whose combined - reservations exceed the memory available on that node. - - After a task is scheduled and running, `--reserve-memory` does not enforce a - memory limit. Use `--limit-memory` to ensure that a task uses no more than a - given amount of memory on a node. This example limits the amount of memory used - by the task to 4GB. The task will be scheduled even if each of your nodes has - only 2GB of memory, because `--limit-memory` is an upper limit. - - ```console - $ docker service create --limit-memory=4GB --name=too-big nginx:alpine - ``` - - Using `--reserve-memory` and `--limit-memory` does not guarantee that Docker - will not use more memory on your host than you want. For instance, you could - create many services, the sum of whose memory usage could exhaust the available - memory. - - You can prevent this scenario from exhausting the available memory by taking - into account other (non-containerized) software running on the host as well. If - `--reserve-memory` is greater than or equal to `--limit-memory`, Docker won't - schedule a service on a host that doesn't have enough memory. `--limit-memory` - will limit the service's memory to stay within that limit, so if every service - has a memory-reservation and limit set, Docker services will be less likely to - saturate the host. Other non-service containers or applications running directly - on the Docker host could still exhaust memory. - - There is a downside to this approach. Reserving memory also means that you may - not make optimum use of the memory available on the node. Consider a service - that under normal circumstances uses 100MB of memory, but depending on load can - "peak" at 500MB. Reserving 500MB for that service (to guarantee can have 500MB - for those "peaks") results in 400MB of memory being wasted most of the time. - - In short, you can take a more conservative or more flexible approach: - - - **Conservative**: reserve 500MB, and limit to 500MB. Basically you're now - treating the service containers as VMs, and you may be losing a big advantage - containers, which is greater density of services per host. - - - **Flexible**: limit to 500MB in the assumption that if the service requires - more than 500MB, it is malfunctioning. Reserve something between the 100MB - "normal" requirement and the 500MB "peak" requirement". This assumes that when - this service is at "peak", other services or non-container workloads probably - won't be. - - The approach you take depends heavily on the memory-usage patterns of your - workloads. You should test under normal and peak conditions before settling - on an approach. - - On Linux, you can also limit a service's overall memory footprint on a given - host at the level of the host operating system, using `cgroups` or other - relevant operating system tools. - - ### Specify maximum replicas per node (--replicas-max-per-node) - - Use the `--replicas-max-per-node` flag to set the maximum number of replica tasks that can run on a node. - The following command creates a nginx service with 2 replica tasks but only one replica task per node. - - One example where this can be useful is to balance tasks over a set of data centers together with `--placement-pref` - and let `--replicas-max-per-node` setting make sure that replicas are not migrated to another datacenter during - maintenance or datacenter failure. - - The example below illustrates this: - - ```console - $ docker service create \ - --name nginx \ - --replicas 2 \ - --replicas-max-per-node 1 \ - --placement-pref 'spread=node.labels.datacenter' \ - nginx - ``` - - ### Attach a service to an existing network (--network) - - You can use overlay networks to connect one or more services within the swarm. - - First, create an overlay network on a manager node the docker network create - command: - - ```console - $ docker network create --driver overlay my-network - - etjpu59cykrptrgw0z0hk5snf - ``` - - After you create an overlay network in swarm mode, all manager nodes have - access to the network. - - When you create a service and pass the `--network` flag to attach the service to - the overlay network: - - ```console - $ docker service create \ - --replicas 3 \ - --network my-network \ - --name my-web \ - nginx - - 716thylsndqma81j6kkkb5aus - ``` - - The swarm extends my-network to each node running the service. - - Containers on the same network can access each other using - [service discovery](https://docs.docker.com/network/overlay/#container-discovery). - - Long form syntax of `--network` allows to specify list of aliases and driver options: - `--network name=my-network,alias=web1,driver-opt=field1=value1` - - ### 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. The `--publish` flag can take two different styles - of arguments. The short version is positional, and allows you to specify the - published port and target port separated by a colon (`:`). - - ```console - $ docker service create --name my_web --replicas 3 --publish 8080:80 nginx - ``` - - 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: - - ```console - $ docker service create --name my_web --replicas 3 --publish published=8080,target=80 nginx - ``` - - The options you can specify are: - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OptionShort syntaxLong syntaxDescription
published and target port--publish 8080:80--publish published=8080,target=80

- The target port within the container and the port to map it to on the - nodes, using the routing mesh (ingress) or host-level networking. - More options are available, later in this table. The key-value syntax is - preferred, because it is somewhat self-documenting. -

modeNot possible to set using short syntax.--publish published=8080,target=80,mode=host

- The mode to use for binding the port, either ingress or host. - Defaults to ingress to use the routing mesh. -

protocol--publish 8080:80/tcp--publish published=8080,target=80,protocol=tcp

- The protocol to use, tcp , udp, or sctp. Defaults to - tcp. To bind a port for both protocols, specify the -p or - --publish flag twice. -

- - When you publish a service port using `ingress` mode, the swarm routing mesh - makes the service accessible at the published 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/). - - ### Provide credential specs for managed service accounts (--credentials-spec) - - This option is only used for services using Windows containers. The - `--credential-spec` must be in the format `file://` or - `registry://`. - - When using the `file://` format, the referenced file must be - present in the `CredentialSpecs` subdirectory in the docker data directory, - which defaults to `C:\ProgramData\Docker\` on Windows. For example, - specifying `file://spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`. - - When using the `registry://` format, the credential spec is - read from the Windows registry on the daemon's host. The specified - registry value must be located in: - - HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs - - - ### Create services using templates - - You can use templates for some flags of `service create`, using the syntax - provided by the Go's [text/template](https://golang.org/pkg/text/template/) package. - - The supported flags are the following : - - - `--hostname` - - `--mount` - - `--env` - - Valid placeholders for the Go template are listed below: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PlaceholderDescription
.Service.IDService ID
.Service.NameService name
.Service.LabelsService labels
.Node.IDNode ID
.Node.HostnameNode Hostname
.Task.IDTask ID
.Task.NameTask name
.Task.SlotTask slot
- - - #### Template example - - In this example, we are going to set the template of the created containers based on the - service's name, the node's ID and hostname where it sits. - - ```console - $ docker service create \ - --name hosttempl \ - --hostname="{{.Node.Hostname}}-{{.Node.ID}}-{{.Service.Name}}"\ - busybox top - - va8ew30grofhjoychbr6iot8c - - $ docker service ps va8ew30grofhjoychbr6iot8c - - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - wo41w8hg8qan hosttempl.1 busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 2e7a8a9c4da2 Running Running about a minute ago - - $ docker inspect --format="{{.Config.Hostname}}" 2e7a8a9c4da2-wo41w8hg8qanxwjwsg4kxpprj-hosttempl - - x3ti0erg11rjpg64m75kej2mz-hosttempl - ``` - - ### Specify isolation mode on Windows (--isolation) - - By default, tasks scheduled on Windows nodes are run using the default isolation mode - configured for this particular node. To force a specific isolation mode, you can use - the `--isolation` flag: - - ```console - $ docker service create --name myservice --isolation=process microsoft/nanoserver - ``` - - Supported isolation modes on Windows are: - - `default`: use default settings specified on the node running the task - - `process`: use process isolation (Windows server only) - - `hyperv`: use Hyper-V isolation - - ### Create services requesting Generic Resources (--generic-resources) - - You can narrow the kind of nodes your task can land on through the using the - `--generic-resource` flag (if the nodes advertise these resources): - - ```console - $ docker service create \ - --name cuda \ - --generic-resource "NVIDIA-GPU=2" \ - --generic-resource "SSD=1" \ - nvidia/cuda - ``` - - ### Running as a job - - Jobs are a special kind of service designed to run an operation to completion - and then stop, as opposed to running long-running daemons. When a Task - belonging to a job exits successfully (return value 0), the Task is marked as - "Completed", and is not run again. - - Jobs are started by using one of two modes, `replicated-job` or `global-job` - - ```console - $ docker service create --name myjob \ - --mode replicated-job \ - bash "true" - ``` - - This command will run one Task, which will, using the `bash` image, execute the - command `true`, which will return 0 and then exit. - - Though Jobs are ultimately a different kind of service, they a couple of - caveats compared to other services: - - - None of the update or rollback configuration options are valid. Jobs can be - updated, but cannot be rolled out or rolled back, making these configuration - options moot. - - Jobs are never restarted on reaching the `Complete` state. This means that - for jobs, setting `--restart-condition` to `any` is the same as setting it to - `on-failure`. - - Jobs are available in both replicated and global modes. - - #### Replicated Jobs - - A replicated job is like a replicated service. Setting the `--replicas` flag - will specify total number of iterations of a job to execute. - - By default, all replicas of a replicated job will launch at once. To control - the total number of replicas that are executing simultaneously at any one time, - the `--max-concurrent` flag can be used: - - ```console - $ docker service create \ - --name mythrottledjob \ - --mode replicated-job \ + ```console + $ docker service create \ --replicas 10 \ - --max-concurrent 2 \ - bash "true" - ``` + --name redis \ + --update-delay 10s \ + --update-parallelism 2 \ + redis:3.0.6 + ``` - The above command will execute 10 Tasks in total, but only 2 of them will be - run at any given time. + When you run a [service update](service_update.md), the scheduler updates a + maximum of 2 tasks at a time, with `10s` between updates. For more information, + refer to the [rolling updates + tutorial](/engine/swarm/swarm-tutorial/rolling-update/). - #### Global Jobs + ### Set environment variables (-e, --env) {#env} - Global jobs are like global services, in that a Task is executed once on each node - matching placement constraints. Global jobs are represented by the mode `global-job`. + This sets an environment variable for all tasks in a service. For example: - Note that after a Global job is created, any new Nodes added to the cluster - will have a Task from that job started on them. The Global Job does not as a - whole have a "done" state, except insofar as every Node meeting the job's - constraints has a Completed task. + ```console + $ 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. + + ```console + $ 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) {#hostname} + + This option sets the docker service containers hostname to a specific string. + For example: + + ```console + $ docker service create --name redis --hostname myredis redis:3.0.6 + ``` + + ### Set metadata on a service (-l, --label) {#label} + + A label is a `key=value` pair that applies metadata to a service. To label a + service with two labels: + + ```console + $ docker service create \ + --name redis_2 \ + --label com.example.foo="bar" \ + --label bar=baz \ + redis:3.0.6 + ``` + + For more information about labels, refer to [apply custom + metadata](/config/labels-custom-metadata/). + + ### Add bind mounts, volumes or memory filesystems (--mount) {#mount} + + Docker supports three different kinds of mounts, which allow containers to read + from or write to files or directories, either on the host operating system, or + on memory filesystems. These types are _data volumes_ (often referred to simply + as volumes), _bind mounts_, _tmpfs_, and _named pipes_. + + A **bind mount** makes a file or directory on the host available to the + container it is mounted within. A bind mount may be either read-only or + read-write. For example, a container might share its host's DNS information by + means of a bind mount of the host's `/etc/resolv.conf` or a container might + write logs to its host's `/var/log/myContainerLogs` directory. If you use + bind mounts and your host and containers have different notions of permissions, + access controls, or other such details, you will run into portability issues. + + A **named volume** is a mechanism for decoupling persistent data needed by your + container from the image used to create the container and from the host machine. + Named volumes are created and managed by Docker, and a named volume persists + even when no container is currently using it. Data in named volumes can be + shared between a container and the host machine, as well as between multiple + containers. Docker uses a _volume driver_ to create, manage, and mount volumes. + You can back up or restore volumes using Docker commands. + + A **tmpfs** mounts a tmpfs inside a container for volatile data. + + A **npipe** mounts a named pipe from the host into the container. + + Consider a situation where your image starts a lightweight web server. You could + use that image as a base image, copy in your website's HTML files, and package + that into another image. Each time your website changed, you'd need to update + the new image and redeploy all of the containers serving your website. A better + solution is to store the website in a named volume which is attached to each of + your web server containers when they start. To update the website, you just + update the named volume. + + For more information about named volumes, see + [Data Volumes](/storage/volumes/). + + The following table describes options which apply to both bind mounts and named + volumes in a service: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionRequiredDescription
type +

The type of mount, can be either volume, bind, tmpfs, or npipe. Defaults to volume if no type is specified.

+
    +
  • volume: mounts a managed volume + into the container.
  • bind: + bind-mounts a directory or file from the host into the container.
    • +
  • tmpfs: mount a tmpfs in the container
    • +
  • npipe: mounts named pipe from the host into the container (Windows containers only).
    • +
+
src or sourcefor type=bind and type=npipe +
    +
  • + type=volume: src is an optional way to specify the name of the volume (for example, src=my-volume). + If the named volume does not exist, it is automatically created. If no src is specified, the volume is + assigned a random name which is guaranteed to be unique on the host, but may not be unique cluster-wide. + A randomly-named volume has the same lifecycle as its container and is destroyed when the container + is destroyed (which is upon service update, or when scaling or re-balancing the service) +
    • +
  • + type=bind: src is required, and specifies an absolute path to the file or directory to bind-mount + (for example, src=/path/on/host/). An error is produced if the file or directory does not exist. +
    • +
  • + type=tmpfs: src is not supported. +
    • +
+

dst or destination or target

yes +

Mount path inside the container, for example /some/path/in/container/. + If the path does not exist in the container's filesystem, the Engine creates + a directory at the specified location before mounting the volume or bind mount.

+

readonly or ro

 +

The Engine mounts binds and volumes read-write unless readonly option + is given when mounting the bind or volume. Note that setting readonly for a + bind-mount does not make its submounts readonly on the current Linux implementation. See also bind-nonrecursive.

+
    +
  • true or 1 or no value: Mounts the bind or volume read-only.
    • +
  • false or 0: Mounts the bind or volume read-write.
    • +
+
+ + #### Options for Bind Mounts + + The following options can only be used for bind mounts (`type=bind`): + + + + + + + + + + + + + + + + + + + +
OptionDescription
bind-propagation +

See the bind propagation section.

+
consistency +

The consistency requirements for the mount; one of

+
    +
  • default: Equivalent to consistent.
    • +
  • consistent: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.
    • +
  • cached: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.
    • +
  • delegated: 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.
    • +
+
bind-nonrecursive + By default, submounts are recursively bind-mounted as well. However, this behavior can be confusing when a + bind mount is configured with readonly option, because submounts are not mounted as read-only. + Set bind-nonrecursive to disable recursive bind-mount.
+
+ A value is optional:
+
+
    +
  • true or 1: Disables recursive bind-mount.
    • +
  • false or 0: Default if you do not provide a value. Enables recursive bind-mount.
    • +
+
+ + ##### Bind propagation + + Bind propagation refers to whether or not mounts created within a given + bind mount or named volume can be propagated to replicas of that mount. Consider + a mount point `/mnt`, which is also mounted on `/tmp`. The propagation settings + control whether a mount on `/tmp/a` would also be available on `/mnt/a`. Each + propagation setting has a recursive counterpoint. In the case of recursion, + consider that `/tmp/a` is also mounted as `/foo`. The propagation settings + control whether `/mnt/a` and/or `/tmp/a` would exist. + + The `bind-propagation` option defaults to `rprivate` for both bind mounts and + volume mounts, and is only configurable for bind mounts. In other words, named + volumes do not support bind propagation. + + - **`shared`**: Sub-mounts of the original mount are exposed to replica mounts, + and sub-mounts of replica mounts are also propagated to the + original mount. + - **`slave`**: similar to a shared mount, but only in one direction. If the + original mount exposes a sub-mount, the replica mount can see it. + However, if the replica mount exposes a sub-mount, the original + mount cannot see it. + - **`private`**: The mount is private. Sub-mounts within it are not exposed to + replica mounts, and sub-mounts of replica mounts are not + exposed to the original mount. + - **`rshared`**: The same as shared, but the propagation also extends to and from + mount points nested within any of the original or replica mount + points. + - **`rslave`**: The same as `slave`, but the propagation also extends to and from + mount points nested within any of the original or replica mount + points. + - **`rprivate`**: The default. The same as `private`, meaning that no mount points + anywhere within the original or replica mount points propagate + in either direction. + + For more information about bind propagation, see the + [Linux kernel documentation for shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt). + + #### Options for named volumes + + The following options can only be used for named volumes (`type=volume`): + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescription
volume-driver +

Name of the volume-driver plugin to use for the volume. Defaults to + "local", to use the local volume driver to create the volume if the + volume does not exist.

+
volume-label + One or more custom metadata ("labels") to apply to the volume upon + creation. For example, + volume-label=mylabel=hello-world,my-other-label=hello-mars. For more + information about labels, refer to + apply custom metadata. +
volume-nocopy + By default, if you attach an empty volume to a container, and files or + directories already existed at the mount-path in the container (dst), + the Engine copies those files and directories into the volume, allowing + the host to access them. Set volume-nocopy to disable copying files + from the container's filesystem to the volume and mount the empty volume.
+
+ A value is optional:
+
+
    +
  • true or 1: Default if you do not provide a value. Disables copying.
    • +
  • false or 0: Enables copying.
    • +
+
volume-opt + Options specific to a given volume driver, which will be passed to the + driver when creating the volume. Options are provided as a comma-separated + list of key/value pairs, for example, + volume-opt=some-option=some-value,volume-opt=some-other-option=some-other-value. + For available options for a given driver, refer to that driver's + documentation. +
+ + + #### Options for tmpfs + + The following options can only be used for tmpfs mounts (`type=tmpfs`); + + + + + + + + + + + + + + + +
OptionDescription
tmpfs-sizeSize of the tmpfs mount in bytes. Unlimited by default in Linux.
tmpfs-modeFile mode of the tmpfs in octal. (e.g. "700" or "0700".) Defaults to "1777" in Linux.
+ + + #### Differences between "--mount" and "--volume" + + The `--mount` flag supports most options that are supported by the `-v` + or `--volume` flag for `docker run`, with some important exceptions: + + - The `--mount` flag allows you to specify a volume driver and volume driver + options *per volume*, without creating the volumes in advance. In contrast, + `docker run` allows you to specify a single volume driver which is shared + by all volumes, using the `--volume-driver` flag. + + - The `--mount` flag allows you to specify custom metadata ("labels") for a volume, + before the volume is created. + + - When you use `--mount` with `type=bind`, the host-path must refer to an *existing* + path on the host. The path will not be created for you and the service will fail + with an error if the path does not exist. + + - The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags, + which are used for `selinux` labeling. + + #### Create a service using a named volume + + The following example creates a service that uses a named volume: + + ```console + $ docker service create \ + --name my-service \ + --replicas 3 \ + --mount type=volume,source=my-volume,destination=/path/in/container,volume-label="color=red",volume-label="shape=round" \ + nginx:alpine + ``` + + For each replica of the service, the engine requests a volume named "my-volume" + from the default ("local") volume driver where the task is deployed. If the + volume does not exist, the engine creates a new volume and applies the "color" + and "shape" labels. + + When the task is started, the volume is mounted on `/path/in/container/` inside + the container. + + Be aware that the default ("local") volume is a locally scoped volume driver. + This means that depending on where a task is deployed, either that task gets a + *new* volume named "my-volume", or shares the same "my-volume" with other tasks + of the same service. Multiple containers writing to a single shared volume can + cause data corruption if the software running inside the container is not + designed to handle concurrent processes writing to the same location. Also take + into account that containers can be re-scheduled by the Swarm orchestrator and + be deployed on a different node. + + #### Create a service that uses an anonymous volume + + The following command creates a service with three replicas with an anonymous + volume on `/path/in/container`: + + ```console + $ docker service create \ + --name my-service \ + --replicas 3 \ + --mount type=volume,destination=/path/in/container \ + nginx:alpine + ``` + + In this example, no name (`source`) is specified for the volume, so a new volume + is created for each task. This guarantees that each task gets its own volume, + and volumes are not shared between tasks. Anonymous volumes are removed after + the task using them is complete. + + #### Create a service that uses a bind-mounted host directory + + The following example bind-mounts a host directory at `/path/in/container` in + the containers backing the service: + + ```console + $ docker service create \ + --name my-service \ + --mount type=bind,source=/path/on/host,destination=/path/in/container \ + nginx:alpine + ``` + + ### Set service mode (--mode) + + The service mode determines whether this is a _replicated_ service or a _global_ + service. A replicated service runs as many tasks as specified, while a global + service runs on each active node in the swarm. + + The following command creates a global service: + + ```console + $ docker service create \ + --name redis_2 \ + --mode global \ + redis:3.0.6 + ``` + + ### Specify service constraints (--constraint) {#constraint} + + You can limit the set of nodes where a task can be scheduled by defining + constraint expressions. Constraint expressions can either use a _match_ (`==`) + or _exclude_ (`!=`) rule. Multiple constraints find nodes that satisfy every + expression (AND match). Constraints can match node or Docker Engine labels as + follows: + + | node attribute | matches | example | + |----------------------|--------------------------------|-----------------------------------------------| + | `node.id` | Node ID | `node.id==2ivku8v2gvtg4` | + | `node.hostname` | Node hostname | `node.hostname!=node-2` | + | `node.role` | Node role (`manager`/`worker`) | `node.role==manager` | + | `node.platform.os` | Node operating system | `node.platform.os==windows` | + | `node.platform.arch` | Node architecture | `node.platform.arch==x86_64` | + | `node.labels` | User-defined node labels | `node.labels.security==high` | + | `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-22.04` | + + `engine.labels` apply to Docker Engine labels like operating system, drivers, + etc. Swarm administrators add `node.labels` for operational purposes by using + the [`docker node update`](node_update.md) command. + + For example, the following limits tasks for the redis service to nodes where the + node type label equals queue: + + ```console + $ docker service create \ + --name redis_2 \ + --constraint node.platform.os==linux \ + --constraint node.labels.type==queue \ + redis:3.0.6 + ``` + + If the service constraints exclude all nodes in the cluster, a message is printed + that no suitable node is found, but the scheduler will start a reconciliation + loop and deploy the service once a suitable node becomes available. + + In the example below, no node satisfying the constraint was found, causing the + service to not reconcile with the desired state: + + ```console + $ docker service create \ + --name web \ + --constraint node.labels.region==east \ + nginx:alpine + + lx1wrhhpmbbu0wuk0ybws30bc + overall progress: 0 out of 1 tasks + 1/1: no suitable node (scheduling constraints not satisfied on 5 nodes) + + $ docker service ls + ID NAME MODE REPLICAS IMAGE PORTS + b6lww17hrr4e web replicated 0/1 nginx:alpine + ``` + + After adding the `region=east` label to a node in the cluster, the service + reconciles, and the desired number of replicas are deployed: + + ```console + $ docker node update --label-add region=east yswe2dm4c5fdgtsrli1e8ya5l + yswe2dm4c5fdgtsrli1e8ya5l + + $ docker service ls + ID NAME MODE REPLICAS IMAGE PORTS + b6lww17hrr4e web replicated 1/1 nginx:alpine + ``` + + ### Specify service placement preferences (--placement-pref) {#placement-pref} + + You can set up the service to divide tasks evenly over different categories of + nodes. One example of where this can be useful is to balance tasks over a set + of datacenters or availability zones. The example below illustrates this: + + ```console + $ docker service create \ + --replicas 9 \ + --name redis_2 \ + --placement-pref spread=node.labels.datacenter \ + redis:3.0.6 + ``` + + This uses `--placement-pref` with a `spread` strategy (currently the only + supported strategy) to spread tasks evenly over the values of the `datacenter` + node label. In this example, we assume that every node has a `datacenter` node + label attached to it. If there are three different values of this label among + nodes in the swarm, one third of the tasks will be placed on the nodes + associated with each value. This is true even if there are more nodes with one + value than another. For example, consider the following set of nodes: + + - Three nodes with `node.labels.datacenter=east` + - Two nodes with `node.labels.datacenter=south` + - One node with `node.labels.datacenter=west` + + Since we are spreading over the values of the `datacenter` label and the + service has 9 replicas, 3 replicas will end up in each datacenter. There are + three nodes associated with the value `east`, so each one will get one of the + three replicas reserved for this value. There are two nodes with the value + `south`, and the three replicas for this value will be divided between them, + with one receiving two replicas and another receiving just one. Finally, `west` + has a single node that will get all three replicas reserved for `west`. + + If the nodes in one category (for example, those with + `node.labels.datacenter=south`) can't handle their fair share of tasks due to + constraints or resource limitations, the extra tasks will be assigned to other + nodes instead, if possible. + + Both engine labels and node labels are supported by placement preferences. The + example above uses a node label, because the label is referenced with + `node.labels.datacenter`. To spread over the values of an engine label, use + `--placement-pref spread=engine.labels.`. + + It is possible to add multiple placement preferences to a service. This + establishes a hierarchy of preferences, so that tasks are first divided over + one category, and then further divided over additional categories. One example + of where this may be useful is dividing tasks fairly between datacenters, and + then splitting the tasks within each datacenter over a choice of racks. To add + multiple placement preferences, specify the `--placement-pref` flag multiple + times. The order is significant, and the placement preferences will be applied + in the order given when making scheduling decisions. + + The following example sets up a service with multiple placement preferences. + Tasks are spread first over the various datacenters, and then over racks + (as indicated by the respective labels): + + ```console + $ docker service create \ + --replicas 9 \ + --name redis_2 \ + --placement-pref 'spread=node.labels.datacenter' \ + --placement-pref 'spread=node.labels.rack' \ + redis:3.0.6 + ``` + + When updating a service with `docker service update`, `--placement-pref-add` + appends a new placement preference after all existing placement preferences. + `--placement-pref-rm` removes an existing placement preference that matches the + argument. + + ### Specify memory requirements and constraints for a service (--reserve-memory and --limit-memory) {#reserve-memory} + + If your service needs a minimum amount of memory in order to run correctly, + you can use `--reserve-memory` to specify that the service should only be + scheduled on a node with this much memory available to reserve. If no node is + available that meets the criteria, the task is not scheduled, but remains in a + pending state. + + The following example requires that 4GB of memory be available and reservable + on a given node before scheduling the service to run on that node. + + ```console + $ docker service create --reserve-memory=4GB --name=too-big nginx:alpine + ``` + + The managers won't schedule a set of containers on a single node whose combined + reservations exceed the memory available on that node. + + After a task is scheduled and running, `--reserve-memory` does not enforce a + memory limit. Use `--limit-memory` to ensure that a task uses no more than a + given amount of memory on a node. This example limits the amount of memory used + by the task to 4GB. The task will be scheduled even if each of your nodes has + only 2GB of memory, because `--limit-memory` is an upper limit. + + ```console + $ docker service create --limit-memory=4GB --name=too-big nginx:alpine + ``` + + Using `--reserve-memory` and `--limit-memory` does not guarantee that Docker + will not use more memory on your host than you want. For instance, you could + create many services, the sum of whose memory usage could exhaust the available + memory. + + You can prevent this scenario from exhausting the available memory by taking + into account other (non-containerized) software running on the host as well. If + `--reserve-memory` is greater than or equal to `--limit-memory`, Docker won't + schedule a service on a host that doesn't have enough memory. `--limit-memory` + will limit the service's memory to stay within that limit, so if every service + has a memory-reservation and limit set, Docker services will be less likely to + saturate the host. Other non-service containers or applications running directly + on the Docker host could still exhaust memory. + + There is a downside to this approach. Reserving memory also means that you may + not make optimum use of the memory available on the node. Consider a service + that under normal circumstances uses 100MB of memory, but depending on load can + "peak" at 500MB. Reserving 500MB for that service (to guarantee can have 500MB + for those "peaks") results in 400MB of memory being wasted most of the time. + + In short, you can take a more conservative or more flexible approach: + + - **Conservative**: reserve 500MB, and limit to 500MB. Basically you're now + treating the service containers as VMs, and you may be losing a big advantage + containers, which is greater density of services per host. + + - **Flexible**: limit to 500MB in the assumption that if the service requires + more than 500MB, it is malfunctioning. Reserve something between the 100MB + "normal" requirement and the 500MB "peak" requirement". This assumes that when + this service is at "peak", other services or non-container workloads probably + won't be. + + The approach you take depends heavily on the memory-usage patterns of your + workloads. You should test under normal and peak conditions before settling + on an approach. + + On Linux, you can also limit a service's overall memory footprint on a given + host at the level of the host operating system, using `cgroups` or other + relevant operating system tools. + + ### Specify maximum replicas per node (--replicas-max-per-node) {#replicas-max-per-node} + + Use the `--replicas-max-per-node` flag to set the maximum number of replica tasks that can run on a node. + The following command creates a nginx service with 2 replica tasks but only one replica task per node. + + One example where this can be useful is to balance tasks over a set of data centers together with `--placement-pref` + and let `--replicas-max-per-node` setting make sure that replicas are not migrated to another datacenter during + maintenance or datacenter failure. + + The example below illustrates this: + + ```console + $ docker service create \ + --name nginx \ + --replicas 2 \ + --replicas-max-per-node 1 \ + --placement-pref 'spread=node.labels.datacenter' \ + nginx + ``` + + ### Attach a service to an existing network (--network) {#network} + + You can use overlay networks to connect one or more services within the swarm. + + First, create an overlay network on a manager node the docker network create + command: + + ```console + $ docker network create --driver overlay my-network + + etjpu59cykrptrgw0z0hk5snf + ``` + + After you create an overlay network in swarm mode, all manager nodes have + access to the network. + + When you create a service and pass the `--network` flag to attach the service to + the overlay network: + + ```console + $ docker service create \ + --replicas 3 \ + --network my-network \ + --name my-web \ + nginx + + 716thylsndqma81j6kkkb5aus + ``` + + The swarm extends my-network to each node running the service. + + Containers on the same network can access each other using + [service discovery](/network/overlay/#container-discovery). + + Long form syntax of `--network` allows to specify list of aliases and driver options: + `--network name=my-network,alias=web1,driver-opt=field1=value1` + + ### Publish service ports externally to the swarm (-p, --publish) {#publish} + + You can publish service ports to make them available externally to the swarm + 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 + published port and target port separated by a colon (`:`). + + ```console + $ docker service create --name my_web --replicas 3 --publish 8080:80 nginx + ``` + + 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: + + ```console + $ docker service create --name my_web --replicas 3 --publish published=8080,target=80 nginx + ``` + + The options you can specify are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionShort syntaxLong syntaxDescription
published and target port--publish 8080:80--publish published=8080,target=80

+ The target port within the container and the port to map it to on the + nodes, using the routing mesh (ingress) or host-level networking. + More options are available, later in this table. The key-value syntax is + preferred, because it is somewhat self-documenting. +

modeNot possible to set using short syntax.--publish published=8080,target=80,mode=host

+ The mode to use for binding the port, either ingress or host. + Defaults to ingress to use the routing mesh. +

protocol--publish 8080:80/tcp--publish published=8080,target=80,protocol=tcp

+ The protocol to use, tcp , udp, or sctp. Defaults to + tcp. To bind a port for both protocols, specify the -p or + --publish flag twice. +

+ + When you publish a service port using `ingress` mode, the swarm routing mesh + makes the service accessible at the published 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](/engine/swarm/ingress/). + + ### Provide credential specs for managed service accounts (--credentials-spec) {#credentials-spec} + + This option is only used for services using Windows containers. The + `--credential-spec` must be in the format `file://` or + `registry://`. + + When using the `file://` format, the referenced file must be + present in the `CredentialSpecs` subdirectory in the docker data directory, + which defaults to `C:\ProgramData\Docker\` on Windows. For example, + specifying `file://spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`. + + When using the `registry://` format, the credential spec is + read from the Windows registry on the daemon's host. The specified + registry value must be located in: + + HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs + + + ### Create services using templates + + You can use templates for some flags of `service create`, using the syntax + provided by the Go's [text/template](https://golang.org/pkg/text/template/) package. + + The supported flags are the following : + + - `--hostname` + - `--mount` + - `--env` + + Valid placeholders for the Go template are listed below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlaceholderDescription
.Service.IDService ID
.Service.NameService name
.Service.LabelsService labels
.Node.IDNode ID
.Node.HostnameNode Hostname
.Task.IDTask ID
.Task.NameTask name
.Task.SlotTask slot
+ + + #### Template example + + In this example, we are going to set the template of the created containers based on the + service's name, the node's ID and hostname where it sits. + + ```console + $ docker service create \ + --name hosttempl \ + --hostname="{{.Node.Hostname}}-{{.Node.ID}}-{{.Service.Name}}"\ + busybox top + + va8ew30grofhjoychbr6iot8c + + $ docker service ps va8ew30grofhjoychbr6iot8c + + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + wo41w8hg8qan hosttempl.1 busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 2e7a8a9c4da2 Running Running about a minute ago + + $ docker inspect --format="{{.Config.Hostname}}" 2e7a8a9c4da2-wo41w8hg8qanxwjwsg4kxpprj-hosttempl + + x3ti0erg11rjpg64m75kej2mz-hosttempl + ``` + + ### Specify isolation mode on Windows (--isolation) {#isolation} + + By default, tasks scheduled on Windows nodes are run using the default isolation mode + configured for this particular node. To force a specific isolation mode, you can use + the `--isolation` flag: + + ```console + $ docker service create --name myservice --isolation=process microsoft/nanoserver + ``` + + Supported isolation modes on Windows are: + - `default`: use default settings specified on the node running the task + - `process`: use process isolation (Windows server only) + - `hyperv`: use Hyper-V isolation + + ### Create services requesting Generic Resources (--generic-resources) {#generic-resources} + + You can narrow the kind of nodes your task can land on through the using the + `--generic-resource` flag (if the nodes advertise these resources): + + ```console + $ docker service create \ + --name cuda \ + --generic-resource "NVIDIA-GPU=2" \ + --generic-resource "SSD=1" \ + nvidia/cuda + ``` + + ### Running as a job + + Jobs are a special kind of service designed to run an operation to completion + and then stop, as opposed to running long-running daemons. When a Task + belonging to a job exits successfully (return value 0), the Task is marked as + "Completed", and is not run again. + + Jobs are started by using one of two modes, `replicated-job` or `global-job` + + ```console + $ docker service create --name myjob \ + --mode replicated-job \ + bash "true" + ``` + + This command will run one Task, which will, using the `bash` image, execute the + command `true`, which will return 0 and then exit. + + Though Jobs are ultimately a different kind of service, they a couple of + caveats compared to other services: + + - None of the update or rollback configuration options are valid. Jobs can be + updated, but cannot be rolled out or rolled back, making these configuration + options moot. + - Jobs are never restarted on reaching the `Complete` state. This means that + for jobs, setting `--restart-condition` to `any` is the same as setting it to + `on-failure`. + + Jobs are available in both replicated and global modes. + + #### Replicated Jobs + + A replicated job is like a replicated service. Setting the `--replicas` flag + will specify total number of iterations of a job to execute. + + By default, all replicas of a replicated job will launch at once. To control + the total number of replicas that are executing simultaneously at any one time, + the `--max-concurrent` flag can be used: + + ```console + $ docker service create \ + --name mythrottledjob \ + --mode replicated-job \ + --replicas 10 \ + --max-concurrent 2 \ + bash "true" + ``` + + The above command will execute 10 Tasks in total, but only 2 of them will be + run at any given time. + + #### Global Jobs + + Global jobs are like global services, in that a Task is executed once on each node + matching placement constraints. Global jobs are represented by the mode `global-job`. + + Note that after a Global job is created, any new Nodes added to the cluster + will have a Task from that job started on them. The Global Job does not as a + whole have a "done" state, except insofar as every Node meeting the job's + constraints has a Completed task. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_inspect.yaml b/_data/engine-cli/docker_service_inspect.yaml index e0aed46b0c..731eeb3f03 100644 --- a/_data/engine-cli/docker_service_inspect.yaml +++ b/_data/engine-cli/docker_service_inspect.yaml @@ -1,165 +1,184 @@ command: docker service inspect short: Display detailed information on one or more services long: |- - Inspects the specified service. + Inspects the specified service. - By default, this renders all results in a JSON array. If a format is specified, - the given template will be executed for each result. + By default, this renders all results in a JSON array. If a format is specified, + the given template will be executed for each result. - Go's [text/template](https://golang.org/pkg/text/template/) package - describes all the details of the format. + Go's [text/template](https://golang.org/pkg/text/template/) package + describes all the details of the format. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service inspect [OPTIONS] SERVICE [SERVICE...] pname: docker service plink: docker_service.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pretty - value_type: bool - default_value: "false" - description: Print the information in a human friendly format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pretty + value_type: bool + default_value: "false" + description: Print the information in a human friendly format + details_url: '#pretty' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Inspect a service by name or ID + ### Inspect a service by name or ID - You can inspect a service, either by its *name*, or *ID* + You can inspect a service, either by its *name*, or *ID* - For example, given the following service; + For example, given the following service; - ```console - $ docker service ls - ID NAME MODE REPLICAS IMAGE - dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 - ``` + ```console + $ docker service ls + ID NAME MODE REPLICAS IMAGE + dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 + ``` - Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf` - produce the same result: + Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf` + produce the same result: - ```console - $ docker service inspect redis - ``` + ```console + $ docker service inspect redis + ``` - The output is in JSON format, for example: + The output is in JSON format, for example: - ```json - [ - { - "ID": "dmu1ept4cxcfe8k8lhtux3ro3", - "Version": { - "Index": 12 - }, - "CreatedAt": "2016-06-17T18:44:02.558012087Z", - "UpdatedAt": "2016-06-17T18:44:02.558012087Z", - "Spec": { - "Name": "redis", - "TaskTemplate": { - "ContainerSpec": { - "Image": "redis:3.0.6" - }, - "Resources": { - "Limits": {}, - "Reservations": {} - }, - "RestartPolicy": { - "Condition": "any", - "MaxAttempts": 0 - }, - "Placement": {} + ```json + [ + { + "ID": "dmu1ept4cxcfe8k8lhtux3ro3", + "Version": { + "Index": 12 }, - "Mode": { - "Replicated": { - "Replicas": 1 + "CreatedAt": "2016-06-17T18:44:02.558012087Z", + "UpdatedAt": "2016-06-17T18:44:02.558012087Z", + "Spec": { + "Name": "redis", + "TaskTemplate": { + "ContainerSpec": { + "Image": "redis:3.0.6" + }, + "Resources": { + "Limits": {}, + "Reservations": {} + }, + "RestartPolicy": { + "Condition": "any", + "MaxAttempts": 0 + }, + "Placement": {} + }, + "Mode": { + "Replicated": { + "Replicas": 1 + } + }, + "UpdateConfig": {}, + "EndpointSpec": { + "Mode": "vip" } }, - "UpdateConfig": {}, - "EndpointSpec": { - "Mode": "vip" + "Endpoint": { + "Spec": {} } - }, - "Endpoint": { - "Spec": {} } - } - ] - ``` + ] + ``` - ```console - $ docker service inspect dmu1ept4cxcf + ```console + $ docker service inspect dmu1ept4cxcf - [ - { - "ID": "dmu1ept4cxcfe8k8lhtux3ro3", - "Version": { - "Index": 12 - }, - ... - } - ] - ``` + [ + { + "ID": "dmu1ept4cxcfe8k8lhtux3ro3", + "Version": { + "Index": 12 + }, + ... + } + ] + ``` - ### Formatting (--pretty) + ### Formatting (--pretty) {#pretty} - You can print the inspect output in a human-readable format instead of the default - JSON output, by using the `--pretty` option: + You can print the inspect output in a human-readable format instead of the default + JSON output, by using the `--pretty` option: - ```console - $ docker service inspect --pretty frontend + ```console + $ docker service inspect --pretty frontend - ID: c8wgl7q4ndfd52ni6qftkvnnp - Name: frontend - Labels: - - org.example.projectname=demo-app - Service Mode: REPLICATED - Replicas: 5 - Placement: - UpdateConfig: - Parallelism: 0 - On failure: pause - Max failure ratio: 0 - ContainerSpec: - Image: nginx:alpine - Resources: - Networks: net1 - Endpoint Mode: vip - Ports: - PublishedPort = 4443 - Protocol = tcp - TargetPort = 443 - PublishMode = ingress - ``` + ID: c8wgl7q4ndfd52ni6qftkvnnp + Name: frontend + Labels: + - org.example.projectname=demo-app + Service Mode: REPLICATED + Replicas: 5 + Placement: + UpdateConfig: + Parallelism: 0 + On failure: pause + Max failure ratio: 0 + ContainerSpec: + Image: nginx:alpine + Resources: + Networks: net1 + Endpoint Mode: vip + Ports: + PublishedPort = 4443 + Protocol = tcp + TargetPort = 443 + PublishMode = ingress + ``` - You can also use `--format pretty` for the same effect. + You can also use `--format pretty` for the same effect. - ### Format the output (--format) + ### Format the output (--format) {#format} - You can use the --format option to obtain specific information about a - The `--format` option can be used to obtain specific information about a - service. For example, the following command outputs the number of replicas - of the "redis" service. + You can use the --format option to obtain specific information about a + The `--format` option can be used to obtain specific information about a + service. For example, the following command outputs the number of replicas + of the "redis" service. - ```console - $ docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis + ```console + $ docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis - 10 - ``` + 10 + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_logs.yaml b/_data/engine-cli/docker_service_logs.yaml index 29cd8214a6..5454520ffb 100644 --- a/_data/engine-cli/docker_service_logs.yaml +++ b/_data/engine-cli/docker_service_logs.yaml @@ -1,145 +1,165 @@ command: docker service logs short: Fetch the logs of a service or task long: |- - The `docker service logs` command batch-retrieves logs present at the time of execution. + The `docker service logs` command batch-retrieves logs present at the time of execution. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. - The `docker service logs` command can be used with either the name or ID of a - service, or with the ID of a task. If a service is passed, it will display logs - for all of the containers in that service. If a task is passed, it will only - display logs from that particular task. + The `docker service logs` command can be used with either the name or ID of a + service, or with the ID of a task. If a service is passed, it will display logs + for all of the containers in that service. If a task is passed, it will only + display logs from that particular task. - > **Note** - > - > This command is only functional for services that are started with - > the `json-file` or `journald` logging driver. + > **Note** + > + > This command is only functional for services that are started with + > the `json-file` or `journald` logging driver. - For more information about selecting and configuring logging drivers, refer to - [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). + For more information about selecting and configuring logging drivers, refer to + [Configure logging drivers](/config/containers/logging/configure/). - The `docker service logs --follow` command will continue streaming the new output from - the service's `STDOUT` and `STDERR`. + The `docker service logs --follow` command will continue streaming the new output from + the service's `STDOUT` and `STDERR`. - Passing a negative number or a non-integer to `--tail` is invalid and the - value is set to `all` in that case. + Passing a negative number or a non-integer to `--tail` is invalid and the + value is set to `all` in that case. - The `docker service logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants) - , for example `2014-09-16T06:17:46.000000000Z`, to each - log entry. To ensure that the timestamps are aligned the - nano-second part of the timestamp will be padded with zero when necessary. + The `docker service logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants) + , for example `2014-09-16T06:17:46.000000000Z`, to each + log entry. To ensure that the timestamps are aligned the + nano-second part of the timestamp will be padded with zero when necessary. - The `docker service logs --details` command will add on extra attributes, such as - environment variables and labels, provided to `--log-opt` when creating the - service. + The `docker service logs --details` command will add on extra attributes, such as + environment variables and labels, provided to `--log-opt` when creating the + service. - The `--since` option shows only the service logs generated after - a given date. You can specify the date as an RFC 3339 date, a UNIX - timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date - format you may also use RFC3339Nano, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local - timezone on the client will be used if you do not provide either a `Z` or a - `+-00:00` timezone offset at the end of the timestamp. When providing Unix - timestamps enter seconds[.nanoseconds], where seconds is the number of seconds - that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap - seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a - fraction of a second no more than nine digits long. You can combine the - `--since` option with either or both of the `--follow` or `--tail` options. + The `--since` option shows only the service logs generated after + a given date. You can specify the date as an RFC 3339 date, a UNIX + timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date + format you may also use RFC3339Nano, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the client will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. You can combine the + `--since` option with either or both of the `--follow` or `--tail` options. usage: docker service logs [OPTIONS] SERVICE|TASK pname: docker service plink: docker_service.yaml options: -- option: details - value_type: bool - default_value: "false" - description: Show extra details provided to logs - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: follow - shorthand: f - value_type: bool - default_value: "false" - description: Follow log output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-resolve - value_type: bool - default_value: "false" - description: Do not map IDs to Names in output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-task-ids - value_type: bool - default_value: "false" - description: Do not include task IDs in output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Do not truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: raw - value_type: bool - default_value: "false" - description: Do not neatly format logs - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: since - value_type: string - description: | - Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tail - shorthand: "n" - value_type: string - default_value: all - description: Number of lines to show from the end of the logs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: timestamps - shorthand: t - value_type: bool - default_value: "false" - description: Show timestamps - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: details + value_type: bool + default_value: "false" + description: Show extra details provided to logs + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: follow + shorthand: f + value_type: bool + default_value: "false" + description: Follow log output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-resolve + value_type: bool + default_value: "false" + description: Do not map IDs to Names in output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-task-ids + value_type: bool + default_value: "false" + description: Do not include task IDs in output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Do not truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: raw + value_type: bool + default_value: "false" + description: Do not neatly format logs + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: since + value_type: string + description: | + Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tail + shorthand: "n" + value_type: string + default_value: all + description: Number of lines to show from the end of the logs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: timestamps + shorthand: t + value_type: bool + default_value: "false" + description: Show timestamps + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.29" experimental: false diff --git a/_data/engine-cli/docker_service_ls.yaml b/_data/engine-cli/docker_service_ls.yaml index 484bc60b5b..5e1ffdf82c 100644 --- a/_data/engine-cli/docker_service_ls.yaml +++ b/_data/engine-cli/docker_service_ls.yaml @@ -1,165 +1,194 @@ command: docker service ls -aliases: list +aliases: docker service ls, docker service list short: List services long: |- - This command lists services are running in the swarm. + This command lists services are running in the swarm. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service ls [OPTIONS] pname: docker service plink: docker_service.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print services using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - On a manager node: + On a manager node: - ```console - $ docker service ls + ```console + $ docker service ls - ID NAME MODE REPLICAS IMAGE - c8wgl7q4ndfd frontend replicated 5/5 nginx:alpine - dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 - iwe3278osahj mongo global 7/7 mongo:3.3 - hh08h9uu8uwr job replicated-job 1/1 (3/5 completed) nginx:latest - ``` + ID NAME MODE REPLICAS IMAGE + c8wgl7q4ndfd frontend replicated 5/5 nginx:alpine + dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 + iwe3278osahj mongo global 7/7 mongo:3.3 + hh08h9uu8uwr job replicated-job 1/1 (3/5 completed) nginx:latest + ``` - The `REPLICAS` column shows both the *actual* and *desired* number of tasks for - the service. If the service is in `replicated-job` or `global-job`, it will - additionally show the completion status of the job as completed tasks over - total tasks the job will execute. + The `REPLICAS` column shows both the *actual* and *desired* number of tasks for + the service. If the service is in `replicated-job` or `global-job`, it will + additionally show the completion status of the job as completed tasks over + total tasks the job will execute. - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--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 filtering flag (`-f` or `--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: + The currently supported filters are: - * [id](service_ls.md#id) - * [label](service_ls.md#label) - * [mode](service_ls.md#mode) - * [name](service_ls.md#name) + * [id](service_ls.md#id) + * [label](service_ls.md#label) + * [mode](service_ls.md#mode) + * [name](service_ls.md#name) - #### id + #### id - The `id` filter matches all or part of a service's id. + The `id` filter matches all or part of a service's id. - ```console - $ docker service ls -f "id=0bcjw" - ID NAME MODE REPLICAS IMAGE - 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 - ``` + ```console + $ docker service ls -f "id=0bcjw" + ID NAME MODE REPLICAS IMAGE + 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 + ``` - #### label + #### label - The `label` filter matches services based on the presence of a `label` alone or - a `label` and a value. + The `label` filter matches services based on the presence of a `label` alone or + a `label` and a value. - The following filter matches all services with a `project` label regardless of - its value: + The following filter matches all services with a `project` label regardless of + its value: - ```console - $ docker service ls --filter label=project - ID NAME MODE REPLICAS IMAGE - 01sl1rp6nj5u frontend2 replicated 1/1 nginx:alpine - 36xvvwwauej0 frontend replicated 5/5 nginx:alpine - 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 - ``` + ```console + $ docker service ls --filter label=project + ID NAME MODE REPLICAS IMAGE + 01sl1rp6nj5u frontend2 replicated 1/1 nginx:alpine + 36xvvwwauej0 frontend replicated 5/5 nginx:alpine + 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 + ``` - The following filter matches only services with the `project` label with the - `project-a` value. + The following filter matches only services with the `project` label with the + `project-a` value. - ```console - $ docker service ls --filter label=project=project-a - ID NAME MODE REPLICAS IMAGE - 36xvvwwauej0 frontend replicated 5/5 nginx:alpine - 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 - ``` + ```console + $ docker service ls --filter label=project=project-a + ID NAME MODE REPLICAS IMAGE + 36xvvwwauej0 frontend replicated 5/5 nginx:alpine + 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 + ``` - #### mode + #### mode - The `mode` filter matches on the mode (either `replicated` or `global`) of a service. + The `mode` filter matches on the mode (either `replicated` or `global`) of a service. - The following filter matches only `global` services. + The following filter matches only `global` services. - ```console - $ docker service ls --filter mode=global - ID NAME MODE REPLICAS IMAGE - w7y0v2yrn620 top global 1/1 busybox - ``` + ```console + $ docker service ls --filter mode=global + ID NAME MODE REPLICAS IMAGE + w7y0v2yrn620 top global 1/1 busybox + ``` - #### name + #### name - The `name` filter matches on all or part of a service's name. + The `name` filter matches on all or part of a service's name. - The following filter matches services with a name containing `redis`. + The following filter matches services with a name containing `redis`. - ```console - $ docker service ls --filter name=redis - ID NAME MODE REPLICAS IMAGE - 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 - ``` + ```console + $ docker service ls --filter name=redis + ID NAME MODE REPLICAS IMAGE + 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints services output - using a Go template. + The formatting options (`--format`) pretty-prints services output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |-------------|-----------------------------------------| - | `.ID` | Service ID | - | `.Name` | Service name | - | `.Mode` | Service mode (replicated, global) | - | `.Replicas` | Service replicas | - | `.Image` | Service image | - | `.Ports` | Service ports published in ingress mode | + | Placeholder | Description | + |-------------|-----------------------------------------| + | `.ID` | Service ID | + | `.Name` | Service name | + | `.Mode` | Service mode (replicated, global) | + | `.Replicas` | Service replicas | + | `.Image` | Service image | + | `.Ports` | Service ports published in ingress mode | - When using the `--format` option, the `service ls` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `service ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: + The following example uses a template without headers and outputs the + `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: - ```console - $ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}" + ```console + $ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}" - 0zmvwuiu3vue: replicated 10/10 - fm6uf97exkul: global 5/5 - ``` + 0zmvwuiu3vue: replicated 10/10 + fm6uf97exkul: global 5/5 + ``` + + To list all services in JSON format, use the `json` directive: + + ```console + $ docker service ls --format json + {"ID":"ssniordqolsi","Image":"hello-world:latest","Mode":"replicated","Name":"hello","Ports":"","Replicas":"0/1"} + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_ps.yaml b/_data/engine-cli/docker_service_ps.yaml index d2d50beaa4..161e7e69a6 100644 --- a/_data/engine-cli/docker_service_ps.yaml +++ b/_data/engine-cli/docker_service_ps.yaml @@ -1,212 +1,230 @@ command: docker service ps short: List the tasks of one or more services long: |- - Lists the tasks that are running as part of the specified services. + Lists the tasks that are running as part of the specified services. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service ps [OPTIONS] SERVICE [SERVICE...] pname: docker service plink: docker_service.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print tasks using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-resolve - value_type: bool - default_value: "false" - description: Do not map IDs to Names - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Do not truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display task IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: Pretty-print tasks using a Go template + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-resolve + value_type: bool + default_value: "false" + description: Do not map IDs to Names + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Do not truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display task IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### List the tasks that are part of a service + ### List the tasks that are part of a service - The following command shows all the tasks that are part of the `redis` service: + The following command shows all the tasks that are part of the `redis` service: - ```console - $ docker service ps redis + ```console + $ docker service ps redis - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 0qihejybwf1x redis.1 redis:3.0.5 manager1 Running Running 8 seconds - bk658fpbex0d redis.2 redis:3.0.5 worker2 Running Running 9 seconds - 5ls5s5fldaqg redis.3 redis:3.0.5 worker1 Running Running 9 seconds - 8ryt076polmc redis.4 redis:3.0.5 worker1 Running Running 9 seconds - 1x0v8yomsncd redis.5 redis:3.0.5 manager1 Running Running 8 seconds - 71v7je3el7rr redis.6 redis:3.0.5 worker2 Running Running 9 seconds - 4l3zm9b7tfr7 redis.7 redis:3.0.5 worker2 Running Running 9 seconds - 9tfpyixiy2i7 redis.8 redis:3.0.5 worker1 Running Running 9 seconds - 3w1wu13yupln redis.9 redis:3.0.5 manager1 Running Running 8 seconds - 8eaxrb2fqpbn redis.10 redis:3.0.5 manager1 Running Running 8 seconds - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + 0qihejybwf1x redis.1 redis:3.0.5 manager1 Running Running 8 seconds + bk658fpbex0d redis.2 redis:3.0.5 worker2 Running Running 9 seconds + 5ls5s5fldaqg redis.3 redis:3.0.5 worker1 Running Running 9 seconds + 8ryt076polmc redis.4 redis:3.0.5 worker1 Running Running 9 seconds + 1x0v8yomsncd redis.5 redis:3.0.5 manager1 Running Running 8 seconds + 71v7je3el7rr redis.6 redis:3.0.5 worker2 Running Running 9 seconds + 4l3zm9b7tfr7 redis.7 redis:3.0.5 worker2 Running Running 9 seconds + 9tfpyixiy2i7 redis.8 redis:3.0.5 worker1 Running Running 9 seconds + 3w1wu13yupln redis.9 redis:3.0.5 manager1 Running Running 8 seconds + 8eaxrb2fqpbn redis.10 redis:3.0.5 manager1 Running Running 8 seconds + ``` - In addition to _running_ tasks, the output also shows the task history. For - example, after updating the service to use the `redis:3.0.6` image, the output - may look like this: + In addition to _running_ tasks, the output also shows the task history. For + example, after updating the service to use the `redis:3.0.6` image, the output + may look like this: - ```console - $ docker service ps redis + ```console + $ docker service ps redis - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 50qe8lfnxaxk redis.1 redis:3.0.6 manager1 Running Running 6 seconds ago - ky2re9oz86r9 \_ redis.1 redis:3.0.5 manager1 Shutdown Shutdown 8 seconds ago - 3s46te2nzl4i redis.2 redis:3.0.6 worker2 Running Running less than a second ago - nvjljf7rmor4 \_ redis.2 redis:3.0.6 worker2 Shutdown Rejected 23 seconds ago "No such image: redis@sha256:6…" - vtiuz2fpc0yb \_ redis.2 redis:3.0.5 worker2 Shutdown Shutdown 1 second ago - jnarweeha8x4 redis.3 redis:3.0.6 worker1 Running Running 3 seconds ago - vs448yca2nz4 \_ redis.3 redis:3.0.5 worker1 Shutdown Shutdown 4 seconds ago - jf1i992619ir redis.4 redis:3.0.6 worker1 Running Running 10 seconds ago - blkttv7zs8ee \_ redis.4 redis:3.0.5 worker1 Shutdown Shutdown 11 seconds ago - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + 50qe8lfnxaxk redis.1 redis:3.0.6 manager1 Running Running 6 seconds ago + ky2re9oz86r9 \_ redis.1 redis:3.0.5 manager1 Shutdown Shutdown 8 seconds ago + 3s46te2nzl4i redis.2 redis:3.0.6 worker2 Running Running less than a second ago + nvjljf7rmor4 \_ redis.2 redis:3.0.6 worker2 Shutdown Rejected 23 seconds ago "No such image: redis@sha256:6…" + vtiuz2fpc0yb \_ redis.2 redis:3.0.5 worker2 Shutdown Shutdown 1 second ago + jnarweeha8x4 redis.3 redis:3.0.6 worker1 Running Running 3 seconds ago + vs448yca2nz4 \_ redis.3 redis:3.0.5 worker1 Shutdown Shutdown 4 seconds ago + jf1i992619ir redis.4 redis:3.0.6 worker1 Running Running 10 seconds ago + blkttv7zs8ee \_ redis.4 redis:3.0.5 worker1 Shutdown Shutdown 11 seconds ago + ``` - The number of items in the task history is determined by the - `--task-history-limit` option that was set when initializing the swarm. You can - change the task history retention limit using the - [`docker swarm update`](swarm_update.md) command. + The number of items in the task history is determined by the + `--task-history-limit` option that was set when initializing the swarm. You can + change the task history retention limit using the + [`docker swarm update`](swarm_update.md) command. - When deploying a service, docker resolves the digest for the service's - image, and pins the service to that digest. The digest is not shown by - default, but is printed if `--no-trunc` is used. The `--no-trunc` option - also shows the non-truncated task ID, and error-messages, as can be seen below; + When deploying a service, docker resolves the digest for the service's + image, and pins the service to that digest. The digest is not shown by + default, but is printed if `--no-trunc` is used. The `--no-trunc` option + also shows the non-truncated task ID, and error-messages, as can be seen below; - ```console - $ docker service ps --no-trunc redis + ```console + $ docker service ps --no-trunc redis - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 50qe8lfnxaxksi9w2a704wkp7 redis.1 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 manager1 Running Running 5 minutes ago - ky2re9oz86r9556i2szb8a8af \_ redis.1 redis:3.0.5@sha256:f8829e00d95672c48c60f468329d6693c4bdd28d1f057e755f8ba8b40008682e worker2 Shutdown Shutdown 5 minutes ago - bk658fpbex0d57cqcwoe3jthu redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Running Running 5 seconds - nvjljf7rmor4htv7l8rwcx7i7 \_ redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Shutdown Rejected 5 minutes ago "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842" - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + 50qe8lfnxaxksi9w2a704wkp7 redis.1 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 manager1 Running Running 5 minutes ago + ky2re9oz86r9556i2szb8a8af \_ redis.1 redis:3.0.5@sha256:f8829e00d95672c48c60f468329d6693c4bdd28d1f057e755f8ba8b40008682e worker2 Shutdown Shutdown 5 minutes ago + bk658fpbex0d57cqcwoe3jthu redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Running Running 5 seconds + nvjljf7rmor4htv7l8rwcx7i7 \_ redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Shutdown Rejected 5 minutes ago "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842" + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there - is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). - Multiple filter flags are combined as an `OR` filter. For example, - `-f name=redis.1 -f name=redis.7` returns both `redis.1` and `redis.7` tasks. + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there + is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). + Multiple filter flags are combined as an `OR` filter. For example, + `-f name=redis.1 -f name=redis.7` returns both `redis.1` and `redis.7` tasks. - The currently supported filters are: + The currently supported filters are: - * [id](#id) - * [name](#name) - * [node](#node) - * [desired-state](#desired-state) + * [id](#id) + * [name](#name) + * [node](#node) + * [desired-state](#desired-state) - #### id + #### id - The `id` filter matches on all or a prefix of a task's ID. + The `id` filter matches on all or a prefix of a task's ID. - ```console - $ docker service ps -f "id=8" redis + ```console + $ docker service ps -f "id=8" redis - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 8ryt076polmc redis.4 redis:3.0.6 worker1 Running Running 9 seconds - 8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + 8ryt076polmc redis.4 redis:3.0.6 worker1 Running Running 9 seconds + 8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds + ``` - #### name + #### name - The `name` filter matches on task names. + The `name` filter matches on task names. - ```console - $ docker service ps -f "name=redis.1" redis + ```console + $ docker service ps -f "name=redis.1" redis - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - qihejybwf1x5 redis.1 redis:3.0.6 manager1 Running Running 8 seconds - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + qihejybwf1x5 redis.1 redis:3.0.6 manager1 Running Running 8 seconds + ``` - #### node + #### node - The `node` filter matches on a node name or a node ID. + The `node` filter matches on a node name or a node ID. - ```console - $ docker service ps -f "node=manager1" redis + ```console + $ docker service ps -f "node=manager1" redis - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - 0qihejybwf1x redis.1 redis:3.0.6 manager1 Running Running 8 seconds - 1x0v8yomsncd redis.5 redis:3.0.6 manager1 Running Running 8 seconds - 3w1wu13yupln redis.9 redis:3.0.6 manager1 Running Running 8 seconds - 8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + 0qihejybwf1x redis.1 redis:3.0.6 manager1 Running Running 8 seconds + 1x0v8yomsncd redis.5 redis:3.0.6 manager1 Running Running 8 seconds + 3w1wu13yupln redis.9 redis:3.0.6 manager1 Running Running 8 seconds + 8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds + ``` - #### desired-state + #### desired-state - The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`. + The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`. - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints tasks output - using a Go template. + The formatting options (`--format`) pretty-prints tasks output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |-----------------|------------------------------------------------------------------| - | `.ID` | Task ID | - | `.Name` | Task name | - | `.Image` | Task image | - | `.Node` | Node ID | - | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | - | `.CurrentState` | Current state of the task | - | `.Error` | Error | - | `.Ports` | Task published ports | + | Placeholder | Description | + |-----------------|------------------------------------------------------------------| + | `.ID` | Task ID | + | `.Name` | Task name | + | `.Image` | Task image | + | `.Node` | Node ID | + | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | + | `.CurrentState` | Current state of the task | + | `.Error` | Error | + | `.Ports` | Task published ports | - When using the `--format` option, the `service ps` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `service ps` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `Name` and `Image` entries separated by a colon (`:`) for all tasks: + The following example uses a template without headers and outputs the + `Name` and `Image` entries separated by a colon (`:`) for all tasks: - ```console - $ docker service ps --format "{{.Name}}: {{.Image}}" top + ```console + $ docker service ps --format "{{.Name}}: {{.Image}}" top - top.1: busybox - top.2: busybox - top.3: busybox - ``` + top.1: busybox + top.2: busybox + top.3: busybox + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_rm.yaml b/_data/engine-cli/docker_service_rm.yaml index c39d8c3d06..9ff3e7a269 100644 --- a/_data/engine-cli/docker_service_rm.yaml +++ b/_data/engine-cli/docker_service_rm.yaml @@ -1,35 +1,46 @@ command: docker service rm -aliases: remove +aliases: docker service rm, docker service remove short: Remove one or more services long: |- - Removes the specified services from the swarm. + Removes the specified services from the swarm. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service rm SERVICE [SERVICE...] pname: docker service plink: docker_service.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Remove the `redis` service: + Remove the `redis` service: - ```console - $ docker service rm redis + ```console + $ docker service rm redis - redis + redis - $ docker service ls + $ docker service ls - ID NAME MODE REPLICAS IMAGE - ``` + ID NAME MODE REPLICAS IMAGE + ``` - > **Warning** - > - > Unlike `docker rm`, this command does not ask for confirmation before removing - > a running service. + > **Warning** + > + > Unlike `docker rm`, this command does not ask for confirmation before removing + > a running service. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_rollback.yaml b/_data/engine-cli/docker_service_rollback.yaml index 29839e5022..73ae4340f1 100644 --- a/_data/engine-cli/docker_service_rollback.yaml +++ b/_data/engine-cli/docker_service_rollback.yaml @@ -1,89 +1,101 @@ command: docker service rollback short: Revert changes to a service's configuration long: |- - Roll back a specified service to its previous version from the swarm. + Roll back a specified service to its previous version from the swarm. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service rollback [OPTIONS] SERVICE pname: docker service plink: docker_service.yaml options: -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: | - Exit immediately instead of waiting for the service to converge - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress progress output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: Exit immediately instead of waiting for the service to converge + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress progress output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Roll back to the previous version of a service + ### Roll back to the previous version of a service - Use the `docker service rollback` command to roll back to the previous version - of a service. After executing this command, the service is reverted to the - configuration that was in place before the most recent `docker service update` - command. + Use the `docker service rollback` command to roll back to the previous version + of a service. After executing this command, the service is reverted to the + configuration that was in place before the most recent `docker service update` + command. - The following example creates a service with a single replica, updates the - service to use three replicas, and then rolls back the service to the - previous version, having one replica. + The following example creates a service with a single replica, updates the + service to use three replicas, and then rolls back the service to the + previous version, having one replica. - Create a service with a single replica: + Create a service with a single replica: - ```console - $ docker service create --name my-service -p 8080:80 nginx:alpine - ``` + ```console + $ docker service create --name my-service -p 8080:80 nginx:alpine + ``` - Confirm that the service is running with a single replica: + Confirm that the service is running with a single replica: - ```console - $ docker service ls + ```console + $ docker service ls - ID NAME MODE REPLICAS IMAGE PORTS - xbw728mf6q0d my-service replicated 1/1 nginx:alpine *:8080->80/tcp - ``` + ID NAME MODE REPLICAS IMAGE PORTS + xbw728mf6q0d my-service replicated 1/1 nginx:alpine *:8080->80/tcp + ``` - Update the service to use three replicas: + Update the service to use three replicas: - ```console - $ docker service update --replicas=3 my-service + ```console + $ docker service update --replicas=3 my-service - $ docker service ls + $ docker service ls - ID NAME MODE REPLICAS IMAGE PORTS - xbw728mf6q0d my-service replicated 3/3 nginx:alpine *:8080->80/tcp - ``` + ID NAME MODE REPLICAS IMAGE PORTS + xbw728mf6q0d my-service replicated 3/3 nginx:alpine *:8080->80/tcp + ``` - Now roll back the service to its previous version, and confirm it is - running a single replica again: + Now roll back the service to its previous version, and confirm it is + running a single replica again: - ```console - $ docker service rollback my-service + ```console + $ docker service rollback my-service - $ docker service ls + $ docker service ls - ID NAME MODE REPLICAS IMAGE PORTS - xbw728mf6q0d my-service replicated 1/1 nginx:alpine *:8080->80/tcp - ``` + ID NAME MODE REPLICAS IMAGE PORTS + xbw728mf6q0d my-service replicated 1/1 nginx:alpine *:8080->80/tcp + ``` deprecated: false min_api_version: "1.31" experimental: false diff --git a/_data/engine-cli/docker_service_scale.yaml b/_data/engine-cli/docker_service_scale.yaml index 5ab5fe33b6..8ad6234f33 100644 --- a/_data/engine-cli/docker_service_scale.yaml +++ b/_data/engine-cli/docker_service_scale.yaml @@ -1,93 +1,104 @@ command: docker service scale short: Scale one or multiple replicated services long: |- - The scale command enables you to scale one or more replicated services either up - or down to the desired number of replicas. This command cannot be applied on - services which are global mode. The command will return immediately, but the - actual scaling of the service may take some time. To stop all replicas of a - service while keeping the service active in the swarm you can set the scale to 0. + The scale command enables you to scale one or more replicated services either up + or down to the desired number of replicas. This command cannot be applied on + services which are global mode. The command will return immediately, but the + actual scaling of the service may take some time. To stop all replicas of a + service while keeping the service active in the swarm you can set the scale to 0. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service scale SERVICE=REPLICAS [SERVICE=REPLICAS...] pname: docker service plink: docker_service.yaml options: -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: | - Exit immediately instead of waiting for the service to converge - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: Exit immediately instead of waiting for the service to converge + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Scale a single service + ### Scale a single service - The following command scales the "frontend" service to 50 tasks. + The following command scales the "frontend" service to 50 tasks. - ```console - $ docker service scale frontend=50 + ```console + $ docker service scale frontend=50 - frontend scaled to 50 - ``` + frontend scaled to 50 + ``` - The following command tries to scale a global service to 10 tasks and returns an error. + The following command tries to scale a global service to 10 tasks and returns an error. - ```console - $ docker service create --mode global --name backend backend:latest + ```console + $ docker service create --mode global --name backend backend:latest - b4g08uwuairexjub6ome6usqh + b4g08uwuairexjub6ome6usqh - $ docker service scale backend=10 + $ docker service scale backend=10 - backend: scale can only be used with replicated or replicated-job mode - ``` + backend: scale can only be used with replicated or replicated-job mode + ``` - Directly afterwards, run `docker service ls`, to see the actual number of - replicas. + Directly afterwards, run `docker service ls`, to see the actual number of + replicas. - ```console - $ docker service ls --filter name=frontend + ```console + $ docker service ls --filter name=frontend - ID NAME MODE REPLICAS IMAGE - 3pr5mlvu3fh9 frontend replicated 15/50 nginx:alpine - ``` + ID NAME MODE REPLICAS IMAGE + 3pr5mlvu3fh9 frontend replicated 15/50 nginx:alpine + ``` - You can also scale a service using the [`docker service update`](service_update.md) - command. The following commands are equivalent: + You can also scale a service using the [`docker service update`](service_update.md) + command. The following commands are equivalent: - ```console - $ docker service scale frontend=50 - $ docker service update --replicas=50 frontend - ``` + ```console + $ docker service scale frontend=50 + $ docker service update --replicas=50 frontend + ``` - ### Scale multiple services + ### Scale multiple services - The `docker service scale` command allows you to set the desired number of - tasks for multiple services at once. The following example scales both the - backend and frontend services: + The `docker service scale` command allows you to set the desired number of + tasks for multiple services at once. The following example scales both the + backend and frontend services: - ```console - $ docker service scale backend=3 frontend=5 + ```console + $ docker service scale backend=3 frontend=5 - backend scaled to 3 - frontend scaled to 5 + backend scaled to 3 + frontend scaled to 5 - $ docker service ls + $ docker service ls - ID NAME MODE REPLICAS IMAGE - 3pr5mlvu3fh9 frontend replicated 5/5 nginx:alpine - 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 - ``` + ID NAME MODE REPLICAS IMAGE + 3pr5mlvu3fh9 frontend replicated 5/5 nginx:alpine + 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_update.yaml b/_data/engine-cli/docker_service_update.yaml index 41422b558e..6297541388 100644 --- a/_data/engine-cli/docker_service_update.yaml +++ b/_data/engine-cli/docker_service_update.yaml @@ -1,1033 +1,1139 @@ command: docker service update short: Update a service long: |- - Updates a service as described by the specified parameters. The parameters are - the same as [`docker service create`](service_create.md). Refer to the description - there for further information. + Updates a service as described by the specified parameters. The parameters are + the same as [`docker service create`](service_create.md). Refer to the description + there for further information. - Normally, updating a service will only cause the service's tasks to be replaced with new ones if a change to the - service requires recreating the tasks for it to take effect. For example, only changing the - `--update-parallelism` setting will not recreate the tasks, because the individual tasks are not affected by this - setting. However, the `--force` flag will cause the tasks to be recreated anyway. This can be used to perform a - rolling restart without any changes to the service parameters. + Normally, updating a service will only cause the service's tasks to be replaced with new ones if a change to the + service requires recreating the tasks for it to take effect. For example, only changing the + `--update-parallelism` setting will not recreate the tasks, because the individual tasks are not affected by this + setting. However, the `--force` flag will cause the tasks to be recreated anyway. This can be used to perform a + rolling restart without any changes to the service parameters. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker service update [OPTIONS] SERVICE pname: docker service plink: docker_service.yaml options: -- option: args - value_type: command - description: Service command args - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-add - value_type: list - description: Add Linux capabilities - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cap-drop - value_type: list - description: Drop Linux capabilities - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: config-add - value_type: config - description: Add or update a config file on a service - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: config-rm - value_type: list - description: Remove a configuration file - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: constraint-add - value_type: list - description: Add or update a placement constraint - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: constraint-rm - value_type: list - description: Remove a constraint - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: container-label-add - value_type: list - description: Add or update a container label - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: container-label-rm - value_type: list - description: Remove a container label by its key - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: credential-spec - value_type: credential-spec - description: Credential spec for managed service account (Windows only) - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: | - Exit immediately instead of waiting for the service to converge - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-add - value_type: list - description: Add or update a custom DNS server - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-option-add - value_type: list - description: Add or update a DNS option - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-option-rm - value_type: list - description: Remove a DNS option - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-rm - value_type: list - description: Remove a custom DNS server - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-search-add - value_type: list - description: Add or update a custom DNS search domain - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dns-search-rm - value_type: list - description: Remove a DNS search domain - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: endpoint-mode - value_type: string - description: Endpoint mode (vip or dnsrr) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: entrypoint - value_type: command - description: Overwrite the default ENTRYPOINT of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-add - value_type: list - description: Add or update an environment variable - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: env-rm - value_type: list - description: Remove an environment variable - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force - value_type: bool - default_value: "false" - description: Force update even if no changes require it - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: generic-resource-add - value_type: list - description: Add a Generic resource - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: generic-resource-rm - value_type: list - description: Remove a Generic resource - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: group-add - value_type: list - description: Add an additional supplementary user group to the container - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: group-rm - value_type: list - description: | - Remove a previously added supplementary user group from the container - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-cmd - value_type: string - description: Command to run to check health - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-interval - value_type: duration - description: Time between running the check (ms|s|m|h) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-retries - value_type: int - default_value: "0" - description: Consecutive failures needed to report unhealthy - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-start-period - value_type: duration - description: | - Start period for the container to initialize before counting retries towards unstable (ms|s|m|h) - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: health-timeout - value_type: duration - description: Maximum time to allow one check to run (ms|s|m|h) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: host-add - value_type: list - description: Add a custom host-to-IP mapping (host:ip) - deprecated: false - min_api_version: "1.32" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: host-rm - value_type: list - description: Remove a custom host-to-IP mapping (host:ip) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: hostname - value_type: string - description: Container hostname - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: image - value_type: string - description: Service image tag - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: init - value_type: bool - default_value: "false" - description: | - Use an init inside each service container to forward signals and reap processes - deprecated: false - min_api_version: "1.37" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Service container isolation mode - deprecated: false - min_api_version: "1.35" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label-add - value_type: list - description: Add or update a service label - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label-rm - value_type: list - description: Remove a label by its key - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: limit-cpu - value_type: decimal - description: Limit CPUs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: limit-memory - value_type: bytes - default_value: "0" - description: Limit Memory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: limit-pids - value_type: int64 - default_value: "0" - description: Limit maximum number of processes (default 0 = unlimited) - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: true -- option: log-driver - value_type: string - description: Logging driver for service - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: log-opt - value_type: list - description: Logging driver options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: max-concurrent - value_type: uint - description: | - Number of job tasks to run concurrently (default equal to --replicas) - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mount-add - value_type: mount - description: Add or update a mount on a service - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: mount-rm - value_type: list - description: Remove a mount by its target path - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network-add - value_type: network - description: Add a network - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network-rm - value_type: list - description: Remove a network - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-healthcheck - value_type: bool - default_value: "false" - description: Disable any container-specified HEALTHCHECK - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-resolve-image - value_type: bool - default_value: "false" - description: | - Do not query the registry to resolve image digest and supported platforms - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: placement-pref-add - value_type: pref - description: Add a placement preference - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: placement-pref-rm - value_type: pref - description: Remove a placement preference - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish-add - value_type: port - description: Add or update a published port - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: publish-rm - value_type: port - description: Remove a published port by its target port - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress progress output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: read-only - value_type: bool - default_value: "false" - description: Mount the container's root filesystem as read only - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: replicas - value_type: uint - description: Number of tasks - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: replicas-max-per-node - value_type: uint64 - default_value: "0" - description: Maximum number of tasks per node (default 0 = unlimited) - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: reserve-cpu - value_type: decimal - description: Reserve CPUs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: reserve-memory - value_type: bytes - default_value: "0" - description: Reserve Memory - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart-condition - value_type: string - description: Restart when condition is met ("none"|"on-failure"|"any") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart-delay - value_type: duration - description: Delay between restart attempts (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart-max-attempts - value_type: uint - description: Maximum number of restarts before giving up - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart-window - value_type: duration - description: Window used to evaluate the restart policy (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback - value_type: bool - default_value: "false" - description: Rollback to previous specification - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-delay - value_type: duration - default_value: 0s - description: Delay between task rollbacks (ns|us|ms|s|m|h) - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-failure-action - value_type: string - description: Action on rollback failure ("pause"|"continue") - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-max-failure-ratio - value_type: float - default_value: "0" - description: Failure rate to tolerate during a rollback - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-monitor - value_type: duration - default_value: 0s - description: | - Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-order - value_type: string - description: Rollback order ("start-first"|"stop-first") - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rollback-parallelism - value_type: uint64 - default_value: "0" - description: | - Maximum number of tasks rolled back simultaneously (0 to roll back all at once) - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: secret-add - value_type: secret - description: Add or update a secret on a service - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: secret-rm - value_type: list - description: Remove a secret - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-grace-period - value_type: duration - description: | - Time to wait before force killing a container (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: stop-signal - value_type: string - description: Signal to stop the container - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sysctl-add - value_type: list - description: Add or update a Sysctl option - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: sysctl-rm - value_type: list - description: Remove a Sysctl option - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tty - shorthand: t - value_type: bool - default_value: "false" - description: Allocate a pseudo-TTY - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit-add - value_type: ulimit - default_value: '[]' - description: Add or update a ulimit option - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit-rm - value_type: list - description: Remove a ulimit option - deprecated: false - min_api_version: "1.41" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-delay - value_type: duration - default_value: 0s - description: Delay between updates (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-failure-action - value_type: string - description: Action on update failure ("pause"|"continue"|"rollback") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-max-failure-ratio - value_type: float - default_value: "0" - description: Failure rate to tolerate during an update - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-monitor - value_type: duration - default_value: 0s - description: | - Duration after each task update to monitor for failure (ns|us|ms|s|m|h) - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-order - value_type: string - description: Update order ("start-first"|"stop-first") - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: update-parallelism - value_type: uint64 - default_value: "0" - description: | - Maximum number of tasks updated simultaneously (0 to update all at once) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: user - shorthand: u - value_type: string - description: 'Username or UID (format: [:])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: with-registry-auth - value_type: bool - default_value: "false" - description: Send registry authentication details to swarm agents - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: workdir - shorthand: w - value_type: string - description: Working directory inside the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: args + value_type: command + description: Service command args + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-add + value_type: list + description: Add Linux capabilities + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cap-drop + value_type: list + description: Drop Linux capabilities + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: config-add + value_type: config + description: Add or update a config file on a service + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: config-rm + value_type: list + description: Remove a configuration file + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: constraint-add + value_type: list + description: Add or update a placement constraint + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: constraint-rm + value_type: list + description: Remove a constraint + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: container-label-add + value_type: list + description: Add or update a container label + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: container-label-rm + value_type: list + description: Remove a container label by its key + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: credential-spec + value_type: credential-spec + description: Credential spec for managed service account (Windows only) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: Exit immediately instead of waiting for the service to converge + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-add + value_type: list + description: Add or update a custom DNS server + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-option-add + value_type: list + description: Add or update a DNS option + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-option-rm + value_type: list + description: Remove a DNS option + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-rm + value_type: list + description: Remove a custom DNS server + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-search-add + value_type: list + description: Add or update a custom DNS search domain + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dns-search-rm + value_type: list + description: Remove a DNS search domain + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: endpoint-mode + value_type: string + description: Endpoint mode (vip or dnsrr) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: entrypoint + value_type: command + description: Overwrite the default ENTRYPOINT of the image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-add + value_type: list + description: Add or update an environment variable + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env-rm + value_type: list + description: Remove an environment variable + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + value_type: bool + default_value: "false" + description: Force update even if no changes require it + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: generic-resource-add + value_type: list + description: Add a Generic resource + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: generic-resource-rm + value_type: list + description: Remove a Generic resource + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: group-add + value_type: list + description: Add an additional supplementary user group to the container + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: group-rm + value_type: list + description: | + Remove a previously added supplementary user group from the container + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-cmd + value_type: string + description: Command to run to check health + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-interval + value_type: duration + description: Time between running the check (ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-retries + value_type: int + default_value: "0" + description: Consecutive failures needed to report unhealthy + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-start-period + value_type: duration + description: | + Start period for the container to initialize before counting retries towards unstable (ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: health-timeout + value_type: duration + description: Maximum time to allow one check to run (ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: host-add + value_type: list + description: Add a custom host-to-IP mapping (`host:ip`) + deprecated: false + hidden: false + min_api_version: "1.32" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: host-rm + value_type: list + description: Remove a custom host-to-IP mapping (`host:ip`) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: hostname + value_type: string + description: Container hostname + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: image + value_type: string + description: Service image tag + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: init + value_type: bool + default_value: "false" + description: | + Use an init inside each service container to forward signals and reap processes + deprecated: false + hidden: false + min_api_version: "1.37" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: isolation + value_type: string + description: Service container isolation mode + details_url: '#isolation' + deprecated: false + hidden: false + min_api_version: "1.35" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label-add + value_type: list + description: Add or update a service label + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: label-rm + value_type: list + description: Remove a label by its key + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: limit-cpu + value_type: decimal + description: Limit CPUs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: limit-memory + value_type: bytes + default_value: "0" + description: Limit Memory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: limit-pids + value_type: int64 + default_value: "0" + description: Limit maximum number of processes (default 0 = unlimited) + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-driver + value_type: string + description: Logging driver for service + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: log-opt + value_type: list + description: Logging driver options + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: max-concurrent + value_type: uint + description: | + Number of job tasks to run concurrently (default equal to --replicas) + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mount-add + value_type: mount + description: Add or update a mount on a service + details_url: '#mount-add' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mount-rm + value_type: list + description: Remove a mount by its target path + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network-add + value_type: network + description: Add a network + details_url: '#network-add' + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: network-rm + value_type: list + description: Remove a network + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-healthcheck + value_type: bool + default_value: "false" + description: Disable any container-specified HEALTHCHECK + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-resolve-image + value_type: bool + default_value: "false" + description: | + Do not query the registry to resolve image digest and supported platforms + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: placement-pref-add + value_type: pref + description: Add a placement preference + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: placement-pref-rm + value_type: pref + description: Remove a placement preference + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish-add + value_type: port + description: Add or update a published port + details_url: '#publish-add' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: publish-rm + value_type: port + description: Remove a published port by its target port + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress progress output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: read-only + value_type: bool + default_value: "false" + description: Mount the container's root filesystem as read only + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: replicas + value_type: uint + description: Number of tasks + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: replicas-max-per-node + value_type: uint64 + default_value: "0" + description: Maximum number of tasks per node (default 0 = unlimited) + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: reserve-cpu + value_type: decimal + description: Reserve CPUs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: reserve-memory + value_type: bytes + default_value: "0" + description: Reserve Memory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart-condition + value_type: string + description: Restart when condition is met (`none`, `on-failure`, `any`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart-delay + value_type: duration + description: Delay between restart attempts (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart-max-attempts + value_type: uint + description: Maximum number of restarts before giving up + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart-window + value_type: duration + description: Window used to evaluate the restart policy (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback + value_type: bool + default_value: "false" + description: Rollback to previous specification + details_url: '#rollback' + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-delay + value_type: duration + default_value: 0s + description: Delay between task rollbacks (ns|us|ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-failure-action + value_type: string + description: Action on rollback failure (`pause`, `continue`) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-max-failure-ratio + value_type: float + default_value: "0" + description: Failure rate to tolerate during a rollback + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-monitor + value_type: duration + default_value: 0s + description: | + Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-order + value_type: string + description: Rollback order (`start-first`, `stop-first`) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rollback-parallelism + value_type: uint64 + default_value: "0" + description: | + Maximum number of tasks rolled back simultaneously (0 to roll back all at once) + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: secret-add + value_type: secret + description: Add or update a secret on a service + details_url: '#secret-add' + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: secret-rm + value_type: list + description: Remove a secret + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-grace-period + value_type: duration + description: Time to wait before force killing a container (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stop-signal + value_type: string + description: Signal to stop the container + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sysctl-add + value_type: list + description: Add or update a Sysctl option + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: sysctl-rm + value_type: list + description: Remove a Sysctl option + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tty + shorthand: t + value_type: bool + default_value: "false" + description: Allocate a pseudo-TTY + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit-add + value_type: ulimit + default_value: '[]' + description: Add or update a ulimit option + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ulimit-rm + value_type: list + description: Remove a ulimit option + deprecated: false + hidden: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-delay + value_type: duration + default_value: 0s + description: Delay between updates (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-failure-action + value_type: string + description: Action on update failure (`pause`, `continue`, `rollback`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-max-failure-ratio + value_type: float + default_value: "0" + description: Failure rate to tolerate during an update + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-monitor + value_type: duration + default_value: 0s + description: | + Duration after each task update to monitor for failure (ns|us|ms|s|m|h) + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-order + value_type: string + description: Update order (`start-first`, `stop-first`) + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: update-parallelism + value_type: uint64 + default_value: "0" + description: | + Maximum number of tasks updated simultaneously (0 to update all at once) + details_url: '#update-parallelism' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: user + shorthand: u + value_type: string + description: 'Username or UID (format: [:])' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: with-registry-auth + value_type: bool + default_value: "false" + description: Send registry authentication details to swarm agents + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workdir + shorthand: w + value_type: string + description: Working directory inside the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Update a service + ### Update a service - ```console - $ docker service update --limit-cpu 2 redis - ``` + ```console + $ docker service update --limit-cpu 2 redis + ``` - ### Perform a rolling restart with no parameter changes + ### Perform a rolling restart with no parameter changes {#update-parallelism} - ```console - $ docker service update --force --update-parallelism 1 --update-delay 30s redis - ``` + ```console + $ docker service update --force --update-parallelism 1 --update-delay 30s redis + ``` - In this example, the `--force` flag causes the service's tasks to be shut down - and replaced with new ones even though none of the other parameters would - normally cause that to happen. The `--update-parallelism 1` setting ensures - that only one task is replaced at a time (this is the default behavior). The - `--update-delay 30s` setting introduces a 30 second delay between tasks, so - that the rolling restart happens gradually. + In this example, the `--force` flag causes the service's tasks to be shut down + and replaced with new ones even though none of the other parameters would + normally cause that to happen. The `--update-parallelism 1` setting ensures + that only one task is replaced at a time (this is the default behavior). The + `--update-delay 30s` setting introduces a 30 second delay between tasks, so + that the rolling restart happens gradually. - ### Add or remove mounts (--mount-add, --mount-rm) + ### Add or remove mounts (--mount-add, --mount-rm) {#mount-add} - Use the `--mount-add` or `--mount-rm` options add or remove a service's bind mounts - or volumes. + Use the `--mount-add` or `--mount-rm` options add or remove a service's bind mounts + or volumes. - The following example creates a service which mounts the `test-data` volume to - `/somewhere`. The next step updates the service to also mount the `other-volume` - volume to `/somewhere-else`volume, The last step unmounts the `/somewhere` mount - point, effectively removing the `test-data` volume. Each command returns the - service name. + The following example creates a service which mounts the `test-data` volume to + `/somewhere`. The next step updates the service to also mount the `other-volume` + volume to `/somewhere-else`volume, The last step unmounts the `/somewhere` mount + point, effectively removing the `test-data` volume. Each command returns the + service name. - - The `--mount-add` flag takes the same parameters as the `--mount` flag on - `service create`. Refer to the [volumes and bind mounts](service_create.md#mount) - section in the `service create` reference for details. + - The `--mount-add` flag takes the same parameters as the `--mount` flag on + `service create`. Refer to the [volumes and bind mounts](service_create.md#mount) + section in the `service create` reference for details. - - The `--mount-rm` flag takes the `target` path of the mount. + - The `--mount-rm` flag takes the `target` path of the mount. - ```console - $ docker service create \ - --name=myservice \ - --mount type=volume,source=test-data,target=/somewhere \ - nginx:alpine + ```console + $ docker service create \ + --name=myservice \ + --mount type=volume,source=test-data,target=/somewhere \ + nginx:alpine - myservice + myservice - $ docker service update \ - --mount-add type=volume,source=other-volume,target=/somewhere-else \ + $ docker service update \ + --mount-add type=volume,source=other-volume,target=/somewhere-else \ + myservice + + myservice + + $ docker service update --mount-rm /somewhere myservice + + myservice + ``` + + ### Add or remove published service ports (--publish-add, --publish-rm) {#publish-add} + + Use the `--publish-add` or `--publish-rm` flags to add or remove a published + port for a service. You can use the short or long syntax discussed in the + [docker service create](service_create.md#publish) + reference. + + The following example adds a published service port to an existing service. + + ```console + $ docker service update \ + --publish-add published=8080,target=80 \ myservice + ``` - myservice + ### Add or remove network (--network-add, --network-rm) {#network-add} - $ docker service update --mount-rm /somewhere myservice + Use the `--network-add` or `--network-rm` flags to add or remove a network for + a service. You can use the short or long syntax discussed in the + [docker service create](service_create.md#network) + reference. - myservice - ``` + The following example adds a new alias name to an existing service already connected to network my-network: - ### Add or remove published service ports (--publish-add, --publish-rm) + ```console + $ docker service update \ + --network-rm my-network \ + --network-add name=my-network,alias=web1 \ + myservice + ``` - Use the `--publish-add` or `--publish-rm` flags to add or remove a published - port for a service. You can use the short or long syntax discussed in the - [docker service create](service_create.md#publish) - reference. + ### Roll back to the previous version of a service (--rollback) {#rollback} - The following example adds a published service port to an existing service. + Use the `--rollback` option to roll back to the previous version of the service. - ```console - $ docker service update \ - --publish-add published=8080,target=80 \ - myservice - ``` + This will revert the service to the configuration that was in place before the most recent `docker service update` command. - ### Add or remove network (--network-add, --network-rm) + The following example updates the number of replicas for the service from 4 to 5, and then rolls back to the previous configuration. - Use the `--network-add` or `--network-rm` flags to add or remove a network for - a service. You can use the short or long syntax discussed in the - [docker service create](service_create.md#network) - reference. + ```console + $ docker service update --replicas=5 web - The following example adds a new alias name to an existing service already connected to network my-network: - - ```console - $ docker service update \ - --network-rm my-network \ - --network-add name=my-network,alias=web1 \ - myservice - ``` - - ### Roll back to the previous version of a service (--rollback) - - Use the `--rollback` option to roll back to the previous version of the service. - - This will revert the service to the configuration that was in place before the most recent `docker service update` command. - - The following example updates the number of replicas for the service from 4 to 5, and then rolls back to the previous configuration. - - ```console - $ docker service update --replicas=5 web - - web - - $ docker service ls - - ID NAME MODE REPLICAS IMAGE - 80bvrzp6vxf3 web replicated 0/5 nginx:alpine - - ``` - - Roll back the `web` service... - - ```console - $ docker service update --rollback web - - web - - $ docker service ls - - ID NAME MODE REPLICAS IMAGE - 80bvrzp6vxf3 web replicated 0/4 nginx:alpine - - ``` - - Other options can be combined with `--rollback` as well, for example, `--update-delay 0s` to execute the rollback without a delay between tasks: - - ```console - $ docker service update \ - --rollback \ - --update-delay 0s web - web + $ docker service ls - ``` + ID NAME MODE REPLICAS IMAGE + 80bvrzp6vxf3 web replicated 0/5 nginx:alpine - Services can also be set up to roll back to the previous version automatically - when an update fails. To set up a service for automatic rollback, use - `--update-failure-action=rollback`. A rollback will be triggered if the fraction - of the tasks which failed to update successfully exceeds the value given with - `--update-max-failure-ratio`. + ``` - The rate, parallelism, and other parameters of a rollback operation are - determined by the values passed with the following flags: + Roll back the `web` service... - - `--rollback-delay` - - `--rollback-failure-action` - - `--rollback-max-failure-ratio` - - `--rollback-monitor` - - `--rollback-parallelism` + ```console + $ docker service update --rollback web - For example, a service set up with `--update-parallelism 1 --rollback-parallelism 3` - will update one task at a time during a normal update, but during a rollback, 3 - tasks at a time will get rolled back. These rollback parameters are respected both - during automatic rollbacks and for rollbacks initiated manually using `--rollback`. + web - ### Add or remove secrets (--secret-add, --secret-rm) + $ docker service ls - Use the `--secret-add` or `--secret-rm` options add or remove a service's - secrets. + ID NAME MODE REPLICAS IMAGE + 80bvrzp6vxf3 web replicated 0/4 nginx:alpine - The following example adds a secret named `ssh-2` and removes `ssh-1`: + ``` - ```console - $ docker service update \ - --secret-add source=ssh-2,target=ssh-2 \ - --secret-rm ssh-1 \ - myservice - ``` + Other options can be combined with `--rollback` as well, for example, `--update-delay 0s` to execute the rollback without a delay between tasks: - ### Update services using templates + ```console + $ docker service update \ + --rollback \ + --update-delay 0s + web - Some flags of `service update` support the use of templating. - See [`service create`](service_create.md#create-services-using-templates) for the reference. + web + + ``` + + Services can also be set up to roll back to the previous version automatically + when an update fails. To set up a service for automatic rollback, use + `--update-failure-action=rollback`. A rollback will be triggered if the fraction + of the tasks which failed to update successfully exceeds the value given with + `--update-max-failure-ratio`. + + The rate, parallelism, and other parameters of a rollback operation are + determined by the values passed with the following flags: + + - `--rollback-delay` + - `--rollback-failure-action` + - `--rollback-max-failure-ratio` + - `--rollback-monitor` + - `--rollback-parallelism` + + For example, a service set up with `--update-parallelism 1 --rollback-parallelism 3` + will update one task at a time during a normal update, but during a rollback, 3 + tasks at a time will get rolled back. These rollback parameters are respected both + during automatic rollbacks and for rollbacks initiated manually using `--rollback`. + + ### Add or remove secrets (--secret-add, --secret-rm) {#secret-add} + + Use the `--secret-add` or `--secret-rm` options add or remove a service's + secrets. + + The following example adds a secret named `ssh-2` and removes `ssh-1`: + + ```console + $ docker service update \ + --secret-add source=ssh-2,target=ssh-2 \ + --secret-rm ssh-1 \ + myservice + ``` + + ### Update services using templates + + Some flags of `service update` support the use of templating. + See [`service create`](service_create.md#create-services-using-templates) for the reference. - ### Specify isolation mode on Windows (--isolation) + ### Specify isolation mode on Windows (--isolation) {#isolation} - `service update` supports the same `--isolation` flag as `service create` - See [`service create`](service_create.md) for the reference. + `service update` supports the same `--isolation` flag as `service create` + See [`service create`](service_create.md) for the reference. - ### Updating Jobs + ### Updating Jobs - When a service is created as a job, by setting its mode to `replicated-job` or - to `global-job` when doing `service create`, options for updating it are - limited. + When a service is created as a job, by setting its mode to `replicated-job` or + to `global-job` when doing `service create`, options for updating it are + limited. - Updating a Job immediately stops any Tasks that are in progress. The operation - creates a new set of Tasks for the job and effectively resets its completion - status. If any Tasks were running before the update, they are stopped, and new - Tasks are created. + Updating a Job immediately stops any Tasks that are in progress. The operation + creates a new set of Tasks for the job and effectively resets its completion + status. If any Tasks were running before the update, they are stopped, and new + Tasks are created. - Jobs cannot be rolled out or rolled back. None of the flags for configuring - update or rollback settings are valid with job modes. + Jobs cannot be rolled out or rolled back. None of the flags for configuring + update or rollback settings are valid with job modes. - To run a job again with the same parameters that it was run previously, it can - be force updated with the `--force` flag. + To run a job again with the same parameters that it was run previously, it can + be force updated with the `--force` flag. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_stack.yaml b/_data/engine-cli/docker_stack.yaml index dee0895bfa..91b88a1ab7 100644 --- a/_data/engine-cli/docker_stack.yaml +++ b/_data/engine-cli/docker_stack.yaml @@ -1,42 +1,48 @@ command: docker stack -short: Manage Docker stacks +short: Manage Swarm stacks long: Manage stacks. usage: docker stack [OPTIONS] pname: docker plink: docker.yaml cname: -- docker stack deploy -- docker stack ls -- docker stack ps -- docker stack rm -- docker stack services + - docker stack config + - docker stack deploy + - docker stack ls + - docker stack ps + - docker stack rm + - docker stack services clink: -- docker_stack_deploy.yaml -- docker_stack_ls.yaml -- docker_stack_ps.yaml -- docker_stack_rm.yaml -- docker_stack_services.yaml + - docker_stack_config.yaml + - docker_stack_deploy.yaml + - docker_stack_ls.yaml + - docker_stack_ps.yaml + - docker_stack_rm.yaml + - docker_stack_services.yaml options: -- option: kubeconfig - value_type: string - description: Kubernetes config file - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: orchestrator - value_type: string - description: Orchestrator to use (swarm|kubernetes|all) - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: orchestrator + value_type: string + description: Orchestrator to use (swarm|all) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false -swarm: false +swarm: true diff --git a/_data/engine-cli/docker_stack_config.yaml b/_data/engine-cli/docker_stack_config.yaml new file mode 100644 index 0000000000..fad8e01132 --- /dev/null +++ b/_data/engine-cli/docker_stack_config.yaml @@ -0,0 +1,90 @@ +command: docker stack config +short: Outputs the final config file, after doing merges and interpolations +long: | + Outputs the final Compose file, after doing the merges and interpolations of the input Compose files. +usage: docker stack config [OPTIONS] +pname: docker stack +plink: docker_stack.yaml +options: + - option: compose-file + shorthand: c + value_type: stringSlice + default_value: '[]' + description: Path to a Compose file, or `-` to read from stdin + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: skip-interpolation + value_type: bool + default_value: "false" + description: Skip interpolation and output only merged config + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: orchestrator + value_type: string + description: Orchestrator to use (swarm|all) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +examples: |- + The following command outputs the result of the merge and interpolation of two Compose files. + + ```bash + $ docker stack config --compose-file docker-compose.yml --compose-file docker-compose.prod.yml + ``` + + The Compose file can also be provided as standard input with `--compose-file -`: + + ```bash + $ cat docker-compose.yml | docker stack config --compose-file - + ``` + + ### Skipping interpolation + + In some cases, it might be useful to skip interpolation of environment variables. + For example, when you want to pipe the output of this command back to `stack deploy`. + + If you have a regex for a redirect route in an environment variable for your webserver you would use two `$` signs to prevent `stack deploy` from interpolating `${1}`. + + ```bash + service: webserver + environment: + REDIRECT_REGEX=http://host/redirect/$${1} + ``` + + With interpolation, the `stack config` command will replace the environment variable in the Compose file + with `REDIRECT_REGEX=http://host/redirect/${1}`, but then when piping it back to the `stack deploy` + command it will be interpolated again and result in undefined behavior. + That is why, when piping the output back to `stack deploy` one should always prefer the `--skip-interpolation` option. + + ``` + $ docker stack config --compose-file web.yml --compose-file web.prod.yml --skip-interpolation | docker stack deploy --compose-file - + ``` +deprecated: false +min_api_version: "1.25" +experimental: false +experimentalcli: false +kubernetes: false +swarm: true + diff --git a/_data/engine-cli/docker_stack_deploy.yaml b/_data/engine-cli/docker_stack_deploy.yaml index 64a86f8edc..03093288c7 100644 --- a/_data/engine-cli/docker_stack_deploy.yaml +++ b/_data/engine-cli/docker_stack_deploy.yaml @@ -1,158 +1,158 @@ command: docker stack deploy -aliases: up +aliases: docker stack deploy, docker stack up short: Deploy a new stack or update an existing stack long: |- - Create and update a stack from a `compose` file on the swarm. + Create and update a stack from a `compose` file on the swarm. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker stack deploy [OPTIONS] STACK pname: docker stack plink: docker_stack.yaml options: -- option: compose-file - shorthand: c - value_type: stringSlice - default_value: '[]' - description: Path to a Compose file, or "-" to read from stdin - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: namespace - value_type: string - description: Kubernetes namespace to use - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: prune - value_type: bool - default_value: "false" - description: Prune services that are no longer referenced - deprecated: false - min_api_version: "1.27" - experimental: false - experimentalcli: false - kubernetes: false - swarm: true -- option: resolve-image - value_type: string - default_value: always - description: | - Query the registry to resolve image digest and supported platforms ("always"|"changed"|"never") - deprecated: false - min_api_version: "1.30" - experimental: false - experimentalcli: false - kubernetes: false - swarm: true -- option: with-registry-auth - value_type: bool - default_value: "false" - description: Send registry authentication details to Swarm agents - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: true + - option: compose-file + shorthand: c + value_type: stringSlice + default_value: '[]' + description: Path to a Compose file, or `-` to read from stdin + details_url: '#compose-file' + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: prune + value_type: bool + default_value: "false" + description: Prune services that are no longer referenced + deprecated: false + hidden: false + min_api_version: "1.27" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: resolve-image + value_type: string + default_value: always + description: | + Query the registry to resolve image digest and supported platforms (`always`, `changed`, `never`) + deprecated: false + hidden: false + min_api_version: "1.30" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: with-registry-auth + value_type: bool + default_value: "false" + description: Send registry authentication details to Swarm agents + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false inherited_options: -- option: kubeconfig - value_type: string - description: Kubernetes config file - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: orchestrator - value_type: string - description: Orchestrator to use (swarm|kubernetes|all) - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: orchestrator + value_type: string + description: Orchestrator to use (swarm|all) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Compose file (--compose-file) + ### Compose file (--compose-file) {#compose-file} - The `deploy` command supports compose file version `3.0` and above. + The `deploy` command supports compose file version `3.0` and above. - ```console - $ docker stack deploy --compose-file docker-compose.yml vossibility + ```console + $ docker stack deploy --compose-file docker-compose.yml vossibility - Ignoring unsupported options: links + 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 - ``` + 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 + ``` - The Compose file can also be provided as standard input with `--compose-file -`: + The Compose file can also be provided as standard input with `--compose-file -`: - ```console - $ cat docker-compose.yml | docker stack deploy --compose-file - vossibility + ```console + $ cat docker-compose.yml | docker stack deploy --compose-file - vossibility - Ignoring unsupported options: links + 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 - ``` + 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 + ``` - If your configuration is split between multiple Compose files, e.g. a base - configuration and environment-specific overrides, you can provide multiple - `--compose-file` flags. + If your configuration is split between multiple Compose files, e.g. a base + configuration and environment-specific overrides, you can provide multiple + `--compose-file` flags. - ```console - $ docker stack deploy --compose-file docker-compose.yml -c docker-compose.prod.yml vossibility + ```console + $ docker stack deploy --compose-file docker-compose.yml -c docker-compose.prod.yml vossibility - Ignoring unsupported options: links + 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 - ``` + 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: + You can verify that the services were correctly created: - ```console - $ docker service ls + ```console + $ docker service ls - ID NAME MODE REPLICAS IMAGE - 29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 - 4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 - 4tjx9biia6fs vossibility_elasticsearch replicated 1/1 elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa - 7563uuzr9eys vossibility_kibana replicated 1/1 kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03 - 9gc5m4met4he vossibility_logstash replicated 1/1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe - axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba - ``` + ID NAME MODE REPLICAS IMAGE + 29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 + 4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 + 4tjx9biia6fs vossibility_elasticsearch replicated 1/1 elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa + 7563uuzr9eys vossibility_kibana replicated 1/1 kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03 + 9gc5m4met4he vossibility_logstash replicated 1/1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe + axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba + ``` deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false -swarm: false +swarm: true diff --git a/_data/engine-cli/docker_stack_ls.yaml b/_data/engine-cli/docker_stack_ls.yaml index 41e59e0fe2..85d3e4f3eb 100644 --- a/_data/engine-cli/docker_stack_ls.yaml +++ b/_data/engine-cli/docker_stack_ls.yaml @@ -1,102 +1,102 @@ command: docker stack ls -aliases: list +aliases: docker stack ls, docker stack list short: List stacks long: |- - Lists the stacks. + Lists the stacks. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker stack ls [OPTIONS] pname: docker stack plink: docker_stack.yaml options: -- option: all-namespaces - value_type: bool - default_value: "false" - description: List stacks from all Kubernetes namespaces - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: format - value_type: string - description: Pretty-print stacks using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: namespace - value_type: stringSlice - default_value: '[]' - description: Kubernetes namespaces to use - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false inherited_options: -- option: kubeconfig - value_type: string - description: Kubernetes config file - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: orchestrator - value_type: string - description: Orchestrator to use (swarm|kubernetes|all) - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: orchestrator + value_type: string + description: Orchestrator to use (swarm|all) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following command shows all stacks and some additional information: + The following command shows all stacks and some additional information: - ```console - $ docker stack ls + ```console + $ docker stack ls - ID SERVICES ORCHESTRATOR - myapp 2 Kubernetes - vossibility-stack 6 Swarm - ``` + ID SERVICES ORCHESTRATOR + myapp 2 Kubernetes + vossibility-stack 6 Swarm + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) pretty-prints stacks using a Go template. + The formatting option (`--format`) pretty-prints stacks using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |-----------------|--------------------| - | `.Name` | Stack name | - | `.Services` | Number of services | - | `.Orchestrator` | Orchestrator name | - | `.Namespace` | Namespace | + | Placeholder | Description | + |-----------------|--------------------| + | `.Name` | Stack name | + | `.Services` | Number of services | + | `.Orchestrator` | Orchestrator name | + | `.Namespace` | Namespace | - When using the `--format` option, the `stack ls` command either outputs - the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `stack ls` command either outputs + the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `Name` and `Services` entries separated by a colon (`:`) for all stacks: + The following example uses a template without headers and outputs the + `Name` and `Services` entries separated by a colon (`:`) for all stacks: - ```console - $ docker stack ls --format "{{.Name}}: {{.Services}}" - web-server: 1 - web-cache: 4 - ``` + ```console + $ docker stack ls --format "{{.Name}}: {{.Services}}" + web-server: 1 + web-cache: 4 + ``` + + To list all stacks in JSON format, use the `json` directive: + + ```console + $ docker stack ls --format json + {"Name":"myapp","Namespace":"","Orchestrator":"Swarm","Services":"3"} + ``` deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false -swarm: false +swarm: true diff --git a/_data/engine-cli/docker_stack_ps.yaml b/_data/engine-cli/docker_stack_ps.yaml index 74f19ef86a..f939f232b6 100644 --- a/_data/engine-cli/docker_stack_ps.yaml +++ b/_data/engine-cli/docker_stack_ps.yaml @@ -1,286 +1,305 @@ command: docker stack ps short: List the tasks in the stack long: |- - Lists the tasks that are running as part of the specified stack. + Lists the tasks that are running as part of the specified stack. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker stack ps [OPTIONS] STACK pname: docker stack plink: docker_stack.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print tasks using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: namespace - value_type: string - description: Kubernetes namespace to use - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: no-resolve - value_type: bool - default_value: "false" - description: Do not map IDs to Names - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Do not truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display task IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-resolve + value_type: bool + default_value: "false" + description: Do not map IDs to Names + details_url: '#no-resolve' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Do not truncate output + details_url: '#no-trunc' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display task IDs + details_url: '#quiet' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false inherited_options: -- option: kubeconfig - value_type: string - description: Kubernetes config file - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: orchestrator - value_type: string - description: Orchestrator to use (swarm|kubernetes|all) - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: orchestrator + value_type: string + description: Orchestrator to use (swarm|all) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### List the tasks that are part of a stack + ### List the tasks that are part of a stack - The following command shows all the tasks that are part of the `voting` stack: + The following command shows all the tasks that are part of the `voting` stack: - ```console - $ docker stack ps voting + ```console + $ docker stack ps voting - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - xim5bcqtgk1b voting_worker.1 dockersamples/examplevotingapp_worker:latest node2 Running Running 2 minutes ago - q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 2 minutes ago - rx5yo0866nfx voting_vote.1 dockersamples/examplevotingapp_vote:before node3 Running Running 2 minutes ago - tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 2 minutes ago - w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 3 minutes ago - 6jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 2 minutes ago - kqgdmededccb voting_vote.2 dockersamples/examplevotingapp_vote:before node2 Running Running 2 minutes ago - t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 3 minutes ago - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + xim5bcqtgk1b voting_worker.1 dockersamples/examplevotingapp_worker:latest node2 Running Running 2 minutes ago + q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 2 minutes ago + rx5yo0866nfx voting_vote.1 dockersamples/examplevotingapp_vote:before node3 Running Running 2 minutes ago + tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 2 minutes ago + w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 3 minutes ago + 6jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 2 minutes ago + kqgdmededccb voting_vote.2 dockersamples/examplevotingapp_vote:before node2 Running Running 2 minutes ago + t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 3 minutes ago + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there - is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). - Multiple filter flags are combined as an `OR` filter. For example, - `-f name=redis.1 -f name=redis.7` returns both `redis.1` and `redis.7` tasks. + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there + is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). + Multiple filter flags are combined as an `OR` filter. For example, + `-f name=redis.1 -f name=redis.7` returns both `redis.1` and `redis.7` tasks. - The currently supported filters are: + The currently supported filters are: - * [id](#id) - * [name](#name) - * [node](#node) - * [desired-state](#desired-state) + * [id](#id) + * [name](#name) + * [node](#node) + * [desired-state](#desired-state) - #### id + #### id - The `id` filter matches on all or a prefix of a task's ID. + The `id` filter matches on all or a prefix of a task's ID. - ```console - $ docker stack ps -f "id=t" voting + ```console + $ docker stack ps -f "id=t" voting - ID NAME IMAGE NODE DESIRED STATE CURRENTSTATE ERROR PORTS - tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 14 minutes ago - t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 14 minutes ago - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENTSTATE ERROR PORTS + tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 14 minutes ago + t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 14 minutes ago + ``` - #### name + #### name - The `name` filter matches on task names. + The `name` filter matches on task names. - ```console - $ docker stack ps -f "name=voting_redis" voting + ```console + $ docker stack ps -f "name=voting_redis" voting - ID NAME IMAGE NODE DESIRED STATE CURRENTSTATE ERROR PORTS - w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 17 minutes ago - t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 17 minutes ago - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENTSTATE ERROR PORTS + w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 17 minutes ago + t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 17 minutes ago + ``` - #### node + #### node - The `node` filter matches on a node name or a node ID. + The `node` filter matches on a node name or a node ID. - ```console - $ docker stack ps -f "node=node1" voting + ```console + $ docker stack ps -f "node=node1" voting - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 18 minutes ago - tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 18 minutes ago - 6jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 18 minutes ago - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 18 minutes ago + tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 18 minutes ago + 6jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 18 minutes ago + ``` - #### desired-state + #### desired-state - The `desired-state` filter can take the values `running`, `shutdown`, `ready` or `accepted`. + The `desired-state` filter can take the values `running`, `shutdown`, `ready` or `accepted`. - ```console - $ docker stack ps -f "desired-state=running" voting + ```console + $ docker stack ps -f "desired-state=running" voting - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - xim5bcqtgk1b voting_worker.1 dockersamples/examplevotingapp_worker:latest node2 Running Running 21 minutes ago - q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 21 minutes ago - rx5yo0866nfx voting_vote.1 dockersamples/examplevotingapp_vote:before node3 Running Running 21 minutes ago - tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 21 minutes ago - w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 21 minutes ago - 6jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 21 minutes ago - kqgdmededccb voting_vote.2 dockersamples/examplevotingapp_vote:before node2 Running Running 21 minutes ago - t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 21 minutes ago - ``` + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + xim5bcqtgk1b voting_worker.1 dockersamples/examplevotingapp_worker:latest node2 Running Running 21 minutes ago + q7yik0ks1in6 voting_result.1 dockersamples/examplevotingapp_result:before node1 Running Running 21 minutes ago + rx5yo0866nfx voting_vote.1 dockersamples/examplevotingapp_vote:before node3 Running Running 21 minutes ago + tz6j82jnwrx7 voting_db.1 postgres:9.4 node1 Running Running 21 minutes ago + w48spazhbmxc voting_redis.1 redis:alpine node2 Running Running 21 minutes ago + 6jj1m02freg1 voting_visualizer.1 dockersamples/visualizer:stable node1 Running Running 21 minutes ago + kqgdmededccb voting_vote.2 dockersamples/examplevotingapp_vote:before node2 Running Running 21 minutes ago + t72q3z038jeh voting_redis.2 redis:alpine node3 Running Running 21 minutes ago + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints tasks output using a Go template. + The formatting options (`--format`) pretty-prints tasks output using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |-----------------|------------------------------------------------------------------| - | `.ID` | Task ID | - | `.Name` | Task name | - | `.Image` | Task image | - | `.Node` | Node ID | - | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | - | `.CurrentState` | Current state of the task | - | `.Error` | Error | - | `.Ports` | Task published ports | + | Placeholder | Description | + |-----------------|------------------------------------------------------------------| + | `.ID` | Task ID | + | `.Name` | Task name | + | `.Image` | Task image | + | `.Node` | Node ID | + | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | + | `.CurrentState` | Current state of the task | + | `.Error` | Error | + | `.Ports` | Task published ports | - When using the `--format` option, the `stack ps` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `stack ps` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `Name` and `Image` entries separated by a colon (`:`) for all tasks: + The following example uses a template without headers and outputs the + `Name` and `Image` entries separated by a colon (`:`) for all tasks: - ```console - $ docker stack ps --format "{{.Name}}: {{.Image}}" voting + ```console + $ docker stack ps --format "{{.Name}}: {{.Image}}" voting - voting_worker.1: dockersamples/examplevotingapp_worker:latest - voting_result.1: dockersamples/examplevotingapp_result:before - voting_vote.1: dockersamples/examplevotingapp_vote:before - voting_db.1: postgres:9.4 - voting_redis.1: redis:alpine - voting_visualizer.1: dockersamples/visualizer:stable - voting_vote.2: dockersamples/examplevotingapp_vote:before - voting_redis.2: redis:alpine - ``` + voting_worker.1: dockersamples/examplevotingapp_worker:latest + voting_result.1: dockersamples/examplevotingapp_result:before + voting_vote.1: dockersamples/examplevotingapp_vote:before + voting_db.1: postgres:9.4 + voting_redis.1: redis:alpine + voting_visualizer.1: dockersamples/visualizer:stable + voting_vote.2: dockersamples/examplevotingapp_vote:before + voting_redis.2: redis:alpine + ``` - ### Do not map IDs to Names (--no-resolve) + To list all tasks in JSON format, use the `json` directive: + ```console + $ docker stack ps --format json myapp + {"CurrentState":"Preparing 23 seconds ago","DesiredState":"Running","Error":"","ID":"2ufjubh79tn0","Image":"localstack/localstack:latest","Name":"myapp_localstack.1","Node":"docker-desktop","Ports":""} + {"CurrentState":"Running 20 seconds ago","DesiredState":"Running","Error":"","ID":"roee387ngf5r","Image":"redis:6.0.9-alpine3.12","Name":"myapp_redis.1","Node":"docker-desktop","Ports":""} + {"CurrentState":"Preparing 13 seconds ago","DesiredState":"Running","Error":"","ID":"yte68ouq7glh","Image":"postgres:13.2-alpine","Name":"myapp_repos-db.1","Node":"docker-desktop","Ports":""} + ``` - The `--no-resolve` option shows IDs for task name, without mapping IDs to Names. + ### Do not map IDs to Names (--no-resolve) {#no-resolve} - ```console - $ docker stack ps --no-resolve voting + The `--no-resolve` option shows IDs for task name, without mapping IDs to Names. - ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS - xim5bcqtgk1b 10z9fjfqzsxnezo4hb81p8mqg.1 dockersamples/examplevotingapp_worker:latest qaqt4nrzo775jrx6detglho01 Running Running 30 minutes ago - q7yik0ks1in6 hbxltua1na7mgqjnidldv5m65.1 dockersamples/examplevotingapp_result:before mxpaef1tlh23s052erw88a4w5 Running Running 30 minutes ago - rx5yo0866nfx qyprtqw1g5nrki557i974ou1d.1 dockersamples/examplevotingapp_vote:before kanqcxfajd1r16wlnqcblobmm Running Running 31 minutes ago - tz6j82jnwrx7 122f0xxngg17z52be7xspa72x.1 postgres:9.4 mxpaef1tlh23s052erw88a4w5 Running Running 31 minutes ago - w48spazhbmxc tg61x8myx563ueo3urmn1ic6m.1 redis:alpine qaqt4nrzo775jrx6detglho01 Running Running 31 minutes ago - 6jj1m02freg1 8cqlyi444kzd3panjb7edh26v.1 dockersamples/visualizer:stable mxpaef1tlh23s052erw88a4w5 Running Running 31 minutes ago - kqgdmededccb qyprtqw1g5nrki557i974ou1d.2 dockersamples/examplevotingapp_vote:before qaqt4nrzo775jrx6detglho01 Running Running 31 minutes ago - t72q3z038jeh tg61x8myx563ueo3urmn1ic6m.2 redis:alpine kanqcxfajd1r16wlnqcblobmm Running Running 31 minutes ago - ``` + ```console + $ docker stack ps --no-resolve voting - ### Do not truncate output (--no-trunc) + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS + xim5bcqtgk1b 10z9fjfqzsxnezo4hb81p8mqg.1 dockersamples/examplevotingapp_worker:latest qaqt4nrzo775jrx6detglho01 Running Running 30 minutes ago + q7yik0ks1in6 hbxltua1na7mgqjnidldv5m65.1 dockersamples/examplevotingapp_result:before mxpaef1tlh23s052erw88a4w5 Running Running 30 minutes ago + rx5yo0866nfx qyprtqw1g5nrki557i974ou1d.1 dockersamples/examplevotingapp_vote:before kanqcxfajd1r16wlnqcblobmm Running Running 31 minutes ago + tz6j82jnwrx7 122f0xxngg17z52be7xspa72x.1 postgres:9.4 mxpaef1tlh23s052erw88a4w5 Running Running 31 minutes ago + w48spazhbmxc tg61x8myx563ueo3urmn1ic6m.1 redis:alpine qaqt4nrzo775jrx6detglho01 Running Running 31 minutes ago + 6jj1m02freg1 8cqlyi444kzd3panjb7edh26v.1 dockersamples/visualizer:stable mxpaef1tlh23s052erw88a4w5 Running Running 31 minutes ago + kqgdmededccb qyprtqw1g5nrki557i974ou1d.2 dockersamples/examplevotingapp_vote:before qaqt4nrzo775jrx6detglho01 Running Running 31 minutes ago + t72q3z038jeh tg61x8myx563ueo3urmn1ic6m.2 redis:alpine kanqcxfajd1r16wlnqcblobmm Running Running 31 minutes ago + ``` - When deploying a service, docker resolves the digest for the service's - image, and pins the service to that digest. The digest is not shown by - default, but is printed if `--no-trunc` is used. The `--no-trunc` option - also shows the non-truncated task IDs, and error-messages, as can be seen below: + ### Do not truncate output (--no-trunc) {#no-trunc} - ```console - $ docker stack ps --no-trunc voting + When deploying a service, docker resolves the digest for the service's + image, and pins the service to that digest. The digest is not shown by + default, but is printed if `--no-trunc` is used. The `--no-trunc` option + also shows the non-truncated task IDs, and error-messages, as can be seen below: - ID NAME IMAGE NODE DESIRED STATE CURREN STATE ERROR PORTS - xim5bcqtgk1bxqz91jzo4a1s5 voting_worker.1 dockersamples/examplevotingapp_worker:latest@sha256:3e4ddf59c15f432280a2c0679c4fc5a2ee5a797023c8ef0d3baf7b1385e9fed node2 Running Runnin 32 minutes ago - q7yik0ks1in6kv32gg6y6yjf7 voting_result.1 dockersamples/examplevotingapp_result:before@sha256:83b56996e930c292a6ae5187fda84dd6568a19d97cdb933720be15c757b7463 node1 Running Runnin 32 minutes ago - rx5yo0866nfxc58zf4irsss6n voting_vote.1 dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6 node3 Running Runnin 32 minutes ago - tz6j82jnwrx7n2offljp3mn03 voting_db.1 postgres:9.4@sha256:6046af499eae34d2074c0b53f9a8b404716d415e4a03e68bc1d2f8064f2b027 node1 Running Runnin 32 minutes ago - w48spazhbmxcmbjfi54gs7x90 voting_redis.1 redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7 node2 Running Runnin 32 minutes ago - 6jj1m02freg1n3z9n1evrzsbl voting_visualizer.1 dockersamples/visualizer:stable@sha256:f924ad66c8e94b10baaf7bdb9cd491ef4e982a1d048a56a17e02bf5945401e5 node1 Running Runnin 32 minutes ago - kqgdmededccbhz2wuc0e9hx7g voting_vote.2 dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6 node2 Running Runnin 32 minutes ago - t72q3z038jehe1wbh9gdum076 voting_redis.2 redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7 node3 Running Runnin 32 minutes ago - ``` + ```console + $ docker stack ps --no-trunc voting - ### Only display task IDs (-q, --quiet) + ID NAME IMAGE NODE DESIRED STATE CURREN STATE ERROR PORTS + xim5bcqtgk1bxqz91jzo4a1s5 voting_worker.1 dockersamples/examplevotingapp_worker:latest@sha256:3e4ddf59c15f432280a2c0679c4fc5a2ee5a797023c8ef0d3baf7b1385e9fed node2 Running Runnin 32 minutes ago + q7yik0ks1in6kv32gg6y6yjf7 voting_result.1 dockersamples/examplevotingapp_result:before@sha256:83b56996e930c292a6ae5187fda84dd6568a19d97cdb933720be15c757b7463 node1 Running Runnin 32 minutes ago + rx5yo0866nfxc58zf4irsss6n voting_vote.1 dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6 node3 Running Runnin 32 minutes ago + tz6j82jnwrx7n2offljp3mn03 voting_db.1 postgres:9.4@sha256:6046af499eae34d2074c0b53f9a8b404716d415e4a03e68bc1d2f8064f2b027 node1 Running Runnin 32 minutes ago + w48spazhbmxcmbjfi54gs7x90 voting_redis.1 redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7 node2 Running Runnin 32 minutes ago + 6jj1m02freg1n3z9n1evrzsbl voting_visualizer.1 dockersamples/visualizer:stable@sha256:f924ad66c8e94b10baaf7bdb9cd491ef4e982a1d048a56a17e02bf5945401e5 node1 Running Runnin 32 minutes ago + kqgdmededccbhz2wuc0e9hx7g voting_vote.2 dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6 node2 Running Runnin 32 minutes ago + t72q3z038jehe1wbh9gdum076 voting_redis.2 redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7 node3 Running Runnin 32 minutes ago + ``` - The `-q ` or `--quiet` option only shows IDs of the tasks in the stack. - This example outputs all task IDs of the "voting" stack; + ### Only display task IDs (-q, --quiet) {#quiet} - ```console - $ docker stack ps -q voting - xim5bcqtgk1b - q7yik0ks1in6 - rx5yo0866nfx - tz6j82jnwrx7 - w48spazhbmxc - 6jj1m02freg1 - kqgdmededccb - t72q3z038jeh - ``` + The `-q ` or `--quiet` option only shows IDs of the tasks in the stack. + This example outputs all task IDs of the "voting" stack; - This option can be used to perform batch operations. For example, you can use - the task IDs as input for other commands, such as `docker inspect`. The - following example inspects all tasks of the "voting" stack; + ```console + $ docker stack ps -q voting + xim5bcqtgk1b + q7yik0ks1in6 + rx5yo0866nfx + tz6j82jnwrx7 + w48spazhbmxc + 6jj1m02freg1 + kqgdmededccb + t72q3z038jeh + ``` - ```console - $ docker inspect $(docker stack ps -q voting) + This option can be used to perform batch operations. For example, you can use + the task IDs as input for other commands, such as `docker inspect`. The + following example inspects all tasks of the "voting" stack; - [ - { - "ID": "xim5bcqtgk1b1gk0krq1", - "Version": { - <...> - ``` + ```console + $ docker inspect $(docker stack ps -q voting) + + [ + { + "ID": "xim5bcqtgk1b1gk0krq1", + "Version": { + <...> + ``` deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false -swarm: false +swarm: true diff --git a/_data/engine-cli/docker_stack_rm.yaml b/_data/engine-cli/docker_stack_rm.yaml index e23cc96909..189589da38 100644 --- a/_data/engine-cli/docker_stack_rm.yaml +++ b/_data/engine-cli/docker_stack_rm.yaml @@ -1,84 +1,80 @@ command: docker stack rm -aliases: remove, down +aliases: docker stack rm, docker stack remove, docker stack down short: Remove one or more stacks long: |- - Remove the stack from the swarm. + Remove the stack from the swarm. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker stack rm [OPTIONS] STACK [STACK...] pname: docker stack plink: docker_stack.yaml -options: -- option: namespace - value_type: string - description: Kubernetes namespace to use - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false inherited_options: -- option: kubeconfig - value_type: string - description: Kubernetes config file - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: orchestrator - value_type: string - description: Orchestrator to use (swarm|kubernetes|all) - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: orchestrator + value_type: string + description: Orchestrator to use (swarm|all) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Remove a stack + ### Remove a stack - This will remove the stack with the name `myapp`. Services, networks, and secrets associated with the stack will be removed. + This will remove the stack with the name `myapp`. Services, networks, and secrets + associated with the stack will be removed. - ```console - $ docker stack rm myapp + ```console + $ docker stack rm myapp - Removing service myapp_redis - Removing service myapp_web - Removing service myapp_lb - Removing network myapp_default - Removing network myapp_frontend - ``` + Removing service myapp_redis + Removing service myapp_web + Removing service myapp_lb + Removing network myapp_default + Removing network myapp_frontend + ``` - ### Remove multiple stacks + ### Remove multiple stacks - This will remove all the specified stacks, `myapp` and `vossibility`. Services, networks, and secrets associated with all the specified stacks will be removed. + This will remove all the specified stacks, `myapp` and `vossibility`. Services, + networks, and secrets associated with all the specified stacks will be removed. - ```console - $ docker stack rm myapp vossibility + ```console + $ docker stack rm myapp vossibility - Removing service myapp_redis - Removing service myapp_web - Removing service myapp_lb - Removing network myapp_default - Removing network myapp_frontend - Removing service vossibility_nsqd - Removing service vossibility_logstash - Removing service vossibility_elasticsearch - Removing service vossibility_kibana - Removing service vossibility_ghollector - Removing service vossibility_lookupd - Removing network vossibility_default - Removing network vossibility_vossibility - ``` + Removing service myapp_redis + Removing service myapp_web + Removing service myapp_lb + Removing network myapp_default + Removing network myapp_frontend + Removing service vossibility_nsqd + Removing service vossibility_logstash + Removing service vossibility_elasticsearch + Removing service vossibility_kibana + Removing service vossibility_ghollector + Removing service vossibility_lookupd + Removing network vossibility_default + Removing network vossibility_vossibility + ``` deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false -swarm: false +swarm: true diff --git a/_data/engine-cli/docker_stack_services.yaml b/_data/engine-cli/docker_stack_services.yaml index 718e09f9a2..871e1ccfb7 100644 --- a/_data/engine-cli/docker_stack_services.yaml +++ b/_data/engine-cli/docker_stack_services.yaml @@ -1,150 +1,156 @@ command: docker stack services short: List the services in the stack long: |- - Lists the services that are running as part of the specified stack. + Lists the services that are running as part of the specified stack. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker stack services [OPTIONS] STACK pname: docker stack plink: docker_stack.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print services using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: namespace - value_type: string - description: Kubernetes namespace to use - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display IDs - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display IDs + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false inherited_options: -- option: kubeconfig - value_type: string - description: Kubernetes config file - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false -- option: orchestrator - value_type: string - description: Orchestrator to use (swarm|kubernetes|all) - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: orchestrator + value_type: string + description: Orchestrator to use (swarm|all) + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following command shows all services in the `myapp` stack: + The following command shows all services in the `myapp` stack: - ```console - $ docker stack services myapp + ```console + $ docker stack services myapp - ID NAME REPLICAS IMAGE COMMAND - 7be5ei6sqeye myapp_web 1/1 nginx@sha256:23f809e7fd5952e7d5be065b4d3643fbbceccd349d537b62a123ef2201bc886f - dn7m7nhhfb9y myapp_db 1/1 mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539 - ``` + ID NAME REPLICAS IMAGE COMMAND + 7be5ei6sqeye myapp_web 1/1 nginx@sha256:23f809e7fd5952e7d5be065b4d3643fbbceccd349d537b62a123ef2201bc886f + dn7m7nhhfb9y myapp_db 1/1 mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539 + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there - is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). - Multiple filter flags are combined as an `OR` filter. + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there + is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). + Multiple filter flags are combined as an `OR` filter. - The following command shows both the `web` and `db` services: + The following command shows both the `web` and `db` services: - ```console - $ docker stack services --filter name=myapp_web --filter name=myapp_db myapp + ```console + $ docker stack services --filter name=myapp_web --filter name=myapp_db myapp - ID NAME REPLICAS IMAGE COMMAND - 7be5ei6sqeye myapp_web 1/1 nginx@sha256:23f809e7fd5952e7d5be065b4d3643fbbceccd349d537b62a123ef2201bc886f - dn7m7nhhfb9y myapp_db 1/1 mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539 - ``` + ID NAME REPLICAS IMAGE COMMAND + 7be5ei6sqeye myapp_web 1/1 nginx@sha256:23f809e7fd5952e7d5be065b4d3643fbbceccd349d537b62a123ef2201bc886f + dn7m7nhhfb9y myapp_db 1/1 mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539 + ``` - The currently supported filters are: + The currently supported filters are: - * id / ID (`--filter id=7be5ei6sqeye`, or `--filter ID=7be5ei6sqeye`) - * Swarm: supported - * Kubernetes: not supported - * label (`--filter label=key=value`) - * Swarm: supported - * Kubernetes: supported - * mode (`--filter mode=replicated`, or `--filter mode=global`) - * Swarm: not supported - * Kubernetes: supported - * name (`--filter name=myapp_web`) - * Swarm: supported - * Kubernetes: supported - * node (`--filter node=mynode`) - * Swarm: not supported - * Kubernetes: supported - * service (`--filter service=web`) - * Swarm: not supported - * Kubernetes: supported + * id / ID (`--filter id=7be5ei6sqeye`, or `--filter ID=7be5ei6sqeye`) + * label (`--filter label=key=value`) + * mode (`--filter mode=replicated`, or `--filter mode=global`) + * Swarm: not supported + * name (`--filter name=myapp_web`) + * node (`--filter node=mynode`) + * Swarm: not supported + * service (`--filter service=web`) + * Swarm: not supported - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints services output - using a Go template. + The formatting options (`--format`) pretty-prints services output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |-------------|-----------------------------------| - | `.ID` | Service ID | - | `.Name` | Service name | - | `.Mode` | Service mode (replicated, global) | - | `.Replicas` | Service replicas | - | `.Image` | Service image | + | Placeholder | Description | + |-------------|-----------------------------------| + | `.ID` | Service ID | + | `.Name` | Service name | + | `.Mode` | Service mode (replicated, global) | + | `.Replicas` | Service replicas | + | `.Image` | Service image | - When using the `--format` option, the `stack services` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `stack services` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: + The following example uses a template without headers and outputs the + `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: - ```console - $ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}" + ```console + $ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}" - 0zmvwuiu3vue: replicated 10/10 - fm6uf97exkul: global 5/5 - ``` + 0zmvwuiu3vue: replicated 10/10 + fm6uf97exkul: global 5/5 + ``` + + To list all services in JSON format, use the `json` directive: + + ```console + $ docker stack services ls --format json + {"ID":"0axqbl293vwm","Image":"localstack/localstack:latest","Mode":"replicated","Name":"myapp_localstack","Ports":"*:4566-\u003e4566/tcp, *:8080-\u003e8080/tcp","Replicas":"0/1"} + {"ID":"384xvtzigz3p","Image":"redis:6.0.9-alpine3.12","Mode":"replicated","Name":"myapp_redis","Ports":"*:6379-\u003e6379/tcp","Replicas":"1/1"} + {"ID":"hyujct8cnjkk","Image":"postgres:13.2-alpine","Mode":"replicated","Name":"myapp_repos-db","Ports":"*:5432-\u003e5432/tcp","Replicas":"0/1"} + ``` deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false -swarm: false +swarm: true diff --git a/_data/engine-cli/docker_start.yaml b/_data/engine-cli/docker_start.yaml index 3394b3742d..6c0af2e45f 100644 --- a/_data/engine-cli/docker_start.yaml +++ b/_data/engine-cli/docker_start.yaml @@ -1,60 +1,77 @@ command: docker start +aliases: docker container start, docker start short: Start one or more stopped containers long: Start one or more stopped containers usage: docker start [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml options: -- option: attach - shorthand: a - value_type: bool - default_value: "false" - description: Attach STDOUT/STDERR and forward signals - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: checkpoint - value_type: string - description: Restore from this checkpoint - deprecated: false - experimental: true - experimentalcli: false - kubernetes: false - swarm: false - os_type: linux -- option: checkpoint-dir - value_type: string - description: Use a custom checkpoint storage directory - deprecated: false - experimental: true - experimentalcli: false - kubernetes: false - swarm: false - os_type: linux -- option: detach-keys - value_type: string - description: Override the key sequence for detaching a container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: interactive - shorthand: i - value_type: bool - default_value: "false" - description: Attach container's STDIN - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: attach + shorthand: a + value_type: bool + default_value: "false" + description: Attach STDOUT/STDERR and forward signals + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: checkpoint + value_type: string + description: Restore from this checkpoint + deprecated: false + hidden: false + experimental: true + experimentalcli: false + kubernetes: false + swarm: false + os_type: linux + - option: checkpoint-dir + value_type: string + description: Use a custom checkpoint storage directory + deprecated: false + hidden: false + experimental: true + experimentalcli: false + kubernetes: false + swarm: false + os_type: linux + - option: detach-keys + value_type: string + description: Override the key sequence for detaching a container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: interactive + shorthand: i + value_type: bool + default_value: "false" + description: Attach container's STDIN + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker start my_container - ``` + ```console + $ docker start my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_stats.yaml b/_data/engine-cli/docker_stats.yaml index 34fa3e0981..0510dc7148 100644 --- a/_data/engine-cli/docker_stats.yaml +++ b/_data/engine-cli/docker_stats.yaml @@ -1,209 +1,232 @@ command: docker stats +aliases: docker container stats, docker stats short: Display a live stream of container(s) resource usage statistics 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. + 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 need more detailed information about a container's resource usage, use - the `/containers/(id)/stats` API endpoint. + If you need 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 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 cache so that clients - > can use the data as needed. The cache usage is defined as the value of - > `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts. - > - > On Docker 19.03 and older, the cache usage was defined as the value of `cache` - > field. On cgroup v2 hosts, the cache usage is defined as the value of - > `inactive_file` field. + > **Note** + > + > On Linux, the Docker CLI reports memory usage by subtracting 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 cache so that clients + > can use the data as needed. The cache usage is defined as the value of + > `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts. + > + > On Docker 19.03 and older, the cache usage was defined as the value of `cache` + > field. On cgroup v2 hosts, the cache usage is defined as the value of + > `inactive_file` field. - > **Note** - > - > The `PIDS` column contains the number of processes and kernel threads created - > by that container. Threads is the term used by Linux kernel. Other equivalent - > terms are "lightweight process" or "kernel task", etc. A large number in the - > `PIDS` column combined with a small number of processes (as reported by `ps` - > or `top`) may indicate that something in the container is creating many threads. + > **Note** + > + > The `PIDS` column contains the number of processes and kernel threads created + > by that container. Threads is the term used by Linux kernel. Other equivalent + > terms are "lightweight process" or "kernel task", etc. A large number in the + > `PIDS` column combined with a small number of processes (as reported by `ps` + > or `top`) may indicate that something in the container is creating many threads. usage: docker stats [OPTIONS] [CONTAINER...] pname: docker plink: docker.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Show all containers (default shows just running) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print images using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-stream - value_type: bool - default_value: "false" - description: Disable streaming stats and only pull the first result - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-trunc - value_type: bool - default_value: "false" - description: Do not truncate output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Show all containers (default shows just running) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-stream + value_type: bool + default_value: "false" + description: Disable streaming stats and only pull the first result + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: no-trunc + value_type: bool + default_value: "false" + description: Do not truncate output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Running `docker stats` on all running containers against a Linux daemon. + Running `docker stats` on all running containers against a Linux daemon. - ```console - $ docker stats + ```console + $ docker stats - CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS - b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 - 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 - e5c383697914 test-1951.1.kay7x1lh1twk9c0oig50sd5tr 0.00% 196KiB / 1.952GiB 0.01% 71.2kB / 0B 770kB / 0B 1 - 4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2 - ``` + CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS + b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 + 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 + e5c383697914 test-1951.1.kay7x1lh1twk9c0oig50sd5tr 0.00% 196KiB / 1.952GiB 0.01% 71.2kB / 0B 770kB / 0B 1 + 4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2 + ``` - If you don't [specify a format string using `--format`](#format), the - following columns are shown. + If you don't [specify a format string using `--format`](#format), the + following columns are shown. - | Column name | Description | - |---------------------------|-----------------------------------------------------------------------------------------------| - | `CONTAINER ID` and `Name` | the ID and name of the container | - | `CPU %` and `MEM %` | the percentage of the host's CPU and memory the container is using | - | `MEM USAGE / LIMIT` | the total memory the container is using, and the total amount of memory it is allowed to use | - | `NET I/O` | The amount of data the container has sent and received over its network interface | - | `BLOCK I/O` | The amount of data the container has read to and written from block devices on the host | - | `PIDs` | the number of processes or threads the container has created | + | Column name | Description | + |---------------------------|-----------------------------------------------------------------------------------------------| + | `CONTAINER ID` and `Name` | the ID and name of the container | + | `CPU %` and `MEM %` | the percentage of the host's CPU and memory the container is using | + | `MEM USAGE / LIMIT` | the total memory the container is using, and the total amount of memory it is allowed to use | + | `NET I/O` | The amount of data the container has received and sent over its network interface | + | `BLOCK I/O` | The amount of data the container has written to and read from block devices on the host | + | `PIDs` | the number of processes or threads the container has created | - Running `docker stats` on multiple containers by name and id against a Linux daemon. + Running `docker stats` on multiple containers by name and id against a Linux daemon. - ```console - $ docker stats awesome_brattain 67b2525d8ad1 + ```console + $ docker stats awesome_brattain 67b2525d8ad1 - CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS - b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 - 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 - ``` + CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS + b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 + 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 + ``` - Running `docker stats` on container with name nginx and getting output in `json` format. + Running `docker stats` on container with name nginx and getting output in `json` format. - ```console - $ docker stats nginx --no-stream --format "{{ json . }}" - {"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"} - ``` + ```console + $ docker stats nginx --no-stream --format "{{ json . }}" + {"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"} + ``` - Running `docker stats` with customized format on all (Running and Stopped) containers. + Running `docker stats` with customized format on all (Running and Stopped) containers. - ```console - $ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 drunk_visvesvaraya big_heisenberg + ```console + $ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 drunk_visvesvaraya big_heisenberg - CONTAINER CPU % MEM USAGE / LIMIT - fervent_panini 0.00% 56KiB / 15.57GiB - 5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB - drunk_visvesvaraya 0.00% 0B / 0B - big_heisenberg 0.00% 0B / 0B - ``` + CONTAINER CPU % MEM USAGE / LIMIT + fervent_panini 0.00% 56KiB / 15.57GiB + 5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB + drunk_visvesvaraya 0.00% 0B / 0B + big_heisenberg 0.00% 0B / 0B + ``` - `drunk_visvesvaraya` and `big_heisenberg` are stopped containers in the above example. + `drunk_visvesvaraya` and `big_heisenberg` are stopped containers in the above example. - Running `docker stats` on all running containers against a Windows daemon. + Running `docker stats` on all running containers against a Windows daemon. - ```powershell - PS E:\> docker stats - CONTAINER ID CPU % PRIV WORKING SET NET I/O BLOCK I/O - 09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB - 9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB - 3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB - ``` + ```powershell + PS E:\> docker stats + CONTAINER ID CPU % PRIV WORKING SET NET I/O BLOCK I/O + 09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB + 9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB + 3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB + ``` - Running `docker stats` on multiple containers by name and id against a Windows daemon. + Running `docker stats` on multiple containers by name and id against a Windows daemon. - ```powershell - PS E:\> docker ps -a - CONTAINER ID NAME IMAGE COMMAND CREATED STATUS PORTS NAMES - 3f214c61ad1d awesome_brattain nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky - 9db7aa4d986d mad_wilson windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson - 09d3bb5b1604 fervent_panini windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley + ```powershell + PS E:\> docker ps -a + CONTAINER ID NAME IMAGE COMMAND CREATED STATUS PORTS NAMES + 3f214c61ad1d awesome_brattain nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky + 9db7aa4d986d mad_wilson windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson + 09d3bb5b1604 fervent_panini windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley - PS E:\> docker stats 3f214c61ad1d mad_wilson - CONTAINER ID NAME CPU % PRIV WORKING SET NET I/O BLOCK I/O - 3f214c61ad1d awesome_brattain 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB - 9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB - ``` + PS E:\> docker stats 3f214c61ad1d mad_wilson + CONTAINER ID NAME CPU % PRIV WORKING SET NET I/O BLOCK I/O + 3f214c61ad1d awesome_brattain 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB + 9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) pretty prints container output - using a Go template. + The formatting option (`--format`) pretty prints container output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |--------------|----------------------------------------------| - | `.Container` | Container name or ID (user input) | - | `.Name` | Container name | - | `.ID` | Container ID | - | `.CPUPerc` | CPU percentage | - | `.MemUsage` | Memory usage | - | `.NetIO` | Network IO | - | `.BlockIO` | Block IO | - | `.MemPerc` | Memory percentage (Not available on Windows) | - | `.PIDs` | Number of PIDs (Not available on Windows) | + | Placeholder | Description | + |--------------|----------------------------------------------| + | `.Container` | Container name or ID (user input) | + | `.Name` | Container name | + | `.ID` | Container ID | + | `.CPUPerc` | CPU percentage | + | `.MemUsage` | Memory usage | + | `.NetIO` | Network IO | + | `.BlockIO` | Block IO | + | `.MemPerc` | Memory percentage (Not available on Windows) | + | `.PIDs` | Number of PIDs (Not available on Windows) | - When using the `--format` option, the `stats` command either - outputs the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `stats` command either + outputs the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `Container` and `CPUPerc` entries separated by a colon (`:`) for all images: + The following example uses a template without headers and outputs the + `Container` and `CPUPerc` entries separated by a colon (`:`) for all images: - ```console - $ docker stats --format "{{.Container}}: {{.CPUPerc}}" + ```console + $ docker stats --format "{{.Container}}: {{.CPUPerc}}" - 09d3bb5b1604: 6.61% - 9db7aa4d986d: 9.19% - 3f214c61ad1d: 0.00% - ``` + 09d3bb5b1604: 6.61% + 9db7aa4d986d: 9.19% + 3f214c61ad1d: 0.00% + ``` - To list all containers statistics with their name, CPU percentage and memory - usage in a table format you can use: + To list all containers statistics with their name, CPU percentage and memory + usage in a table format you can use: - ```console - $ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" + ```console + $ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" - CONTAINER CPU % PRIV WORKING SET - 1285939c1fd3 0.07% 796 KiB / 64 MiB - 9c76f7834ae2 0.07% 2.746 MiB / 64 MiB - d1ea048f04e4 0.03% 4.583 MiB / 64 MiB - ``` + CONTAINER CPU % PRIV WORKING SET + 1285939c1fd3 0.07% 796 KiB / 64 MiB + 9c76f7834ae2 0.07% 2.746 MiB / 64 MiB + d1ea048f04e4 0.03% 4.583 MiB / 64 MiB + ``` - The default format is as follows: + The default format is as follows: - On Linux: + On Linux: - "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}" + "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}" - On Windows: + On Windows: - "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" + "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_stop.yaml b/_data/engine-cli/docker_stop.yaml index caf6ba2f8b..cd02162a2e 100644 --- a/_data/engine-cli/docker_stop.yaml +++ b/_data/engine-cli/docker_stop.yaml @@ -1,28 +1,51 @@ command: docker stop +aliases: docker container stop, docker stop short: Stop one or more running containers long: |- - The main process inside the container will receive `SIGTERM`, and after a grace - period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL` - instruction in the container's Dockerfile, or the `--stop-signal` option to - `docker run`. + The main process inside the container will receive `SIGTERM`, and after a grace + period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL` + instruction in the container's Dockerfile, or the `--stop-signal` option to + `docker run`. usage: docker stop [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml options: -- option: time - shorthand: t - value_type: int - default_value: "10" - description: Seconds to wait for stop before killing it - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: signal + shorthand: s + value_type: string + description: Signal to send to the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: time + shorthand: t + value_type: int + default_value: "0" + description: Seconds to wait before killing the container + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker stop my_container - ``` + ```console + $ docker stop my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_swarm.yaml b/_data/engine-cli/docker_swarm.yaml index e5e071d76c..8e3fd77894 100644 --- a/_data/engine-cli/docker_swarm.yaml +++ b/_data/engine-cli/docker_swarm.yaml @@ -5,23 +5,34 @@ usage: docker swarm pname: docker plink: docker.yaml cname: -- docker swarm ca -- docker swarm init -- docker swarm join -- docker swarm join-token -- docker swarm leave -- docker swarm unlock -- docker swarm unlock-key -- docker swarm update + - docker swarm ca + - docker swarm init + - docker swarm join + - docker swarm join-token + - docker swarm leave + - docker swarm unlock + - docker swarm unlock-key + - docker swarm update clink: -- docker_swarm_ca.yaml -- docker_swarm_init.yaml -- docker_swarm_join.yaml -- docker_swarm_join-token.yaml -- docker_swarm_leave.yaml -- docker_swarm_unlock.yaml -- docker_swarm_unlock-key.yaml -- docker_swarm_update.yaml + - docker_swarm_ca.yaml + - docker_swarm_init.yaml + - docker_swarm_join.yaml + - docker_swarm_join-token.yaml + - docker_swarm_leave.yaml + - docker_swarm_unlock.yaml + - docker_swarm_unlock-key.yaml + - docker_swarm_update.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_swarm_ca.yaml b/_data/engine-cli/docker_swarm_ca.yaml index 199e1489e2..18236fd31e 100644 --- a/_data/engine-cli/docker_swarm_ca.yaml +++ b/_data/engine-cli/docker_swarm_ca.yaml @@ -1,160 +1,186 @@ command: docker swarm ca short: Display and rotate the root CA long: |- - View or rotate the current swarm CA certificate. + View or rotate the current swarm CA certificate. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker swarm ca [OPTIONS] pname: docker swarm plink: docker_swarm.yaml options: -- option: ca-cert - value_type: pem-file - description: | - Path to the PEM-formatted root CA certificate to use for the new cluster - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ca-key - value_type: pem-file - description: | - Path to the PEM-formatted root CA key to use for the new cluster - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cert-expiry - value_type: duration - default_value: 2160h0m0s - description: Validity period for node certificates (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: detach - shorthand: d - value_type: bool - default_value: "false" - description: | - Exit immediately instead of waiting for the root rotation to converge - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: external-ca - value_type: external-ca - description: Specifications of one or more certificate signing endpoints - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress progress output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rotate - value_type: bool - default_value: "false" - description: | - Rotate the swarm CA - if no certificate or key are provided, new ones will be generated - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: ca-cert + value_type: pem-file + description: | + Path to the PEM-formatted root CA certificate to use for the new cluster + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: ca-key + value_type: pem-file + description: Path to the PEM-formatted root CA key to use for the new cluster + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cert-expiry + value_type: duration + default_value: 2160h0m0s + description: Validity period for node certificates (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "false" + description: | + Exit immediately instead of waiting for the root rotation to converge + details_url: '#detach' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: external-ca + value_type: external-ca + description: Specifications of one or more certificate signing endpoints + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress progress output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rotate + value_type: bool + default_value: "false" + description: | + Rotate the swarm CA - if no certificate or key are provided, new ones will be generated + details_url: '#rotate' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Run the `docker swarm ca` command without any options to view the current root CA certificate - in PEM format. + Run the `docker swarm ca` command without any options to view the current root CA certificate + in PEM format. - ```console - $ docker swarm ca + ```console + $ docker swarm ca - -----BEGIN CERTIFICATE----- - MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw - EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx - MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH - A0IABKL6/C0sihYEb935wVPRA8MqzPLn3jzou0OJRXHsCLcVExigrMdgmLCC+Va4 - +sJ+SLVO1eQbvLHH8uuDdF/QOU6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB - Af8EBTADAQH/MB0GA1UdDgQWBBSfUy5bjUnBAx/B0GkOBKp91XvxzjAKBggqhkjO - PQQDAgNJADBGAiEAnbvh0puOS5R/qvy1PMHY1iksYKh2acsGLtL/jAIvO4ACIQCi - lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA== - -----END CERTIFICATE----- - ``` + -----BEGIN CERTIFICATE----- + MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw + EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx + MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH + A0IABKL6/C0sihYEb935wVPRA8MqzPLn3jzou0OJRXHsCLcVExigrMdgmLCC+Va4 + +sJ+SLVO1eQbvLHH8uuDdF/QOU6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB + Af8EBTADAQH/MB0GA1UdDgQWBBSfUy5bjUnBAx/B0GkOBKp91XvxzjAKBggqhkjO + PQQDAgNJADBGAiEAnbvh0puOS5R/qvy1PMHY1iksYKh2acsGLtL/jAIvO4ACIQCi + lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA== + -----END CERTIFICATE----- + ``` - Pass the `--rotate` flag (and optionally a `--ca-cert`, along with a `--ca-key` or - `--external-ca` parameter flag), in order to rotate the current swarm root CA. + Pass the `--rotate` flag (and optionally a `--ca-cert`, along with a `--ca-key` or + `--external-ca` parameter flag), in order to rotate the current swarm root CA. - ```console - $ docker swarm ca --rotate - desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e - rotated TLS certificates: [=========================> ] 1/2 nodes - rotated CA certificates: [> ] 0/2 nodes - ``` + ```console + $ docker swarm ca --rotate + desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e + rotated TLS certificates: [=========================> ] 1/2 nodes + rotated CA certificates: [> ] 0/2 nodes + ``` - Once the rotation os finished (all the progress bars have completed) the now-current - CA certificate will be printed: + Once the rotation os finished (all the progress bars have completed) the now-current + CA certificate will be printed: - ```console - $ docker swarm ca --rotate - desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e - rotated TLS certificates: [==================================================>] 2/2 nodes - rotated CA certificates: [==================================================>] 2/2 nodes - -----BEGIN CERTIFICATE----- - MIIBazCCARCgAwIBAgIUFynG04h5Rrl4lKyA4/E65tYKg8IwCgYIKoZIzj0EAwIw - EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTE2MDAxMDAwWhcNMzcwNTExMDAx - MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH - A0IABC2DuNrIETP7C7lfiEPk39tWaaU0I2RumUP4fX4+3m+87j0DU0CsemUaaOG6 - +PxHhGu2VXQ4c9pctPHgf7vWeVajQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB - Af8EBTADAQH/MB0GA1UdDgQWBBSEL02z6mCI3SmMDmITMr12qCRY2jAKBggqhkjO - PQQDAgNJADBGAiEA263Eb52+825EeNQZM0AME+aoH1319Zp9/J5ijILW+6ACIQCg - gyg5u9Iliel99l7SuMhNeLkrU7fXs+Of1nTyyM73ig== - -----END CERTIFICATE----- - ``` + ```console + $ docker swarm ca --rotate + desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e + rotated TLS certificates: [==================================================>] 2/2 nodes + rotated CA certificates: [==================================================>] 2/2 nodes + -----BEGIN CERTIFICATE----- + MIIBazCCARCgAwIBAgIUFynG04h5Rrl4lKyA4/E65tYKg8IwCgYIKoZIzj0EAwIw + EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTE2MDAxMDAwWhcNMzcwNTExMDAx + MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH + A0IABC2DuNrIETP7C7lfiEPk39tWaaU0I2RumUP4fX4+3m+87j0DU0CsemUaaOG6 + +PxHhGu2VXQ4c9pctPHgf7vWeVajQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB + Af8EBTADAQH/MB0GA1UdDgQWBBSEL02z6mCI3SmMDmITMr12qCRY2jAKBggqhkjO + PQQDAgNJADBGAiEA263Eb52+825EeNQZM0AME+aoH1319Zp9/J5ijILW+6ACIQCg + gyg5u9Iliel99l7SuMhNeLkrU7fXs+Of1nTyyM73ig== + -----END CERTIFICATE----- + ``` - ### Root CA rotation (--rotate) + ### Root CA rotation (--rotate) {#rotate} - Root CA Rotation is recommended if one or more of the swarm managers have been - compromised, so that those managers can no longer connect to or be trusted by - any other node in the cluster. + > **Note** + > + > Mirantis Kubernetes Engine (MKE), formerly known as Docker UCP, provides an external + > certificate manager service for the swarm. If you run swarm on MKE, you shouldn't + > rotate the CA certificates manually. Instead, contact Mirantis support if you need + > to rotate a certificate. - Alternately, root CA rotation can be used to give control of the swarm CA - to an external CA, or to take control back from an external CA. + Root CA Rotation is recommended if one or more of the swarm managers have been + compromised, so that those managers can no longer connect to or be trusted by + any other node in the cluster. - The `--rotate` flag does not require any parameters to do a rotation, but you can - optionally specify a certificate and key, or a certificate and external CA URL, - and those will be used instead of an automatically-generated certificate/key pair. + Alternately, root CA rotation can be used to give control of the swarm CA + to an external CA, or to take control back from an external CA. - Because the root CA key should be kept secret, if provided it will not be visible - when viewing swarm any information via the CLI or API. + The `--rotate` flag does not require any parameters to do a rotation, but you can + optionally specify a certificate and key, or a certificate and external CA URL, + and those will be used instead of an automatically-generated certificate/key pair. - The root CA rotation will not be completed until all registered nodes have - rotated their TLS certificates. If the rotation is not completing within a - reasonable amount of time, try running - `docker node ls --format '{{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}'` to - see if any nodes are down or otherwise unable to rotate TLS certificates. + Because the root CA key should be kept secret, if provided it will not be visible + when viewing swarm any information via the CLI or API. + + The root CA rotation will not be completed until all registered nodes have + rotated their TLS certificates. If the rotation is not completing within a + reasonable amount of time, try running + `docker node ls --format '{{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}'` to + see if any nodes are down or otherwise unable to rotate TLS certificates. - ### Run root CA rotation in detached mode (--detach) + ### Run root CA rotation in detached mode (--detach) {#detach} - Initiate the root CA rotation, but do not wait for the completion of or display the - progress of the rotation. + Initiate the root CA rotation, but do not wait for the completion of or display the + progress of the rotation. deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_swarm_init.yaml b/_data/engine-cli/docker_swarm_init.yaml index 50c7eed897..7526fef26a 100644 --- a/_data/engine-cli/docker_swarm_init.yaml +++ b/_data/engine-cli/docker_swarm_init.yaml @@ -1,302 +1,328 @@ command: docker swarm init short: Initialize a swarm long: |- - Initialize a swarm. The docker engine targeted by this command becomes a manager - in the newly created single-node swarm. + Initialize a swarm. The docker engine targeted by this command becomes a manager + in the newly created single-node swarm. usage: docker swarm init [OPTIONS] pname: docker swarm plink: docker_swarm.yaml options: -- option: advertise-addr - value_type: string - description: 'Advertised address (format: [:port])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: autolock - value_type: bool - default_value: "false" - description: | - Enable manager autolocking (requiring an unlock key to start a stopped manager) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: availability - value_type: string - default_value: active - description: Availability of the node ("active"|"pause"|"drain") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cert-expiry - value_type: duration - default_value: 2160h0m0s - description: Validity period for node certificates (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: data-path-addr - value_type: string - description: | - Address or interface to use for data path traffic (format: ) - deprecated: false - min_api_version: "1.31" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: data-path-port - value_type: uint32 - default_value: "0" - description: | - Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: default-addr-pool - value_type: ipNetSlice - default_value: '[]' - description: default address pool in CIDR format - deprecated: false - min_api_version: "1.39" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: default-addr-pool-mask-length - value_type: uint32 - default_value: "24" - description: default address pool subnet mask length - deprecated: false - min_api_version: "1.39" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dispatcher-heartbeat - value_type: duration - default_value: 5s - description: Dispatcher heartbeat period (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: external-ca - value_type: external-ca - description: Specifications of one or more certificate signing endpoints - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force-new-cluster - value_type: bool - default_value: "false" - description: Force create a new cluster from current state - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: listen-addr - value_type: node-addr - default_value: 0.0.0.0:2377 - description: 'Listen address (format: [:port])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: max-snapshots - value_type: uint64 - default_value: "0" - description: Number of additional Raft snapshots to retain - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: snapshot-interval - value_type: uint64 - default_value: "10000" - description: Number of log entries between Raft snapshots - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: task-history-limit - value_type: int64 - default_value: "5" - description: Task history retention limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: advertise-addr + value_type: string + description: 'Advertised address (format: `[:port]`)' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: autolock + value_type: bool + default_value: "false" + description: | + Enable manager autolocking (requiring an unlock key to start a stopped manager) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: availability + value_type: string + default_value: active + description: Availability of the node (`active`, `pause`, `drain`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cert-expiry + value_type: duration + default_value: 2160h0m0s + description: Validity period for node certificates (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: data-path-addr + value_type: string + description: | + Address or interface to use for data path traffic (format: ``) + deprecated: false + hidden: false + min_api_version: "1.31" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: data-path-port + value_type: uint32 + default_value: "0" + description: | + Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: default-addr-pool + value_type: ipNetSlice + default_value: '[]' + description: default address pool in CIDR format + deprecated: false + hidden: false + min_api_version: "1.39" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: default-addr-pool-mask-length + value_type: uint32 + default_value: "24" + description: default address pool subnet mask length + deprecated: false + hidden: false + min_api_version: "1.39" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dispatcher-heartbeat + value_type: duration + default_value: 5s + description: Dispatcher heartbeat period (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: external-ca + value_type: external-ca + description: Specifications of one or more certificate signing endpoints + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force-new-cluster + value_type: bool + default_value: "false" + description: Force create a new cluster from current state + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: listen-addr + value_type: node-addr + default_value: 0.0.0.0:2377 + description: 'Listen address (format: `[:port]`)' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: max-snapshots + value_type: uint64 + default_value: "0" + description: Number of additional Raft snapshots to retain + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: snapshot-interval + value_type: uint64 + default_value: "10000" + description: Number of log entries between Raft snapshots + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: task-history-limit + value_type: int64 + default_value: "5" + description: Task history retention limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker swarm init --advertise-addr 192.168.99.121 + ```console + $ docker swarm init --advertise-addr 192.168.99.121 - Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager. + Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager. - To add a worker to this swarm, run the following command: + To add a worker to this swarm, run the following command: - docker swarm join \ - --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \ - 172.17.0.2:2377 + docker swarm join \ + --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \ + 172.17.0.2:2377 - To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions. - ``` + To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions. + ``` - `docker swarm init` generates two random tokens, a worker token and a manager token. When you join - a new node to the swarm, the node joins as a worker or manager node based upon the token you pass - to [swarm join](swarm_join.md). + `docker swarm init` generates two random tokens, a worker token and a manager token. When you join + a new node to the swarm, the node joins as a worker or manager node based upon the token you pass + to [swarm join](swarm_join.md). - After you create the swarm, you can display or rotate the token using - [swarm join-token](swarm_join-token.md). + After you create the swarm, you can display or rotate the token using + [swarm join-token](swarm_join-token.md). - ### `--autolock` + ### `--autolock` - This flag enables automatic locking of managers with an encryption key. The - private keys and data stored by all managers will be protected by the - encryption key printed in the output, and will not be accessible without it. - Thus, it is very important to store this key in order to activate a manager - after it restarts. The key can be passed to `docker swarm unlock` to reactivate - the manager. Autolock can be disabled by running - `docker swarm update --autolock=false`. After disabling it, the encryption key - is no longer required to start the manager, and it will start up on its own - without user intervention. + This flag enables automatic locking of managers with an encryption key. The + private keys and data stored by all managers will be protected by the + encryption key printed in the output, and will not be accessible without it. + Thus, it is very important to store this key in order to activate a manager + after it restarts. The key can be passed to `docker swarm unlock` to reactivate + the manager. Autolock can be disabled by running + `docker swarm update --autolock=false`. After disabling it, the encryption key + is no longer required to start the manager, and it will start up on its own + without user intervention. - ### `--cert-expiry` + ### `--cert-expiry` - This flag sets the validity period for node certificates. + This flag sets the validity period for node certificates. - ### `--dispatcher-heartbeat` + ### `--dispatcher-heartbeat` - This flag sets the frequency with which nodes are told to use as a - period to report their health. + This flag sets the frequency with which nodes are told to use as a + period to report their health. - ### `--external-ca` + ### `--external-ca` - This flag sets up the swarm to use an external CA to issue node certificates. The value takes - the form `protocol=X,url=Y`. The value for `protocol` specifies what protocol should be used - to send signing requests to the external CA. Currently, the only supported value is `cfssl`. - The URL specifies the endpoint where signing requests should be submitted. + This flag sets up the swarm to use an external CA to issue node certificates. The value takes + the form `protocol=X,url=Y`. The value for `protocol` specifies what protocol should be used + to send signing requests to the external CA. Currently, the only supported value is `cfssl`. + The URL specifies the endpoint where signing requests should be submitted. - ### `--force-new-cluster` + ### `--force-new-cluster` - This flag forces an existing node that was part of a quorum that was lost to restart as a single node Manager without losing its data. + This flag forces an existing node that was part of a quorum that was lost to restart as a single node Manager without losing its data. - ### `--listen-addr` + ### `--listen-addr` - The node listens for inbound swarm manager traffic on this address. The default is to listen on - 0.0.0.0:2377. It is also possible to specify a network interface to listen on that interface's - address; for example `--listen-addr eth0:2377`. + The node listens for inbound swarm manager traffic on this address. The default is to listen on + 0.0.0.0:2377. It is also possible to specify a network interface to listen on that interface's + address; for example `--listen-addr eth0:2377`. - Specifying a port is optional. If the value is a bare IP address or interface - name, the default port 2377 will be used. + Specifying a port is optional. If the value is a bare IP address or interface + name, the default port 2377 will be used. - ### `--advertise-addr` + ### `--advertise-addr` - This flag specifies the address that will be advertised to other members of the - swarm for API access and overlay networking. If unspecified, Docker will check - if the system has a single IP address, and use that IP address with the - listening port (see `--listen-addr`). If the system has multiple IP addresses, - `--advertise-addr` must be specified so that the correct address is chosen for - inter-manager communication and overlay networking. + This flag specifies the address that will be advertised to other members of the + swarm for API access and overlay networking. If unspecified, Docker will check + if the system has a single IP address, and use that IP address with the + listening port (see `--listen-addr`). If the system has multiple IP addresses, + `--advertise-addr` must be specified so that the correct address is chosen for + inter-manager communication and overlay networking. - It is also possible to specify a network interface to advertise that interface's address; - for example `--advertise-addr eth0:2377`. + It is also possible to specify a network interface to advertise that interface's address; + for example `--advertise-addr eth0:2377`. - Specifying a port is optional. If the value is a bare IP address or interface - name, the default port 2377 will be used. + Specifying a port is optional. If the value is a bare IP address or interface + name, the default port 2377 will be used. - ### `--data-path-addr` + ### `--data-path-addr` - This flag 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 then possible to separate the container's data traffic from the - management traffic of the cluster. - If unspecified, Docker will use the same IP address or interface that is used for the - advertise address. + This flag 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 then possible to separate the container's data traffic from the + management traffic of the cluster. + If unspecified, Docker will use the same IP address or interface that is used for the + advertise address. - ### `--data-path-port` + ### `--data-path-port` - This flag allows you to configure the UDP port number to use for data path - traffic. The provided port number must be within the 1024 - 49151 range. If - this flag is not set or is set to 0, the default port number 4789 is used. - The data path port can only be configured when initializing the swarm, and - applies to all nodes that join the swarm. - The following example initializes a new Swarm, and configures the data path - port to UDP port 7777; + This flag allows you to configure the UDP port number to use for data path + traffic. The provided port number must be within the 1024 - 49151 range. If + this flag is not set or is set to 0, the default port number 4789 is used. + The data path port can only be configured when initializing the swarm, and + applies to all nodes that join the swarm. + The following example initializes a new Swarm, and configures the data path + port to UDP port 7777; - ```console - $ docker swarm init --data-path-port=7777 - ``` + ```console + $ docker swarm init --data-path-port=7777 + ``` - After the swarm is initialized, use the `docker info` command to verify that - the port is configured: + After the swarm is initialized, use the `docker info` command to verify that + the port is configured: - ```console - $ docker info - <...> - ClusterID: 9vs5ygs0gguyyec4iqf2314c0 - Managers: 1 - Nodes: 1 - Data Path Port: 7777 - <...> - ``` + ```console + $ docker info + <...> + ClusterID: 9vs5ygs0gguyyec4iqf2314c0 + Managers: 1 + Nodes: 1 + Data Path Port: 7777 + <...> + ``` - ### `--default-addr-pool` - This flag specifies default subnet pools for global scope networks. - Format example is `--default-addr-pool 30.30.0.0/16 --default-addr-pool 40.40.0.0/16` + ### `--default-addr-pool` + This flag specifies default subnet pools for global scope networks. + Format example is `--default-addr-pool 30.30.0.0/16 --default-addr-pool 40.40.0.0/16` - ### `--default-addr-pool-mask-length` - This flag specifies default subnet pools mask length for default-addr-pool. - Format example is `--default-addr-pool-mask-length 24` + ### `--default-addr-pool-mask-length` + This flag specifies default subnet pools mask length for default-addr-pool. + Format example is `--default-addr-pool-mask-length 24` - ### `--task-history-limit` + ### `--task-history-limit` - This flag sets up task history retention limit. + This flag sets up task history retention limit. - ### `--max-snapshots` + ### `--max-snapshots` - This flag sets the number of old Raft snapshots to retain in addition to the - current Raft snapshots. By default, no old snapshots are retained. This option - may be used for debugging, or to store old snapshots of the swarm state for - disaster recovery purposes. + This flag sets the number of old Raft snapshots to retain in addition to the + current Raft snapshots. By default, no old snapshots are retained. This option + may be used for debugging, or to store old snapshots of the swarm state for + disaster recovery purposes. - ### `--snapshot-interval` + ### `--snapshot-interval` - This flag specifies how many log entries to allow in between Raft snapshots. - Setting this to a higher number will trigger snapshots less frequently. - Snapshots compact the Raft log and allow for more efficient transfer of the - state to new managers. However, there is a performance cost to taking snapshots - frequently. + This flag specifies how many log entries to allow in between Raft snapshots. + Setting this to a higher number will trigger snapshots less frequently. + Snapshots compact the Raft log and allow for more efficient transfer of the + state to new managers. However, there is a performance cost to taking snapshots + frequently. - ### `--availability` + ### `--availability` - This flag specifies the availability of the node at the time the node joins a master. - Possible availability values are `active`, `pause`, or `drain`. + This flag specifies the availability of the node at the time the node joins a master. + Possible availability values are `active`, `pause`, or `drain`. - This flag is useful in certain situations. For example, a cluster may want to have - dedicated manager nodes that are not served as worker nodes. This could be achieved - by passing `--availability=drain` to `docker swarm init`. + This flag is useful in certain situations. For example, a cluster may want to have + dedicated manager nodes that are not served as worker nodes. This could be achieved + by passing `--availability=drain` to `docker swarm init`. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_swarm_join-token.yaml b/_data/engine-cli/docker_swarm_join-token.yaml index 2e52efa501..3ea79d614c 100644 --- a/_data/engine-cli/docker_swarm_join-token.yaml +++ b/_data/engine-cli/docker_swarm_join-token.yaml @@ -1,112 +1,125 @@ command: docker swarm join-token short: Manage join tokens long: |- - Join tokens are secrets that allow a node to join the swarm. There are two - different join tokens available, one for the worker role and one for the manager - role. You pass the token using the `--token` flag when you run - [swarm join](swarm_join.md). Nodes use the join token only when they join the - swarm. + Join tokens are secrets that allow a node to join the swarm. There are two + different join tokens available, one for the worker role and one for the manager + role. You pass the token using the `--token` flag when you run + [swarm join](swarm_join.md). Nodes use the join token only when they join the + swarm. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker swarm join-token [OPTIONS] (worker|manager) pname: docker swarm plink: docker_swarm.yaml options: -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display token - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rotate - value_type: bool - default_value: "false" - description: Rotate join token - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display token + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rotate + value_type: bool + default_value: "false" + description: Rotate join token + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - You can view or rotate the join tokens using `swarm join-token`. + You can view or rotate the join tokens using `swarm join-token`. - As a convenience, you can pass `worker` or `manager` as an argument to - `join-token` to print the full `docker swarm join` command to join a new node to - the swarm: + As a convenience, you can pass `worker` or `manager` as an argument to + `join-token` to print the full `docker swarm join` command to join a new node to + the swarm: - ```console - $ docker swarm join-token worker + ```console + $ docker swarm join-token worker - To add a worker to this swarm, run the following command: + To add a worker to this swarm, run the following command: - docker swarm join \ - --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \ - 172.17.0.2:2377 + docker swarm join \ + --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \ + 172.17.0.2:2377 - $ docker swarm join-token manager + $ docker swarm join-token manager - To add a manager to this swarm, run the following command: + To add a manager to this swarm, run the following command: - docker swarm join \ - --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2 \ - 172.17.0.2:2377 - ``` + docker swarm join \ + --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2 \ + 172.17.0.2:2377 + ``` - Use the `--rotate` flag to generate a new join token for the specified role: + Use the `--rotate` flag to generate a new join token for the specified role: - ```console - $ docker swarm join-token --rotate worker + ```console + $ docker swarm join-token --rotate worker - Successfully rotated worker join token. + Successfully rotated worker join token. - To add a worker to this swarm, run the following command: + To add a worker to this swarm, run the following command: - docker swarm join \ - --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t \ - 172.17.0.2:2377 - ``` + docker swarm join \ + --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t \ + 172.17.0.2:2377 + ``` - After using `--rotate`, only the new token will be valid for joining with the specified role. + After using `--rotate`, only the new token will be valid for joining with the specified role. - The `-q` (or `--quiet`) flag only prints the token: + The `-q` (or `--quiet`) flag only prints the token: - ```console - $ docker swarm join-token -q worker + ```console + $ docker swarm join-token -q worker - SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t - ``` + SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t + ``` - ### `--rotate` + ### `--rotate` - Because tokens allow new nodes to join the swarm, you should keep them secret. - Be particularly careful with manager tokens since they allow new manager nodes - to join the swarm. A rogue manager has the potential to disrupt the operation of - your swarm. + Because tokens allow new nodes to join the swarm, you should keep them secret. + Be particularly careful with manager tokens since they allow new manager nodes + to join the swarm. A rogue manager has the potential to disrupt the operation of + your swarm. - Rotate your swarm's join token if a token gets checked-in to version control, - stolen, or a node is compromised. You may also want to periodically rotate the - token to ensure any unknown token leaks do not allow a rogue node to join - the swarm. + Rotate your swarm's join token if a token gets checked-in to version control, + stolen, or a node is compromised. You may also want to periodically rotate the + token to ensure any unknown token leaks do not allow a rogue node to join + the swarm. - To rotate the join token and print the newly generated token, run - `docker swarm join-token --rotate` and pass the role: `manager` or `worker`. + To rotate the join token and print the newly generated token, run + `docker swarm join-token --rotate` and pass the role: `manager` or `worker`. - Rotating a join-token means that no new nodes will be able to join the swarm - using the old token. Rotation does not affect existing nodes in the swarm - because the join token is only used for authorizing new nodes joining the swarm. + Rotating a join-token means that no new nodes will be able to join the swarm + using the old token. Rotation does not affect existing nodes in the swarm + because the join token is only used for authorizing new nodes joining the swarm. - ### `--quiet` + ### `--quiet` - Only print the token. Do not print a complete command for joining. + Only print the token. Do not print a complete command for joining. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_swarm_join.yaml b/_data/engine-cli/docker_swarm_join.yaml index c3e9e41118..0e98942684 100644 --- a/_data/engine-cli/docker_swarm_join.yaml +++ b/_data/engine-cli/docker_swarm_join.yaml @@ -1,143 +1,159 @@ command: docker swarm join short: Join a swarm as a node and/or manager long: |- - Join a node to a swarm. The node joins as a manager node or worker node based upon the token you - pass with the `--token` flag. If you pass a manager token, the node joins as a manager. If you - pass a worker token, the node joins as a worker. + Join a node to a swarm. The node joins as a manager node or worker node based upon the token you + pass with the `--token` flag. If you pass a manager token, the node joins as a manager. If you + pass a worker token, the node joins as a worker. usage: docker swarm join [OPTIONS] HOST:PORT pname: docker swarm plink: docker_swarm.yaml options: -- option: advertise-addr - value_type: string - description: 'Advertised address (format: [:port])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: availability - value_type: string - default_value: active - description: Availability of the node ("active"|"pause"|"drain") - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: data-path-addr - value_type: string - description: | - Address or interface to use for data path traffic (format: ) - deprecated: false - min_api_version: "1.31" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: listen-addr - value_type: node-addr - default_value: 0.0.0.0:2377 - description: 'Listen address (format: [:port])' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: token - value_type: string - description: Token for entry into the swarm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: advertise-addr + value_type: string + description: 'Advertised address (format: `[:port]`)' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: availability + value_type: string + default_value: active + description: Availability of the node (`active`, `pause`, `drain`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: data-path-addr + value_type: string + description: | + Address or interface to use for data path traffic (format: ``) + deprecated: false + hidden: false + min_api_version: "1.31" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: listen-addr + value_type: node-addr + default_value: 0.0.0.0:2377 + description: 'Listen address (format: `[:port]`)' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: token + value_type: string + description: Token for entry into the swarm + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Join a node to swarm as a manager + ### Join a node to swarm as a manager - The example below demonstrates joining a manager node using a manager token. + The example below demonstrates joining a manager node using a manager token. - ```console - $ docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2 192.168.99.121:2377 - This node joined a swarm as a manager. + ```console + $ docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2 192.168.99.121:2377 + This node joined a swarm as a manager. - $ docker node ls - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - dkp8vy1dq1kxleu9g4u78tlag * manager2 Ready Active Reachable - dvfxp4zseq4s0rih1selh0d20 manager1 Ready Active Leader - ``` + $ docker node ls + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + dkp8vy1dq1kxleu9g4u78tlag * manager2 Ready Active Reachable + dvfxp4zseq4s0rih1selh0d20 manager1 Ready Active Leader + ``` - A cluster should only have 3-7 managers at most, because a majority of managers must be available - for the cluster to function. Nodes that aren't meant to participate in this management quorum - should join as workers instead. Managers should be stable hosts that have static IP addresses. + A cluster should only have 3-7 managers at most, because a majority of managers must be available + for the cluster to function. Nodes that aren't meant to participate in this management quorum + should join as workers instead. Managers should be stable hosts that have static IP addresses. - ### Join a node to swarm as a worker + ### Join a node to swarm as a worker - The example below demonstrates joining a worker node using a worker token. + The example below demonstrates joining a worker node using a worker token. - ```console - $ docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx 192.168.99.121:2377 - This node joined a swarm as a worker. + ```console + $ docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx 192.168.99.121:2377 + This node joined a swarm as a worker. - $ docker node ls - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 7ln70fl22uw2dvjn2ft53m3q5 worker2 Ready Active - dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active Reachable - dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader - ``` + $ docker node ls + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + 7ln70fl22uw2dvjn2ft53m3q5 worker2 Ready Active + dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active Reachable + dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader + ``` - ### `--listen-addr value` + ### `--listen-addr value` - If the node is a manager, it will listen for inbound swarm manager traffic on this - address. The default is to listen on 0.0.0.0:2377. It is also possible to specify a - network interface to listen on that interface's address; for example `--listen-addr eth0:2377`. + If the node is a manager, it will listen for inbound swarm manager traffic on this + address. The default is to listen on 0.0.0.0:2377. It is also possible to specify a + network interface to listen on that interface's address; for example `--listen-addr eth0:2377`. - Specifying a port is optional. If the value is a bare IP address, or interface - name, the default port 2377 will be used. + Specifying a port is optional. If the value is a bare IP address, or interface + name, the default port 2377 will be used. - This flag is generally not necessary when joining an existing swarm. + This flag is generally not necessary when joining an existing swarm. - ### `--advertise-addr value` + ### `--advertise-addr value` - This flag specifies the address that will be advertised to other members of the - swarm for API access. If unspecified, Docker will check if the system has a - single IP address, and use that IP address with the listening port (see - `--listen-addr`). If the system has multiple IP addresses, `--advertise-addr` - must be specified so that the correct address is chosen for inter-manager - communication and overlay networking. + This flag specifies the address that will be advertised to other members of the + swarm for API access. If unspecified, Docker will check if the system has a + single IP address, and use that IP address with the listening port (see + `--listen-addr`). If the system has multiple IP addresses, `--advertise-addr` + must be specified so that the correct address is chosen for inter-manager + communication and overlay networking. - It is also possible to specify a network interface to advertise that interface's address; - for example `--advertise-addr eth0:2377`. + It is also possible to specify a network interface to advertise that interface's address; + for example `--advertise-addr eth0:2377`. - Specifying a port is optional. If the value is a bare IP address, or interface - name, the default port 2377 will be used. + Specifying a port is optional. If the value is a bare IP address, or interface + name, the default port 2377 will be used. - This flag is generally not necessary when joining an existing swarm. If - you're joining new nodes through a load balancer, you should use this flag to - ensure the node advertises its IP address and not the IP address of the load - balancer. + This flag is generally not necessary when joining an existing swarm. If + you're joining new nodes through a load balancer, you should use this flag to + ensure the node advertises its IP address and not the IP address of the load + balancer. - ### `--data-path-addr` + ### `--data-path-addr` - This flag 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 then possible to separate the container's data traffic from the - management traffic of the cluster. - If unspecified, Docker will use the same IP address or interface that is used for the - advertise address. + This flag 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 then possible to separate the container's data traffic from the + management traffic of the cluster. + If unspecified, Docker will use the same IP address or interface that is used for the + advertise address. - ### `--token string` + ### `--token string` - Secret value required for nodes to join the swarm + Secret value required for nodes to join the swarm - ### `--availability` + ### `--availability` - This flag specifies the availability of the node at the time the node joins a master. - Possible availability values are `active`, `pause`, or `drain`. + This flag specifies the availability of the node at the time the node joins a master. + Possible availability values are `active`, `pause`, or `drain`. - This flag is useful in certain situations. For example, a cluster may want to have - dedicated manager nodes that are not served as worker nodes. This could be achieved - by passing `--availability=drain` to `docker swarm join`. + This flag is useful in certain situations. For example, a cluster may want to have + dedicated manager nodes that are not served as worker nodes. This could be achieved + by passing `--availability=drain` to `docker swarm join`. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_swarm_leave.yaml b/_data/engine-cli/docker_swarm_leave.yaml index 1a3f453886..b7abf0617d 100644 --- a/_data/engine-cli/docker_swarm_leave.yaml +++ b/_data/engine-cli/docker_swarm_leave.yaml @@ -1,52 +1,64 @@ command: docker swarm leave short: Leave the swarm long: |- - When you run this command on a worker, that worker leaves the swarm. + When you run this command on a worker, that worker leaves the swarm. - You can use the `--force` option on a manager to remove it from the swarm. - However, this does not reconfigure the swarm to ensure that there are enough - managers to maintain a quorum in the swarm. The safe way to remove a manager - from a swarm is to demote it to a worker and then direct it to leave the quorum - without using `--force`. Only use `--force` in situations where the swarm will - no longer be used after the manager leaves, such as in a single-node swarm. + You can use the `--force` option on a manager to remove it from the swarm. + However, this does not reconfigure the swarm to ensure that there are enough + managers to maintain a quorum in the swarm. The safe way to remove a manager + from a swarm is to demote it to a worker and then direct it to leave the quorum + without using `--force`. Only use `--force` in situations where the swarm will + no longer be used after the manager leaves, such as in a single-node swarm. usage: docker swarm leave [OPTIONS] pname: docker swarm plink: docker_swarm.yaml options: -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Force this node to leave the swarm, ignoring warnings - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force this node to leave the swarm, ignoring warnings + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Consider the following swarm, as seen from the manager: + Consider the following swarm, as seen from the manager: - ```console - $ docker node ls + ```console + $ docker node ls - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 7ln70fl22uw2dvjn2ft53m3q5 worker2 Ready Active - dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active - dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader - ``` + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS + 7ln70fl22uw2dvjn2ft53m3q5 worker2 Ready Active + dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active + dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader + ``` - To remove `worker2`, issue the following command from `worker2` itself: + To remove `worker2`, issue the following command from `worker2` itself: - ```console - $ docker swarm leave + ```console + $ docker swarm leave - Node left the default swarm. - ``` + Node left the default swarm. + ``` - The node will still appear in the node list, and marked as `down`. It no longer - affects swarm operation, but a long list of `down` nodes can clutter the node - list. To remove an inactive node from the list, use the [`node rm`](node_rm.md) - command. + The node will still appear in the node list, and marked as `down`. It no longer + affects swarm operation, but a long list of `down` nodes can clutter the node + list. To remove an inactive node from the list, use the [`node rm`](node_rm.md) + command. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_swarm_unlock-key.yaml b/_data/engine-cli/docker_swarm_unlock-key.yaml index 8b4e03ac7c..6f014e5f82 100644 --- a/_data/engine-cli/docker_swarm_unlock-key.yaml +++ b/_data/engine-cli/docker_swarm_unlock-key.yaml @@ -1,88 +1,101 @@ command: docker swarm unlock-key short: Manage the unlock key long: |- - An unlock key is a secret key needed to unlock a manager after its Docker daemon - restarts. These keys are only used when the autolock feature is enabled for the - swarm. + An unlock key is a secret key needed to unlock a manager after its Docker daemon + restarts. These keys are only used when the autolock feature is enabled for the + swarm. - You can view or rotate the unlock key using `swarm unlock-key`. To view the key, - run the `docker swarm unlock-key` command without any arguments: + You can view or rotate the unlock key using `swarm unlock-key`. To view the key, + run the `docker swarm unlock-key` command without any arguments: - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker swarm unlock-key [OPTIONS] pname: docker swarm plink: docker_swarm.yaml options: -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display token - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rotate - value_type: bool - default_value: "false" - description: Rotate unlock key - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display token + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: rotate + value_type: bool + default_value: "false" + description: Rotate unlock key + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker swarm unlock-key + ```console + $ docker swarm unlock-key - To unlock a swarm manager after it restarts, run the `docker swarm unlock` - command and provide the following key: + To unlock a swarm manager after it restarts, run the `docker swarm unlock` + command and provide the following key: - SWMKEY-1-fySn8TY4w5lKcWcJPIpKufejh9hxx5KYwx6XZigx3Q4 + SWMKEY-1-fySn8TY4w5lKcWcJPIpKufejh9hxx5KYwx6XZigx3Q4 - Please remember to store this key in a password manager, since without it you - will not be able to restart the manager. - ``` + Please remember to store this key in a password manager, since without it you + will not be able to restart the manager. + ``` - Use the `--rotate` flag to rotate the unlock key to a new, randomly-generated - key: + Use the `--rotate` flag to rotate the unlock key to a new, randomly-generated + key: - ```console - $ docker swarm unlock-key --rotate + ```console + $ docker swarm unlock-key --rotate - Successfully rotated manager unlock key. + Successfully rotated manager unlock key. - To unlock a swarm manager after it restarts, run the `docker swarm unlock` - command and provide the following key: + To unlock a swarm manager after it restarts, run the `docker swarm unlock` + command and provide the following key: - SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 + SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 - Please remember to store this key in a password manager, since without it you - will not be able to restart the manager. - ``` + Please remember to store this key in a password manager, since without it you + will not be able to restart the manager. + ``` - The `-q` (or `--quiet`) flag only prints the key: + The `-q` (or `--quiet`) flag only prints the key: - ```console - $ docker swarm unlock-key -q + ```console + $ docker swarm unlock-key -q - SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 - ``` + SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 + ``` - ### `--rotate` + ### `--rotate` - This flag rotates the unlock key, replacing it with a new randomly-generated - key. The old unlock key will no longer be accepted. + This flag rotates the unlock key, replacing it with a new randomly-generated + key. The old unlock key will no longer be accepted. - ### `--quiet` + ### `--quiet` - Only print the unlock key, without instructions. + Only print the unlock key, without instructions. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_swarm_unlock.yaml b/_data/engine-cli/docker_swarm_unlock.yaml index 085a52ffb2..787c8a0ba4 100644 --- a/_data/engine-cli/docker_swarm_unlock.yaml +++ b/_data/engine-cli/docker_swarm_unlock.yaml @@ -1,25 +1,36 @@ command: docker swarm unlock short: Unlock swarm long: |- - Unlocks a locked manager using a user-supplied unlock key. This command must be - used to reactivate a manager after its Docker daemon restarts if the autolock - setting is turned on. The unlock key is printed at the time when autolock is - enabled, and is also available from the `docker swarm unlock-key` command. + Unlocks a locked manager using a user-supplied unlock key. This command must be + used to reactivate a manager after its Docker daemon restarts if the autolock + setting is turned on. The unlock key is printed at the time when autolock is + enabled, and is also available from the `docker swarm unlock-key` command. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker swarm unlock pname: docker swarm plink: docker_swarm.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker swarm unlock - Please enter unlock key: - ``` + ```console + $ docker swarm unlock + Please enter unlock key: + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_swarm_update.yaml b/_data/engine-cli/docker_swarm_update.yaml index bc7b45c69c..dc5325ceb9 100644 --- a/_data/engine-cli/docker_swarm_update.yaml +++ b/_data/engine-cli/docker_swarm_update.yaml @@ -1,86 +1,104 @@ command: docker swarm update short: Update the swarm long: |- - Updates a swarm with new parameter values. + Updates a swarm with new parameter values. - > **Note** - > - > This is a cluster management command, and must be executed on a swarm - > manager node. To learn about managers and workers, refer to the - > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the - > documentation. + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](/engine/swarm/) in the + > documentation. usage: docker swarm update [OPTIONS] pname: docker swarm plink: docker_swarm.yaml options: -- option: autolock - value_type: bool - default_value: "false" - description: Change manager autolocking setting (true|false) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cert-expiry - value_type: duration - default_value: 2160h0m0s - description: Validity period for node certificates (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dispatcher-heartbeat - value_type: duration - default_value: 5s - description: Dispatcher heartbeat period (ns|us|ms|s|m|h) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: external-ca - value_type: external-ca - description: Specifications of one or more certificate signing endpoints - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: max-snapshots - value_type: uint64 - default_value: "0" - description: Number of additional Raft snapshots to retain - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: snapshot-interval - value_type: uint64 - default_value: "10000" - description: Number of log entries between Raft snapshots - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: task-history-limit - value_type: int64 - default_value: "5" - description: Task history retention limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: autolock + value_type: bool + default_value: "false" + description: Change manager autolocking setting (true|false) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cert-expiry + value_type: duration + default_value: 2160h0m0s + description: Validity period for node certificates (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: dispatcher-heartbeat + value_type: duration + default_value: 5s + description: Dispatcher heartbeat period (ns|us|ms|s|m|h) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: external-ca + value_type: external-ca + description: Specifications of one or more certificate signing endpoints + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: max-snapshots + value_type: uint64 + default_value: "0" + description: Number of additional Raft snapshots to retain + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: snapshot-interval + value_type: uint64 + default_value: "10000" + description: Number of log entries between Raft snapshots + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: task-history-limit + value_type: int64 + default_value: "5" + description: Task history retention limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker swarm update --cert-expiry 720h - ``` + ```console + $ docker swarm update --cert-expiry 720h + ``` deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_system.yaml b/_data/engine-cli/docker_system.yaml index a1bc57fcf2..d5121c0f52 100644 --- a/_data/engine-cli/docker_system.yaml +++ b/_data/engine-cli/docker_system.yaml @@ -5,15 +5,26 @@ usage: docker system pname: docker plink: docker.yaml cname: -- docker system df -- docker system events -- docker system info -- docker system prune + - docker system df + - docker system events + - docker system info + - docker system prune clink: -- docker_system_df.yaml -- docker_system_events.yaml -- docker_system_info.yaml -- docker_system_prune.yaml + - docker_system_df.yaml + - docker_system_events.yaml + - docker_system_info.yaml + - docker_system_prune.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_system_df.yaml b/_data/engine-cli/docker_system_df.yaml index 4ee148945f..bb3302c843 100644 --- a/_data/engine-cli/docker_system_df.yaml +++ b/_data/engine-cli/docker_system_df.yaml @@ -1,76 +1,95 @@ command: docker system df short: Show docker disk usage long: |- - The `docker system df` command displays information regarding the - amount of disk space used by the docker daemon. + The `docker system df` command displays information regarding the + amount of disk space used by the docker daemon. usage: docker system df [OPTIONS] pname: docker system plink: docker_system.yaml options: -- option: format - value_type: string - description: Pretty-print images using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: verbose - shorthand: v - value_type: bool - default_value: "false" - description: Show detailed information on space usage - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: verbose + shorthand: v + value_type: bool + default_value: "false" + description: Show detailed information on space usage + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - By default the command will just show a summary of the data used: + By default the command will just show a summary of the data used: - ```console - $ docker system df + ```console + $ docker system df - TYPE TOTAL ACTIVE SIZE RECLAIMABLE - Images 5 2 16.43 MB 11.63 MB (70%) - Containers 2 0 212 B 212 B (100%) - Local Volumes 2 1 36 B 0 B (0%) - ``` + TYPE TOTAL ACTIVE SIZE RECLAIMABLE + Images 5 2 16.43 MB 11.63 MB (70%) + Containers 2 0 212 B 212 B (100%) + Local Volumes 2 1 36 B 0 B (0%) + ``` - A more detailed view can be requested using the `-v, --verbose` flag: + A more detailed view can be requested using the `-v, --verbose` flag: - ```console - $ docker system df -v + ```console + $ docker system df -v - Images space usage: + Images space usage: - REPOSITORY TAG IMAGE ID CREATED SIZE SHARED SIZE UNIQUE SIZE CONTAINERS - my-curl latest b2789dd875bf 6 minutes ago 11 MB 11 MB 5 B 0 - my-jq latest ae67841be6d0 6 minutes ago 9.623 MB 8.991 MB 632.1 kB 0 - a0971c4015c1 6 minutes ago 11 MB 11 MB 0 B 0 - alpine latest 4e38e38c8ce0 9 weeks ago 4.799 MB 0 B 4.799 MB 1 - alpine 3.3 47cf20d8c26c 9 weeks ago 4.797 MB 4.797 MB 0 B 1 + REPOSITORY TAG IMAGE ID CREATED SIZE SHARED SIZE UNIQUE SIZE CONTAINERS + my-curl latest b2789dd875bf 6 minutes ago 11 MB 11 MB 5 B 0 + my-jq latest ae67841be6d0 6 minutes ago 9.623 MB 8.991 MB 632.1 kB 0 + a0971c4015c1 6 minutes ago 11 MB 11 MB 0 B 0 + alpine latest 4e38e38c8ce0 9 weeks ago 4.799 MB 0 B 4.799 MB 1 + alpine 3.3 47cf20d8c26c 9 weeks ago 4.797 MB 4.797 MB 0 B 1 - Containers space usage: + Containers space usage: - CONTAINER ID IMAGE COMMAND LOCAL VOLUMES SIZE CREATED STATUS NAMES - 4a7f7eebae0f alpine:latest "sh" 1 0 B 16 minutes ago Exited (0) 5 minutes ago hopeful_yalow - f98f9c2aa1ea alpine:3.3 "sh" 1 212 B 16 minutes ago Exited (0) 48 seconds ago anon-vol + CONTAINER ID IMAGE COMMAND LOCAL VOLUMES SIZE CREATED STATUS NAMES + 4a7f7eebae0f alpine:latest "sh" 1 0 B 16 minutes ago Exited (0) 5 minutes ago hopeful_yalow + f98f9c2aa1ea alpine:3.3 "sh" 1 212 B 16 minutes ago Exited (0) 48 seconds ago anon-vol - Local Volumes space usage: + Local Volumes space usage: - NAME LINKS SIZE - 07c7bdf3e34ab76d921894c2b834f073721fccfbbcba792aa7648e3a7a664c2e 2 36 B - my-named-vol 0 0 B - ``` + NAME LINKS SIZE + 07c7bdf3e34ab76d921894c2b834f073721fccfbbcba792aa7648e3a7a664c2e 2 36 B + my-named-vol 0 0 B + ``` - * `SHARED SIZE` is the amount of space that an image shares with another one (i.e. their common data) - * `UNIQUE SIZE` is the amount of space that is only used by a given image - * `SIZE` is the virtual size of the image, it is the sum of `SHARED SIZE` and `UNIQUE SIZE` + * `SHARED SIZE` is the amount of space that an image shares with another one (i.e. their common data) + * `UNIQUE SIZE` is the amount of space that is only used by a given image + * `SIZE` is the virtual size of the image, it is the sum of `SHARED SIZE` and `UNIQUE SIZE` - > **Note** - > - > Network information is not shown because it does not consume disk space. + > **Note** + > + > Network information is not shown because it does not consume disk space. deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_system_dial-stdio.yaml b/_data/engine-cli/docker_system_dial-stdio.yaml new file mode 100644 index 0000000000..d63f5d14ef --- /dev/null +++ b/_data/engine-cli/docker_system_dial-stdio.yaml @@ -0,0 +1,25 @@ +command: docker system dial-stdio +short: | + Proxy the stdio stream to the daemon connection. Should not be invoked manually. +long: | + Proxy the stdio stream to the daemon connection. Should not be invoked manually. +usage: docker system dial-stdio +pname: docker system +plink: docker_system.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_system_events.yaml b/_data/engine-cli/docker_system_events.yaml index 590218642f..57f5042da7 100644 --- a/_data/engine-cli/docker_system_events.yaml +++ b/_data/engine-cli/docker_system_events.yaml @@ -1,356 +1,373 @@ command: docker system events +aliases: docker system events, docker events short: Get real time events from the server long: |- - Use `docker system events` to get real-time events from the server. These - events differ per Docker object type. + Use `docker system events` to get real-time events from the server. These + events differ per Docker object type. - ### Object types + ### Object types - #### Containers + #### Containers - Docker containers report the following events: + Docker containers report the following events: - - `attach` - - `commit` - - `copy` - - `create` - - `destroy` - - `detach` - - `die` - - `exec_create` - - `exec_detach` - - `exec_die` - - `exec_start` - - `export` - - `health_status` - - `kill` - - `oom` - - `pause` - - `rename` - - `resize` - - `restart` - - `start` - - `stop` - - `top` - - `unpause` - - `update` + - `attach` + - `commit` + - `copy` + - `create` + - `destroy` + - `detach` + - `die` + - `exec_create` + - `exec_detach` + - `exec_die` + - `exec_start` + - `export` + - `health_status` + - `kill` + - `oom` + - `pause` + - `rename` + - `resize` + - `restart` + - `start` + - `stop` + - `top` + - `unpause` + - `update` - #### Images + #### Images - Docker images report the following events: + Docker images report the following events: - - `delete` - - `import` - - `load` - - `pull` - - `push` - - `save` - - `tag` - - `untag` + - `delete` + - `import` + - `load` + - `pull` + - `push` + - `save` + - `tag` + - `untag` - #### Plugins + #### Plugins - Docker plugins report the following events: + Docker plugins report the following events: - - `install` - - `enable` - - `disable` - - `remove` + - `install` + - `enable` + - `disable` + - `remove` - #### Volumes + #### Volumes - Docker volumes report the following events: + Docker volumes report the following events: - - `create` - - `mount` - - `unmount` - - `destroy` + - `create` + - `mount` + - `unmount` + - `destroy` - #### Networks + #### Networks - Docker networks report the following events: + Docker networks report the following events: - - `create` - - `connect` - - `disconnect` - - `destroy` + - `create` + - `connect` + - `disconnect` + - `destroy` - #### Daemons + #### Daemons - Docker daemons report the following events: + Docker daemons report the following events: - - `reload` + - `reload` - ### Limiting, filtering, and formatting the output + ### Limiting, filtering, and formatting the output - #### Limit events by time + #### Limit events by time - The `--since` and `--until` parameters can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed - relative to the client machine’s time. If you do not provide the `--since` option, - the command returns only new and/or live events. Supported formats for date - formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local - timezone on the client will be used if you do not provide either a `Z` or a - `+-00:00` timezone offset at the end of the timestamp. When providing Unix - timestamps enter seconds[.nanoseconds], where seconds is the number of seconds - that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap - seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a - fraction of a second no more than nine digits long. + The `--since` and `--until` parameters can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the client machine’s time. If you do not provide the `--since` option, + the command returns only new and/or live events. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the client will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. - #### Filtering (--filter) + #### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--filter`) format is of "key=value". If you would - like to use multiple filters, pass multiple flags (e.g., - `--filter "foo=bar" --filter "bif=baz"`) + The filtering flag (`-f` or `--filter`) format is of "key=value". If you would + like to use multiple filters, pass multiple flags (e.g., + `--filter "foo=bar" --filter "bif=baz"`) - Using the same filter multiple times will be handled as a *OR*; for example - `--filter container=588a23dac085 --filter container=a8f7720b8c22` will display - events for container 588a23dac085 *OR* container a8f7720b8c22 + Using the same filter multiple times will be handled as a *OR*; for example + `--filter container=588a23dac085 --filter container=a8f7720b8c22` will display + events for container 588a23dac085 *OR* container a8f7720b8c22 - Using multiple filters will be handled as a *AND*; for example - `--filter container=588a23dac085 --filter event=start` will display events for - container container 588a23dac085 *AND* the event type is *start* + Using multiple filters will be handled as a *AND*; for example + `--filter container=588a23dac085 --filter event=start` will display events for + container container 588a23dac085 *AND* the event type is *start* - The currently supported filters are: + The currently supported filters are: - * container (`container=`) - * daemon (`daemon=`) - * event (`event=`) - * image (`image=`) - * label (`label=` or `label==`) - * network (`network=`) - * plugin (`plugin=`) - * type (`type=`) - * volume (`volume=`) + * container (`container=`) + * daemon (`daemon=`) + * event (`event=`) + * image (`image=`) + * label (`label=` or `label==`) + * network (`network=`) + * plugin (`plugin=`) + * type (`type=`) + * volume (`volume=`) usage: docker system events [OPTIONS] pname: docker system plink: docker_system.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Filter output based on conditions provided - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: since - value_type: string - description: Show all events created since timestamp - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: until - value_type: string - description: Stream events until this timestamp - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: filter + shorthand: f + value_type: filter + description: Filter output based on conditions provided + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: Format the output using the given Go template + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: since + value_type: string + description: Show all events created since timestamp + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: until + value_type: string + description: Stream events until this timestamp + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Basic example + ### Basic example - You'll need two shells for this example. + You'll need two shells for this example. - **Shell 1: Listening for events:** + **Shell 1: Listening for events:** - ```console - $ docker system events - ``` + ```console + $ docker system events + ``` - **Shell 2: Start and Stop containers:** + **Shell 2: Start and Stop containers:** - ```console - $ docker create --name test alpine:latest top - $ docker start test - $ docker stop test - ``` + ```console + $ docker create --name test alpine:latest top + $ docker start test + $ docker stop test + ``` - **Shell 1: (Again .. now showing events):** + **Shell 1: (Again .. now showing events):** - ```console - 2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - ``` + ```console + 2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + ``` - To exit the `docker system events` command, use `CTRL+C`. + To exit the `docker system events` command, use `CTRL+C`. - ### Filter events by time + ### Filter events by time - You can filter the output by an absolute timestamp or relative time on the host - machine, using the following different time syntaxes: + You can filter the output by an absolute timestamp or relative time on the host + machine, using the following different time syntaxes: - ```console - $ docker system events --since 1483283804 + ```console + $ docker system events --since 1483283804 - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker system events --since '2017-01-05' + $ docker system events --since '2017-01-05' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker system events --since '2013-09-03T15:49:29' + $ docker system events --since '2013-09-03T15:49:29' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker system events --since '10m' + $ docker system events --since '10m' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - ``` + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + ``` - ### Filter events by criteria + ### Filter events by criteria - The following commands show several different ways to filter the `docker event` - output. + The following commands show several different ways to filter the `docker event` + output. - ```console - $ docker system events --filter 'event=stop' + ```console + $ docker system events --filter 'event=stop' - 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain) + 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain) - $ docker system events --filter 'image=alpine' + $ docker system events --filter 'image=alpine' - 2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15) - 2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9) - 2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner) - 2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15) + 2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9) + 2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner) + 2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner) - $ docker system events --filter 'container=test' + $ docker system events --filter 'container=test' - 2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker system events --filter 'container=test' --filter 'container=d9cdb1525ea8' + $ docker system events --filter 'container=test' --filter 'container=d9cdb1525ea8' - 2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9) - 2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test) - 2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9) + 2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test) + 2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test) - $ docker system events --filter 'container=test' --filter 'event=stop' + $ docker system events --filter 'container=test' --filter 'event=stop' - 2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) + 2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) - $ docker system events --filter 'type=volume' + $ docker system events --filter 'type=volume' - 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) - 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate) - 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local) - 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) + 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) + 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate) + 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local) + 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) - $ docker system events --filter 'type=network' + $ docker system events --filter 'type=network' - 2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge) - 2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge) + 2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge) + 2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge) - $ docker system events --filter 'container=container_1' --filter 'container=container_2' + $ docker system events --filter 'container=container_1' --filter 'container=container_2' - 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04 ) - 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04 ) - 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) - 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) + 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04 ) + 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04 ) + 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) + 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) - $ docker system events --filter 'type=volume' + $ docker system events --filter 'type=volume' - 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) - 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate) - 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local) - 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) + 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) + 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate) + 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local) + 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) - $ docker system events --filter 'type=network' + $ docker system events --filter 'type=network' - 2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge) - 2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge) + 2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge) + 2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge) - $ docker system events --filter 'type=plugin' + $ docker system events --filter 'type=plugin' - 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) - 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) - ``` + 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) + 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - If a format (`--format`) is specified, the given template will be executed - instead of the default format. Go's [text/template](https://golang.org/pkg/text/template/) - package describes all the details of the format. + If a format (`--format`) is specified, the given template will be executed + instead of the default format. Go's [text/template](https://golang.org/pkg/text/template/) + package describes all the details of the format. - ```console - $ docker system events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' + ```console + $ docker system events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' - Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - ``` + Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + ``` - #### Format as JSON + #### Format as JSON - If a format is set to `{{json .}}`, the events are streamed as valid JSON - Lines. For information about JSON Lines, please refer to https://jsonlines.org/ . + If a format is set to `{{json .}}`, the events are streamed as valid JSON + Lines. For information about JSON Lines, please refer to https://jsonlines.org/ . - ```console - $ docker system events --format '{{json .}}' + ```console + $ docker system events --format '{{json .}}' - {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. - {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. - {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. - {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. - {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. - ``` + {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. + {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. + {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_system_info.yaml b/_data/engine-cli/docker_system_info.yaml index 9662751bf0..ef5bda5ddb 100644 --- a/_data/engine-cli/docker_system_info.yaml +++ b/_data/engine-cli/docker_system_info.yaml @@ -1,19 +1,32 @@ command: docker system info +aliases: docker system info, docker info short: Display system-wide information long: Display system-wide information usage: docker system info [OPTIONS] pname: docker system plink: docker_system.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: Format the output using the given Go template + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_system_prune.yaml b/_data/engine-cli/docker_system_prune.yaml index 2a1f78ba42..5c02f27100 100644 --- a/_data/engine-cli/docker_system_prune.yaml +++ b/_data/engine-cli/docker_system_prune.yaml @@ -1,148 +1,164 @@ command: docker system prune short: Remove unused data long: |- - Remove all unused containers, networks, images (both dangling and unreferenced), - and optionally, volumes. + Remove all unused containers, networks, images (both dangling and unreferenced), + and optionally, volumes. usage: docker system prune [OPTIONS] pname: docker system plink: docker_system.yaml options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Remove all unused images not just dangling ones - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: filter - value_type: filter - description: Provide filter values (e.g. 'label==') - deprecated: false - min_api_version: "1.28" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Do not prompt for confirmation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: volumes - value_type: bool - default_value: "false" - description: Prune volumes - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: all + shorthand: a + value_type: bool + default_value: "false" + description: Remove all unused images not just dangling ones + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: filter + value_type: filter + description: Provide filter values (e.g. `label==`) + details_url: '#filter' + deprecated: false + hidden: false + min_api_version: "1.28" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Do not prompt for confirmation + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volumes + value_type: bool + default_value: "false" + description: Prune volumes + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker system prune + ```console + $ docker system prune - WARNING! This will remove: - - all stopped containers - - all networks not used by at least one container - - all dangling images - - all build cache - Are you sure you want to continue? [y/N] y + WARNING! This will remove: + - all stopped containers + - all networks not used by at least one container + - all dangling images + - all build cache + Are you sure you want to continue? [y/N] y - Deleted Containers: - f44f9b81948b3919590d5f79a680d8378f1139b41952e219830a33027c80c867 - 792776e68ac9d75bce4092bc1b5cc17b779bc926ab04f4185aec9bf1c0d4641f + Deleted Containers: + f44f9b81948b3919590d5f79a680d8378f1139b41952e219830a33027c80c867 + 792776e68ac9d75bce4092bc1b5cc17b779bc926ab04f4185aec9bf1c0d4641f - Deleted Networks: - network1 - network2 + Deleted Networks: + network1 + network2 - Deleted Images: - untagged: hello-world@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f - deleted: sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57 - deleted: sha256:45761469c965421a92a69cc50e92c01e0cfa94fe026cdd1233445ea00e96289a + Deleted Images: + untagged: hello-world@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f + deleted: sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57 + deleted: sha256:45761469c965421a92a69cc50e92c01e0cfa94fe026cdd1233445ea00e96289a - Total reclaimed space: 1.84kB - ``` + Total reclaimed space: 1.84kB + ``` - By default, volumes are not removed to prevent important data from being - deleted if there is currently no container using the volume. Use the `--volumes` - flag when running the command to prune volumes as well: + By default, volumes are not removed to prevent important data from being + deleted if there is currently no container using the volume. Use the `--volumes` + flag when running the command to prune volumes as well: - ```console - $ docker system prune -a --volumes + ```console + $ docker system prune -a --volumes - WARNING! This will remove: - - all stopped containers - - all networks not used by at least one container - - all volumes not used by at least one container - - all images without at least one container associated to them - - all build cache - Are you sure you want to continue? [y/N] y + WARNING! This will remove: + - all stopped containers + - all networks not used by at least one container + - all volumes not used by at least one container + - all images without at least one container associated to them + - all build cache + Are you sure you want to continue? [y/N] y - Deleted Containers: - 0998aa37185a1a7036b0e12cf1ac1b6442dcfa30a5c9650a42ed5010046f195b - 73958bfb884fa81fa4cc6baf61055667e940ea2357b4036acbbe25a60f442a4d + Deleted Containers: + 0998aa37185a1a7036b0e12cf1ac1b6442dcfa30a5c9650a42ed5010046f195b + 73958bfb884fa81fa4cc6baf61055667e940ea2357b4036acbbe25a60f442a4d - Deleted Networks: - my-network-a - my-network-b + Deleted Networks: + my-network-a + my-network-b - Deleted Volumes: - named-vol + Deleted Volumes: + named-vol - Deleted Images: - untagged: my-curl:latest - deleted: sha256:7d88582121f2a29031d92017754d62a0d1a215c97e8f0106c586546e7404447d - deleted: sha256:dd14a93d83593d4024152f85d7c63f76aaa4e73e228377ba1d130ef5149f4d8b - untagged: alpine:3.3 - deleted: sha256:695f3d04125db3266d4ab7bbb3c6b23aa4293923e762aa2562c54f49a28f009f - untagged: alpine:latest - deleted: sha256:ee4603260daafe1a8c2f3b78fd760922918ab2441cbb2853ed5c439e59c52f96 - deleted: sha256:9007f5987db353ec398a223bc5a135c5a9601798ba20a1abba537ea2f8ac765f - deleted: sha256:71fa90c8f04769c9721459d5aa0936db640b92c8c91c9b589b54abd412d120ab - deleted: sha256:bb1c3357b3c30ece26e6604aea7d2ec0ace4166ff34c3616701279c22444c0f3 - untagged: my-jq:latest - deleted: sha256:6e66d724542af9bc4c4abf4a909791d7260b6d0110d8e220708b09e4ee1322e1 - deleted: sha256:07b3fa89d4b17009eb3988dfc592c7d30ab3ba52d2007832dffcf6d40e3eda7f - deleted: sha256:3a88a5c81eb5c283e72db2dbc6d65cbfd8e80b6c89bb6e714cfaaa0eed99c548 + Deleted Images: + untagged: my-curl:latest + deleted: sha256:7d88582121f2a29031d92017754d62a0d1a215c97e8f0106c586546e7404447d + deleted: sha256:dd14a93d83593d4024152f85d7c63f76aaa4e73e228377ba1d130ef5149f4d8b + untagged: alpine:3.3 + deleted: sha256:695f3d04125db3266d4ab7bbb3c6b23aa4293923e762aa2562c54f49a28f009f + untagged: alpine:latest + deleted: sha256:ee4603260daafe1a8c2f3b78fd760922918ab2441cbb2853ed5c439e59c52f96 + deleted: sha256:9007f5987db353ec398a223bc5a135c5a9601798ba20a1abba537ea2f8ac765f + deleted: sha256:71fa90c8f04769c9721459d5aa0936db640b92c8c91c9b589b54abd412d120ab + deleted: sha256:bb1c3357b3c30ece26e6604aea7d2ec0ace4166ff34c3616701279c22444c0f3 + untagged: my-jq:latest + deleted: sha256:6e66d724542af9bc4c4abf4a909791d7260b6d0110d8e220708b09e4ee1322e1 + deleted: sha256:07b3fa89d4b17009eb3988dfc592c7d30ab3ba52d2007832dffcf6d40e3eda7f + deleted: sha256:3a88a5c81eb5c283e72db2dbc6d65cbfd8e80b6c89bb6e714cfaaa0eed99c548 - Total reclaimed space: 13.5 MB - ``` + Total reclaimed space: 13.5 MB + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - 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 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: + The currently supported filters are: - * until (``) - only remove containers, images, and networks created before given timestamp - * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove containers, images, networks, and volumes with (or without, in case `label!=...` is used) the specified labels. + * until (``) - only remove containers, images, and networks created before given timestamp + * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove containers, images, networks, and volumes with (or without, in case `label!=...` is used) the specified labels. - The `until` filter can be Unix timestamps, date formatted - timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed - relative to the daemon machine’s time. Supported formats for date - formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local - timezone on the daemon will be used if you do not provide either a `Z` or a - `+-00:00` timezone offset at the end of the timestamp. When providing Unix - timestamps enter seconds[.nanoseconds], where seconds is the number of seconds - that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap - seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a - fraction of a second no more than nine digits long. + The `until` filter can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the daemon machine’s time. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the daemon will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. - The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), - which removes containers, images, networks, and volumes with the specified labels. The other - format is the `label!=...` (`label!=` or `label!==`), which removes - containers, images, networks, and volumes without the specified labels. + The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), + which removes containers, images, networks, and volumes with the specified labels. The other + format is the `label!=...` (`label!=` or `label!==`), which removes + containers, images, networks, and volumes without the specified labels. deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_tag.yaml b/_data/engine-cli/docker_tag.yaml index 786bba5bdc..4d34bfc413 100644 --- a/_data/engine-cli/docker_tag.yaml +++ b/_data/engine-cli/docker_tag.yaml @@ -1,63 +1,75 @@ command: docker tag +aliases: docker image tag, docker tag short: Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE long: |- - An image name is made up of slash-separated name components, optionally prefixed - by a registry hostname. The hostname must comply with standard DNS rules, but - may not contain underscores. If a hostname is present, it may optionally be - followed by a port number in the format `:8080`. If not present, the command - uses Docker's public registry located at `registry-1.docker.io` by default. Name - components may contain lowercase letters, digits and separators. A separator - is defined as a period, one or two underscores, or one or more dashes. A name - component may not start or end with a separator. + An image name is made up of slash-separated name components, optionally prefixed + by a registry hostname. The hostname must comply with standard DNS rules, but + may not contain underscores. If a hostname is present, it may optionally be + followed by a port number in the format `:8080`. If not present, the command + uses Docker's public registry located at `registry-1.docker.io` by default. Name + components may contain lowercase letters, digits and separators. A separator + is defined as a period, one or two underscores, or one or more hyphens. A name + component may not start or end with a separator. - A tag name must be valid ASCII and may contain lowercase and uppercase letters, - digits, underscores, periods and dashes. A tag name may not start with a - period or a dash and may contain a maximum of 128 characters. + A tag name must be valid ASCII and may contain lowercase and uppercase letters, + digits, underscores, periods and hyphens. A tag name may not start with a + period or a hyphen and may contain a maximum of 128 characters. - You can group your images together using names and tags, and then upload them - to [*Share images on Docker Hub*](https://docs.docker.com/get-started/part3/). + You can group your images together using names and tags, and then upload them + to [*Share images on Docker Hub*](/get-started/part3/). usage: docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] pname: docker plink: docker.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Tag an image referenced by ID + ### Tag an image referenced by ID - To tag a local image with ID "0e5574283393" into the "fedora" repository with - "version1.0": + To tag a local image with ID "0e5574283393" into the "fedora" repository with + "version1.0": - ```console - $ docker tag 0e5574283393 fedora/httpd:version1.0 - ``` + ```console + $ docker tag 0e5574283393 fedora/httpd:version1.0 + ``` - ### Tag an image referenced by Name + ### Tag an image referenced by Name - To tag a local image with name "httpd" into the "fedora" repository with - "version1.0": + To tag a local image with name "httpd" into the "fedora" repository with + "version1.0": - ```console - $ docker tag httpd fedora/httpd:version1.0 - ``` + ```console + $ docker tag httpd fedora/httpd:version1.0 + ``` - Note that since the tag name is not specified, the alias is created for an - existing local version `httpd:latest`. + Note that since the tag name is not specified, the alias is created for an + existing local version `httpd:latest`. - ### Tag an image referenced by Name and Tag + ### Tag an image referenced by Name and Tag - To tag a local image with name "httpd" and tag "test" into the "fedora" - repository with "version1.0.test": + To tag a local image with name "httpd" and tag "test" into the "fedora" + repository with "version1.0.test": - ```console - $ docker tag httpd:test fedora/httpd:version1.0.test - ``` + ```console + $ docker tag httpd:test fedora/httpd:version1.0.test + ``` - ### Tag an image for a private repository + ### Tag an image for a private repository - To push an image to a private registry and not the central Docker - registry you must tag it with the registry hostname and port (if needed). + To push an image to a private registry and not the central Docker + registry you must tag it with the registry hostname and port (if needed). - ```console - $ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 - ``` + ```console + $ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_top.yaml b/_data/engine-cli/docker_top.yaml index 100de43b61..754c86ec70 100644 --- a/_data/engine-cli/docker_top.yaml +++ b/_data/engine-cli/docker_top.yaml @@ -1,9 +1,21 @@ command: docker top +aliases: docker container top, docker top short: Display the running processes of a container long: Display the running processes of a container usage: docker top CONTAINER [ps OPTIONS] pname: docker plink: docker.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust.yaml b/_data/engine-cli/docker_trust.yaml index d3219d7407..1780fa76ce 100644 --- a/_data/engine-cli/docker_trust.yaml +++ b/_data/engine-cli/docker_trust.yaml @@ -5,17 +5,28 @@ usage: docker trust pname: docker plink: docker.yaml cname: -- docker trust inspect -- docker trust key -- docker trust revoke -- docker trust sign -- docker trust signer + - docker trust inspect + - docker trust key + - docker trust revoke + - docker trust sign + - docker trust signer clink: -- docker_trust_inspect.yaml -- docker_trust_key.yaml -- docker_trust_revoke.yaml -- docker_trust_sign.yaml -- docker_trust_signer.yaml + - docker_trust_inspect.yaml + - docker_trust_key.yaml + - docker_trust_revoke.yaml + - docker_trust_sign.yaml + - docker_trust_signer.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_inspect.yaml b/_data/engine-cli/docker_trust_inspect.yaml index 69340f42ea..673307eae1 100644 --- a/_data/engine-cli/docker_trust_inspect.yaml +++ b/_data/engine-cli/docker_trust_inspect.yaml @@ -1,487 +1,499 @@ command: docker trust inspect short: Return low-level information about keys and signatures long: |- - `docker trust inspect` provides low-level JSON information on signed repositories. - This includes all image tags that are signed, who signed them, and who can sign - new tags. + `docker trust inspect` provides low-level JSON information on signed repositories. + This includes all image tags that are signed, who signed them, and who can sign + new tags. usage: docker trust inspect IMAGE[:TAG] [IMAGE[:TAG]...] pname: docker trust plink: docker_trust.yaml options: -- option: pretty - value_type: bool - default_value: "false" - description: Print the information in a human friendly format - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: pretty + value_type: bool + default_value: "false" + description: Print the information in a human friendly format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Get low-level details about signatures for a single image tag + ### Get low-level details about signatures for a single image tag - Use the `docker trust inspect` to get trust information about an image. The - following example prints trust information for the `alpine:latest` image: + Use the `docker trust inspect` to get trust information about an image. The + following example prints trust information for the `alpine:latest` image: - ```console - $ docker trust inspect alpine:latest - ``` + ```console + $ docker trust inspect alpine:latest + ``` - The output is in JSON format, for example: + The output is in JSON format, for example: - ```json - [ - { - "Name": "alpine:latest", - "SignedTags": [ - { - "SignedTag": "latest", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - } - ], - "Signers": [], - "AdministrativeKeys": [ - { - "Name": "Repository", - "Keys": [ + ```json + [ + { + "Name": "alpine:latest", + "SignedTags": [ + { + "SignedTag": "latest", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" + ] + } + ], + "Signers": [], + "AdministrativeKeys": [ + { + "Name": "Repository", + "Keys": [ + { + "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" + } + ] + }, + { + "Name": "Root", + "Keys": [ + { + "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" + } + ] + } + ] + } + ] + ``` + + The `SignedTags` key will list the `SignedTag` name, its `Digest`, + and the `Signers` responsible for the signature. + + `AdministrativeKeys` will list the `Repository` and `Root` keys. + + If signers are set up for the repository via other `docker trust` + commands, `docker trust inspect` includes a `Signers` key: + + ```console + $ docker trust inspect my-image:purple + ``` + + The output is in JSON format, for example: + + ```json + [ + { + "Name": "my-image:purple", + "SignedTags": [ + { + "SignedTag": "purple", + "Digest": "941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557", + "Signers": [ + "alice", + "bob", + "carol" + ] + } + ], + "Signers": [ + { + "Name": "alice", + "Keys": [ + { + "ID": "04dd031411ed671ae1e12f47ddc8646d98f135090b01e54c3561e843084484a3" + }, + { + "ID": "6a11e4898a4014d400332ab0e096308c844584ff70943cdd1d6628d577f45fd8" + } + ] + }, + { + "Name": "bob", + "Keys": [ + { + "ID": "433e245c656ae9733cdcc504bfa560f90950104442c4528c9616daa45824ccba" + } + ] + }, + { + "Name": "carol", + "Keys": [ + { + "ID": "d32fa8b5ca08273a2880f455fcb318da3dc80aeae1a30610815140deef8f30d9" + }, + { + "ID": "9a8bbec6ba2af88a5fad6047d428d17e6d05dbdd03d15b4fc8a9a0e8049cd606" + } + ] + } + ], + "AdministrativeKeys": [ + { + "Name": "Repository", + "Keys": [ + { + "ID": "27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44" + } + ] + }, + { + "Name": "Root", + "Keys": [ + { + "ID": "40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f" + } + ] + } + ] + } + ] + ``` + + If the image tag is unsigned or unavailable, `docker trust inspect` does not + display any signed tags. + + ```console + $ docker trust inspect unsigned-img + + no signatures or cannot access unsigned-img + ``` + + However, if other tags are signed in the same image repository, + `docker trust inspect` reports relevant key information: + + ```console + $ docker trust inspect alpine:unsigned + ``` + + The output is in JSON format, for example: + + ```json + [ + { + "Name": "alpine:unsigned", + "Signers": [], + "AdministrativeKeys": [ + { + "Name": "Repository", + "Keys": [ { - "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" + "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" } - ] - }, - { - "Name": "Root", - "Keys": [ + ] + }, + { + "Name": "Root", + "Keys": [ { - "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" + "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" } - ] - } - ] - } - ] - ``` + ] + } + ] + } + ] + ``` - The `SignedTags` key will list the `SignedTag` name, its `Digest`, - and the `Signers` responsible for the signature. + ### Get details about signatures for all image tags in a repository - `AdministrativeKeys` will list the `Repository` and `Root` keys. + If no tag is specified, `docker trust inspect` will report details for all + signed tags in the repository: - If signers are set up for the repository via other `docker trust` - commands, `docker trust inspect` includes a `Signers` key: + ```console + $ docker trust inspect alpine + ``` - ```console - $ docker trust inspect my-image:purple - ``` + The output is in JSON format, for example: - The output is in JSON format, for example: - - ```json - [ - { - "Name": "my-image:purple", - "SignedTags": [ - { - "SignedTag": "purple", - "Digest": "941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557", - "Signers": [ - "alice", - "bob", - "carol" - ] - } - ], - "Signers": [ - { - "Name": "alice", - "Keys": [ + ```json + [ + { + "Name": "alpine", + "SignedTags": [ + { + "SignedTag": "3.5", + "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "3.6", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "edge", + "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "latest", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" + ] + } + ], + "Signers": [], + "AdministrativeKeys": [ + { + "Name": "Repository", + "Keys": [ { - "ID": "04dd031411ed671ae1e12f47ddc8646d98f135090b01e54c3561e843084484a3" - }, - { - "ID": "6a11e4898a4014d400332ab0e096308c844584ff70943cdd1d6628d577f45fd8" + "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" } - ] - }, - { - "Name": "bob", - "Keys": [ + ] + }, + { + "Name": "Root", + "Keys": [ { - "ID": "433e245c656ae9733cdcc504bfa560f90950104442c4528c9616daa45824ccba" + "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" } - ] - }, - { - "Name": "carol", - "Keys": [ + ] + } + ] + } + ] + ``` + + + ### Get details about signatures for multiple images + + `docker trust inspect` can take multiple repositories and images as arguments, + and reports the results in an ordered list: + + ```console + $ docker trust inspect alpine notary + ``` + + The output is in JSON format, for example: + + ```json + [ + { + "Name": "alpine", + "SignedTags": [ + { + "SignedTag": "3.5", + "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "3.6", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "edge", + "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "integ-test-base", + "Digest": "3952dc48dcc4136ccdde37fbef7e250346538a55a0366e3fccc683336377e372", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "latest", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" + ] + } + ], + "Signers": [], + "AdministrativeKeys": [ + { + "Name": "Repository", + "Keys": [ { - "ID": "d32fa8b5ca08273a2880f455fcb318da3dc80aeae1a30610815140deef8f30d9" - }, - { - "ID": "9a8bbec6ba2af88a5fad6047d428d17e6d05dbdd03d15b4fc8a9a0e8049cd606" + "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" } - ] - } - ], - "AdministrativeKeys": [ - { - "Name": "Repository", - "Keys": [ + ] + }, + { + "Name": "Root", + "Keys": [ { - "ID": "27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44" + "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" } - ] - }, - { - "Name": "Root", - "Keys": [ + ] + } + ] + }, + { + "Name": "notary", + "SignedTags": [ + { + "SignedTag": "server", + "Digest": "71f64ab718a3331dee103bc5afc6bc492914738ce37c2d2f127a8133714ecf5c", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "signer", + "Digest": "a6122d79b1e74f70b5dd933b18a6d1f99329a4728011079f06b245205f158fe8", + "Signers": [ + "Repo Admin" + ] + } + ], + "Signers": [], + "AdministrativeKeys": [ + { + "Name": "Root", + "Keys": [ { - "ID": "40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f" + "ID": "8cdcdef5bd039f4ab5a029126951b5985eebf57cabdcdc4d21f5b3be8bb4ce92" } - ] - } - ] - } - ] - ``` + ] + }, + { + "Name": "Repository", + "Keys": [ + { + "ID": "85bfd031017722f950d480a721f845a2944db26a3dc084040a70f1b0d9bbb3df" + } + ] + } + ] + } + ] + ``` - If the image tag is unsigned or unavailable, `docker trust inspect` does not - display any signed tags. + ### Formatting - ```console - $ docker trust inspect unsigned-img + You can print the inspect output in a human-readable format instead of the default + JSON output, by using the `--pretty` option: - No signatures or cannot access unsigned-img - ``` + ### Get details about signatures for a single image tag - However, if other tags are signed in the same image repository, - `docker trust inspect` reports relevant key information: + ```console + $ docker trust inspect --pretty alpine:latest - ```console - $ docker trust inspect alpine:unsigned - ``` + SIGNED TAG DIGEST SIGNERS + latest 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) - The output is in JSON format, for example: + Administrative keys for alpine:latest: + Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd + Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce + ``` - ```json - [ - { - "Name": "alpine:unsigned", - "Signers": [], - "AdministrativeKeys": [ - { - "Name": "Repository", - "Keys": [ - { - "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" - } - ] - }, - { - "Name": "Root", - "Keys": [ - { - "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" - } - ] - } - ] - } - ] - ``` + The `SIGNED TAG` is the signed image tag with a unique content-addressable + `DIGEST`. `SIGNERS` lists all entities who have signed. - ### Get details about signatures for all image tags in a repository + The administrative keys listed specify the root key of trust, as well as + the administrative repository key. These keys are responsible for modifying + signers, and rotating keys for the signed repository. - If no tag is specified, `docker trust inspect` will report details for all - signed tags in the repository: + If signers are set up for the repository via other `docker trust` commands, + `docker trust inspect --pretty` displays them appropriately as a `SIGNER` + and specify their `KEYS`: - ```console - $ docker trust inspect alpine - ``` + ```console + $ docker trust inspect --pretty my-image:purple - The output is in JSON format, for example: + SIGNED TAG DIGEST SIGNERS + purple 941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557 alice, bob, carol - ```json - [ - { - "Name": "alpine", - "SignedTags": [ - { - "SignedTag": "3.5", - "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "3.6", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "edge", - "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "latest", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - } - ], - "Signers": [], - "AdministrativeKeys": [ - { - "Name": "Repository", - "Keys": [ - { - "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" - } - ] - }, - { - "Name": "Root", - "Keys": [ - { - "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" - } - ] - } - ] - } - ] - ``` + List of signers and their keys: + + SIGNER KEYS + alice 47caae5b3e61, a85aab9d20a4 + bob 034370bcbd77, 82a66673242c + carol b6f9f8e1aab0 + + Administrative keys for my-image: + Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44 + Root Key: 40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f + ``` + + However, if other tags are signed in the same image repository, + `docker trust inspect` reports relevant key information. + + ```console + $ docker trust inspect --pretty alpine:unsigned + + No signatures for alpine:unsigned - ### Get details about signatures for multiple images + Administrative keys for alpine:unsigned: + Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd + Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce + ``` - `docker trust inspect` can take multiple repositories and images as arguments, - and reports the results in an ordered list: + ### Get details about signatures for all image tags in a repository - ```console - $ docker trust inspect alpine notary - ``` + ```console + $ docker trust inspect --pretty alpine - The output is in JSON format, for example: + SIGNED TAG DIGEST SIGNERS + 2.6 9ace551613070689a12857d62c30ef0daa9a376107ec0fff0e34786cedb3399b (Repo Admin) + 2.7 9f08005dff552038f0ad2f46b8e65ff3d25641747d3912e3ea8da6785046561a (Repo Admin) + 3.1 d9477888b78e8c6392e0be8b2e73f8c67e2894ff9d4b8e467d1488fcceec21c8 (Repo Admin) + 3.2 19826d59171c2eb7e90ce52bfd822993bef6a6fe3ae6bb4a49f8c1d0a01e99c7 (Repo Admin) + 3.3 8fd4b76819e1e5baac82bd0a3d03abfe3906e034cc5ee32100d12aaaf3956dc7 (Repo Admin) + 3.4 833ad81ace8277324f3ca8c91c02bdcf1d13988d8ecf8a3f97ecdd69d0390ce9 (Repo Admin) + 3.5 af2a5bd2f8de8fc1ecabf1c76611cdc6a5f1ada1a2bdd7d3816e121b70300308 (Repo Admin) + 3.6 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) + edge 79d50d15bd7ea48ea00cf3dd343b0e740c1afaa8e899bee475236ef338e1b53b (Repo Admin) + latest 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) - ```json - [ - { - "Name": "alpine", - "SignedTags": [ - { - "SignedTag": "3.5", - "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "3.6", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "edge", - "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "integ-test-base", - "Digest": "3952dc48dcc4136ccdde37fbef7e250346538a55a0366e3fccc683336377e372", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "latest", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - } - ], - "Signers": [], - "AdministrativeKeys": [ - { - "Name": "Repository", - "Keys": [ - { - "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" - } - ] - }, - { - "Name": "Root", - "Keys": [ - { - "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" - } - ] - } - ] - }, - { - "Name": "notary", - "SignedTags": [ - { - "SignedTag": "server", - "Digest": "71f64ab718a3331dee103bc5afc6bc492914738ce37c2d2f127a8133714ecf5c", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "signer", - "Digest": "a6122d79b1e74f70b5dd933b18a6d1f99329a4728011079f06b245205f158fe8", - "Signers": [ - "Repo Admin" - ] - } - ], - "Signers": [], - "AdministrativeKeys": [ - { - "Name": "Root", - "Keys": [ - { - "ID": "8cdcdef5bd039f4ab5a029126951b5985eebf57cabdcdc4d21f5b3be8bb4ce92" - } - ] - }, - { - "Name": "Repository", - "Keys": [ - { - "ID": "85bfd031017722f950d480a721f845a2944db26a3dc084040a70f1b0d9bbb3df" - } - ] - } - ] - } - ] - ``` + Administrative keys for alpine: + Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd + Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce + ``` - ### Formatting + Here's an example with signers that are set up by `docker trust` commands: - You can print the inspect output in a human-readable format instead of the default - JSON output, by using the `--pretty` option: + ```console + $ docker trust inspect --pretty my-image - ### Get details about signatures for a single image tag + SIGNED TAG DIGEST SIGNERS + red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice + blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob + green cae8fedc840f90c8057e1c24637d11865743ab1e61a972c1c9da06ec2de9a139 alice, bob + yellow 9cc65fc3126790e683d1b92f307a71f48f75fa7dd47a7b03145a123eaf0b45ba carol + purple 941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557 alice, bob, carol + orange d6c271baa6d271bcc24ef1cbd65abf39123c17d2e83455bdab545a1a9093fc1c alice - ```console - $ docker trust inspect --pretty alpine:latest + List of signers and their keys for my-image: - SIGNED TAG DIGEST SIGNERS - latest 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) + SIGNER KEYS + alice 47caae5b3e61, a85aab9d20a4 + bob 034370bcbd77, 82a66673242c + carol b6f9f8e1aab0 - Administrative keys for alpine:latest: - Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd - Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce - ``` - - The `SIGNED TAG` is the signed image tag with a unique content-addressable - `DIGEST`. `SIGNERS` lists all entities who have signed. - - The administrative keys listed specify the root key of trust, as well as - the administrative repository key. These keys are responsible for modifying - signers, and rotating keys for the signed repository. - - If signers are set up for the repository via other `docker trust` commands, - `docker trust inspect --pretty` displays them appropriately as a `SIGNER` - and specify their `KEYS`: - - ```console - $ docker trust inspect --pretty my-image:purple - - SIGNED TAG DIGEST SIGNERS - purple 941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557 alice, bob, carol - - List of signers and their keys: - - SIGNER KEYS - alice 47caae5b3e61, a85aab9d20a4 - bob 034370bcbd77, 82a66673242c - carol b6f9f8e1aab0 - - Administrative keys for my-image: - Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44 - Root Key: 40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f - ``` - - However, if other tags are signed in the same image repository, - `docker trust inspect` reports relevant key information. - - ```console - $ docker trust inspect --pretty alpine:unsigned - - No signatures for alpine:unsigned - - - Administrative keys for alpine:unsigned: - Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd - Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce - ``` - - ### Get details about signatures for all image tags in a repository - - ```console - $ docker trust inspect --pretty alpine - - SIGNED TAG DIGEST SIGNERS - 2.6 9ace551613070689a12857d62c30ef0daa9a376107ec0fff0e34786cedb3399b (Repo Admin) - 2.7 9f08005dff552038f0ad2f46b8e65ff3d25641747d3912e3ea8da6785046561a (Repo Admin) - 3.1 d9477888b78e8c6392e0be8b2e73f8c67e2894ff9d4b8e467d1488fcceec21c8 (Repo Admin) - 3.2 19826d59171c2eb7e90ce52bfd822993bef6a6fe3ae6bb4a49f8c1d0a01e99c7 (Repo Admin) - 3.3 8fd4b76819e1e5baac82bd0a3d03abfe3906e034cc5ee32100d12aaaf3956dc7 (Repo Admin) - 3.4 833ad81ace8277324f3ca8c91c02bdcf1d13988d8ecf8a3f97ecdd69d0390ce9 (Repo Admin) - 3.5 af2a5bd2f8de8fc1ecabf1c76611cdc6a5f1ada1a2bdd7d3816e121b70300308 (Repo Admin) - 3.6 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) - edge 79d50d15bd7ea48ea00cf3dd343b0e740c1afaa8e899bee475236ef338e1b53b (Repo Admin) - latest 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) - - Administrative keys for alpine: - Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd - Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce - ``` - - Here's an example with signers that are set up by `docker trust` commands: - - ```console - $ docker trust inspect --pretty my-image - - SIGNED TAG DIGEST SIGNERS - red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice - blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob - green cae8fedc840f90c8057e1c24637d11865743ab1e61a972c1c9da06ec2de9a139 alice, bob - yellow 9cc65fc3126790e683d1b92f307a71f48f75fa7dd47a7b03145a123eaf0b45ba carol - purple 941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557 alice, bob, carol - orange d6c271baa6d271bcc24ef1cbd65abf39123c17d2e83455bdab545a1a9093fc1c alice - - List of signers and their keys for my-image: - - SIGNER KEYS - alice 47caae5b3e61, a85aab9d20a4 - bob 034370bcbd77, 82a66673242c - carol b6f9f8e1aab0 - - Administrative keys for my-image: - Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44 - Root Key: 40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f - ``` + Administrative keys for my-image: + Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44 + Root Key: 40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_key.yaml b/_data/engine-cli/docker_trust_key.yaml index c6bee2f411..dcce3374cc 100644 --- a/_data/engine-cli/docker_trust_key.yaml +++ b/_data/engine-cli/docker_trust_key.yaml @@ -5,11 +5,22 @@ usage: docker trust key pname: docker trust plink: docker_trust.yaml cname: -- docker trust key generate -- docker trust key load + - docker trust key generate + - docker trust key load clink: -- docker_trust_key_generate.yaml -- docker_trust_key_load.yaml + - docker_trust_key_generate.yaml + - docker_trust_key_load.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_key_generate.yaml b/_data/engine-cli/docker_trust_key_generate.yaml index c324360c86..9cae107f70 100644 --- a/_data/engine-cli/docker_trust_key_generate.yaml +++ b/_data/engine-cli/docker_trust_key_generate.yaml @@ -1,52 +1,64 @@ command: docker trust key generate short: Generate and load a signing key-pair long: |- - `docker trust key generate` generates a key-pair to be used with signing, - and loads the private key into the local docker trust keystore. + `docker trust key generate` generates a key-pair to be used with signing, + and loads the private key into the local docker trust keystore. 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 - experimentalcli: false - kubernetes: false - swarm: false + - option: dir + value_type: string + description: Directory to generate key in, defaults to current directory + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Generate a key-pair + ### Generate a key-pair - ```console - $ docker trust key generate alice + ```console + $ docker trust key generate alice - Generating key for alice... - Enter passphrase for new alice key with ID 17acf3c: - Repeat passphrase for new alice key with ID 17acf3c: - Successfully generated and loaded private key. Corresponding public key available: alice.pub - $ ls - alice.pub - ``` + Generating key for alice... + Enter passphrase for new alice key with ID 17acf3c: + Repeat passphrase for new alice key with ID 17acf3c: + Successfully generated and loaded private key. Corresponding public key available: alice.pub + $ ls + alice.pub + ``` - The private signing key is encrypted by the passphrase and loaded into the docker trust keystore. - All passphrase requests to sign with the key will be referred to by the provided `NAME`. + The private signing key is encrypted by the passphrase and loaded into the docker trust keystore. + All passphrase requests to sign with the key will be referred to by the provided `NAME`. - The public key component `alice.pub` will be available in the current working directory, and can - be used directly by `docker trust signer add`. + The public key component `alice.pub` will be available in the current working directory, and can + be used directly by `docker trust signer add`. - Provide the `--dir` argument to specify a directory to generate the key in: + Provide the `--dir` argument to specify a directory to generate the key in: - ```console - $ docker trust key generate alice --dir /foo + ```console + $ docker trust key generate alice --dir /foo - Generating key for alice... - Enter passphrase for new alice key with ID 17acf3c: - Repeat passphrase for new alice key with ID 17acf3c: - Successfully generated and loaded private key. Corresponding public key available: alice.pub - $ ls /foo - alice.pub - ``` + Generating key for alice... + Enter passphrase for new alice key with ID 17acf3c: + Repeat passphrase for new alice key with ID 17acf3c: + Successfully generated and loaded private key. Corresponding public key available: alice.pub + $ ls /foo + alice.pub + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_key_load.yaml b/_data/engine-cli/docker_trust_key_load.yaml index f416eab607..84d97dc135 100644 --- a/_data/engine-cli/docker_trust_key_load.yaml +++ b/_data/engine-cli/docker_trust_key_load.yaml @@ -1,46 +1,58 @@ command: docker trust key load short: Load a private key file for signing long: |- - `docker trust key load` adds private keys to the local docker trust keystore. + `docker trust key load` adds private keys to the local docker trust keystore. - To add a signer to a repository use `docker trust signer add`. + To add a signer to a repository use `docker trust signer add`. 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 - experimentalcli: false - kubernetes: false - swarm: false + - option: name + value_type: string + default_value: signer + description: Name for the loaded key + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Load a single private key + ### Load a single private key - For a private key `alice.pem` with permissions `-rw-------` + For a private key `alice.pem` with permissions `-rw-------` - ```console - $ docker trust key load alice.pem + ```console + $ docker trust key load alice.pem - Loading key from "alice.pem"... - Enter passphrase for new signer key with ID f8097df: - Repeat passphrase for new signer key with ID f8097df: - Successfully imported key from alice.pem - ``` + Loading key from "alice.pem"... + Enter passphrase for new signer key with ID f8097df: + Repeat passphrase for new signer key with ID f8097df: + Successfully imported key from alice.pem + ``` - To specify a name use the `--name` flag: + To specify a name use the `--name` flag: - ```console - $ docker trust key load --name alice-key alice.pem + ```console + $ docker trust key load --name alice-key alice.pem - Loading key from "alice.pem"... - Enter passphrase for new alice-key key with ID f8097df: - Repeat passphrase for new alice-key key with ID f8097df: - Successfully imported key from alice.pem - ``` + Loading key from "alice.pem"... + Enter passphrase for new alice-key key with ID f8097df: + Repeat passphrase for new alice-key key with ID f8097df: + Successfully imported key from alice.pem + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_revoke.yaml b/_data/engine-cli/docker_trust_revoke.yaml index 8421f2cb9e..75aa41bd70 100644 --- a/_data/engine-cli/docker_trust_revoke.yaml +++ b/_data/engine-cli/docker_trust_revoke.yaml @@ -5,113 +5,125 @@ usage: docker trust revoke [OPTIONS] IMAGE[:TAG] pname: docker trust plink: docker_trust.yaml options: -- option: "yes" - shorthand: "y" - value_type: bool - default_value: "false" - description: Do not prompt for confirmation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: "yes" + shorthand: "y" + value_type: bool + default_value: "false" + description: Do not prompt for confirmation + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Revoke signatures from a signed tag + ### Revoke signatures from a signed tag - Here's an example of a repo with two signed tags: + Here's an example of a repo with two signed tags: - ```console - $ docker trust inspect --pretty example/trust-demo - SIGNED TAG DIGEST SIGNERS - red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice - blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob + ```console + $ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS + red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice + blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob - List of signers and their keys for example/trust-demo: + List of signers and their keys for example/trust-demo: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - When `alice`, one of the signers, runs `docker trust revoke`: + When `alice`, one of the signers, runs `docker trust revoke`: - ```console - $ docker trust revoke example/trust-demo:red - Enter passphrase for delegation key with ID 27d42a8: - Successfully deleted signature for example/trust-demo:red - ``` + ```console + $ docker trust revoke example/trust-demo:red + Enter passphrase for delegation key with ID 27d42a8: + Successfully deleted signature for example/trust-demo:red + ``` - After revocation, the tag is removed from the list of released tags: + After revocation, the tag is removed from the list of released tags: - ```console - $ docker trust inspect --pretty example/trust-demo - SIGNED TAG DIGEST SIGNERS - blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob + ```console + $ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS + blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob - List of signers and their keys for example/trust-demo: + List of signers and their keys for example/trust-demo: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - ### Revoke signatures on all tags in a repository + ### Revoke signatures on all tags in a repository - When no tag is specified, `docker trust` revokes all signatures that you have a signing key for. + When no tag is specified, `docker trust` revokes all signatures that you have a signing key for. - ```console - $ docker trust inspect --pretty example/trust-demo - SIGNED TAG DIGEST SIGNERS - red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice - blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob + ```console + $ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS + red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice + blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob - List of signers and their keys for example/trust-demo: + List of signers and their keys for example/trust-demo: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - When `alice`, one of the signers, runs `docker trust revoke`: + When `alice`, one of the signers, runs `docker trust revoke`: - ```console - $ docker trust revoke example/trust-demo - Please confirm you would like to delete all signature data for example/trust-demo? [y/N] y - Enter passphrase for delegation key with ID 27d42a8: - Successfully deleted signature for example/trust-demo - ``` + ```console + $ docker trust revoke example/trust-demo + Please confirm you would like to delete all signature data for example/trust-demo? [y/N] y + Enter passphrase for delegation key with ID 27d42a8: + Successfully deleted signature for example/trust-demo + ``` - All tags that have `alice`'s signature on them are removed from the list of released tags: + All tags that have `alice`'s signature on them are removed from the list of released tags: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - No signatures for example/trust-demo + No signatures for example/trust-demo - List of signers and their keys for example/trust-demo: + List of signers and their keys for example/trust-demo: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_sign.yaml b/_data/engine-cli/docker_trust_sign.yaml index 2d881aeca0..797e35cec9 100644 --- a/_data/engine-cli/docker_trust_sign.yaml +++ b/_data/engine-cli/docker_trust_sign.yaml @@ -5,122 +5,134 @@ usage: docker trust sign IMAGE:TAG pname: docker trust plink: docker_trust.yaml options: -- option: local - value_type: bool - default_value: "false" - description: Sign a locally tagged image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: local + value_type: bool + default_value: "false" + description: Sign a locally tagged image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Sign a tag as a repo admin + ### Sign a tag as a repo admin - Given an image: + Given an image: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - SIGNED TAG DIGEST SIGNERS - v1 c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41 (Repo Admin) + SIGNED TAG DIGEST SIGNERS + v1 c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41 (Repo Admin) - Administrative keys for example/trust-demo: - Repository Key: 36d4c3601102fa7c5712a343c03b94469e5835fb27c191b529c06fd19c14a942 - Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b - ``` + Administrative keys for example/trust-demo: + Repository Key: 36d4c3601102fa7c5712a343c03b94469e5835fb27c191b529c06fd19c14a942 + Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b + ``` - Sign a new tag with `docker trust sign`: + Sign a new tag with `docker trust sign`: - ```console - $ docker trust sign example/trust-demo:v2 + ```console + $ docker trust sign example/trust-demo:v2 - Signing and pushing trust metadata for example/trust-demo:v2 - The push refers to a repository [docker.io/example/trust-demo] - eed4e566104a: Layer already exists - 77edfb6d1e3c: Layer already exists - c69f806905c2: Layer already exists - 582f327616f1: Layer already exists - a3fbb648f0bd: Layer already exists - 5eac2de68a97: Layer already exists - 8d4d1ab5ff74: Layer already exists - v2: digest: sha256:8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56 size: 1787 - Signing and pushing trust metadata - Enter passphrase for repository key with ID 36d4c36: - Successfully signed docker.io/example/trust-demo:v2 - ``` + Signing and pushing trust metadata for example/trust-demo:v2 + The push refers to a repository [docker.io/example/trust-demo] + eed4e566104a: Layer already exists + 77edfb6d1e3c: Layer already exists + c69f806905c2: Layer already exists + 582f327616f1: Layer already exists + a3fbb648f0bd: Layer already exists + 5eac2de68a97: Layer already exists + 8d4d1ab5ff74: Layer already exists + v2: digest: sha256:8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56 size: 1787 + Signing and pushing trust metadata + Enter passphrase for repository key with ID 36d4c36: + Successfully signed docker.io/example/trust-demo:v2 + ``` - Use `docker trust inspect --pretty` to list the new signature: + Use `docker trust inspect --pretty` to list the new signature: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - SIGNED TAG DIGEST SIGNERS - v1 c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41 (Repo Admin) - v2 8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56 (Repo Admin) + SIGNED TAG DIGEST SIGNERS + v1 c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41 (Repo Admin) + v2 8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56 (Repo Admin) - Administrative keys for example/trust-demo: - Repository Key: 36d4c3601102fa7c5712a343c03b94469e5835fb27c191b529c06fd19c14a942 - Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b - ``` + Administrative keys for example/trust-demo: + Repository Key: 36d4c3601102fa7c5712a343c03b94469e5835fb27c191b529c06fd19c14a942 + Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b + ``` - ### Sign a tag as a signer + ### Sign a tag as a signer - Given an image: + Given an image: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - No signatures for example/trust-demo + No signatures for example/trust-demo - List of signers and their keys for example/trust-demo: + List of signers and their keys for example/trust-demo: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - Sign a new tag with `docker trust sign`: + Sign a new tag with `docker trust sign`: - ```console - $ docker trust sign example/trust-demo:v1 + ```console + $ docker trust sign example/trust-demo:v1 - Signing and pushing trust metadata for example/trust-demo:v1 - The push refers to a repository [docker.io/example/trust-demo] - 26b126eb8632: Layer already exists - 220d34b5f6c9: Layer already exists - 8a5132998025: Layer already exists - aca233ed29c3: Layer already exists - e5d2f035d7a4: Layer already exists - v1: digest: sha256:74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 size: 1357 - Signing and pushing trust metadata - Enter passphrase for delegation key with ID 27d42a8: - Successfully signed docker.io/example/trust-demo:v1 - ``` + Signing and pushing trust metadata for example/trust-demo:v1 + The push refers to a repository [docker.io/example/trust-demo] + 26b126eb8632: Layer already exists + 220d34b5f6c9: Layer already exists + 8a5132998025: Layer already exists + aca233ed29c3: Layer already exists + e5d2f035d7a4: Layer already exists + v1: digest: sha256:74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 size: 1357 + Signing and pushing trust metadata + Enter passphrase for delegation key with ID 27d42a8: + Successfully signed docker.io/example/trust-demo:v1 + ``` - `docker trust inspect --pretty` lists the new signature: + `docker trust inspect --pretty` lists the new signature: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - SIGNED TAG DIGEST SIGNERS - v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice + SIGNED TAG DIGEST SIGNERS + v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice - List of signers and their keys for example/trust-demo: + List of signers and their keys for example/trust-demo: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_signer.yaml b/_data/engine-cli/docker_trust_signer.yaml index b279973d20..bb69800b0f 100644 --- a/_data/engine-cli/docker_trust_signer.yaml +++ b/_data/engine-cli/docker_trust_signer.yaml @@ -5,11 +5,22 @@ usage: docker trust signer pname: docker trust plink: docker_trust.yaml cname: -- docker trust signer add -- docker trust signer remove + - docker trust signer add + - docker trust signer remove clink: -- docker_trust_signer_add.yaml -- docker_trust_signer_remove.yaml + - docker_trust_signer_add.yaml + - docker_trust_signer_remove.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_signer_add.yaml b/_data/engine-cli/docker_trust_signer_add.yaml index 77d4ba7fc0..a39fdde0a6 100644 --- a/_data/engine-cli/docker_trust_signer_add.yaml +++ b/_data/engine-cli/docker_trust_signer_add.yaml @@ -5,62 +5,74 @@ 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 - experimentalcli: false - kubernetes: false - swarm: false + - option: key + value_type: list + description: Path to the signer's public key file + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Add a signer to a repo + ### Add a signer to a repo - To add a new signer, `alice`, to this repository: + To add a new signer, `alice`, to this repository: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - No signatures for example/trust-demo + No signatures for example/trust-demo - List of signers and their keys: + List of signers and their keys: - SIGNER KEYS - bob 5600f5ab76a2 + SIGNER KEYS + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: 642692c14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: 642692c14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - Add `alice` with `docker trust signer add`: + Add `alice` with `docker trust signer add`: - ```console - $ docker trust signer add alice example/trust-demo --key alice.crt - Adding signer "alice" to example/trust-demo... - Enter passphrase for repository key with ID 642692c: - Successfully added signer: alice to example/trust-demo - ``` + ```console + $ docker trust signer add alice example/trust-demo --key alice.crt + Adding signer "alice" to example/trust-demo... + Enter passphrase for repository key with ID 642692c: + Successfully added signer: alice to example/trust-demo + ``` - `docker trust inspect --pretty` now lists `alice` as a valid signer: + `docker trust inspect --pretty` now lists `alice` as a valid signer: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - No signatures for example/trust-demo + No signatures for example/trust-demo - List of signers and their keys: + List of signers and their keys: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: 642692c14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: 642692c14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_trust_signer_remove.yaml b/_data/engine-cli/docker_trust_signer_remove.yaml index 0060f9941d..e9082d4566 100644 --- a/_data/engine-cli/docker_trust_signer_remove.yaml +++ b/_data/engine-cli/docker_trust_signer_remove.yaml @@ -5,170 +5,182 @@ 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 - experimentalcli: false - kubernetes: false - swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: | + Do not prompt for confirmation before removing the most recent signer + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Remove a signer from a repo + ### Remove a signer from a repo - To remove an existing signer, `alice`, from this repository: + To remove an existing signer, `alice`, from this repository: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - No signatures for example/trust-demo + No signatures for example/trust-demo - List of signers and their keys: + List of signers and their keys: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - Remove `alice` with `docker trust signer remove`: + Remove `alice` with `docker trust signer remove`: - ```console - $ docker trust signer remove alice example/trust-demo + ```console + $ docker trust signer remove alice example/trust-demo - Removing signer "alice" from image example/trust-demo... - Enter passphrase for repository key with ID 642692c: - Successfully removed alice from example/trust-demo - ``` + Removing signer "alice" from image example/trust-demo... + Enter passphrase for repository key with ID 642692c: + Successfully removed alice from example/trust-demo + ``` - `docker trust inspect --pretty` now does not list `alice` as a valid signer: + `docker trust inspect --pretty` now does not list `alice` as a valid signer: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - No signatures for example/trust-demo + No signatures for example/trust-demo - List of signers and their keys: + List of signers and their keys: - SIGNER KEYS - bob 5600f5ab76a2 + SIGNER KEYS + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - ### Remove a signer from multiple repos + ### Remove a signer from multiple repos - To remove an existing signer, `alice`, from multiple repositories: + To remove an existing signer, `alice`, from multiple repositories: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - SIGNED TAG DIGEST SIGNERS - v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice, bob + SIGNED TAG DIGEST SIGNERS + v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice, bob - List of signers and their keys: + List of signers and their keys: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: 95b9e5514c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: 95b9e5514c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - ```console - $ docker trust inspect --pretty example/trust-demo2 + ```console + $ docker trust inspect --pretty example/trust-demo2 - SIGNED TAG DIGEST SIGNERS - v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice, bob + SIGNED TAG DIGEST SIGNERS + v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice, bob - List of signers and their keys: + List of signers and their keys: - SIGNER KEYS - alice 05e87edcaecb - bob 5600f5ab76a2 + SIGNER KEYS + alice 05e87edcaecb + bob 5600f5ab76a2 - Administrative keys for example/trust-demo2: - Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d9268 - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo2: + Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d9268 + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - Remove `alice` from both images with a single `docker trust signer remove` command: + Remove `alice` from both images with a single `docker trust signer remove` command: - ```console - $ docker trust signer remove alice example/trust-demo example/trust-demo2 + ```console + $ docker trust signer remove alice example/trust-demo example/trust-demo2 - Removing signer "alice" from image example/trust-demo... - Enter passphrase for repository key with ID 95b9e55: - Successfully removed alice from example/trust-demo + Removing signer "alice" from image example/trust-demo... + Enter passphrase for repository key with ID 95b9e55: + Successfully removed alice from example/trust-demo - Removing signer "alice" from image example/trust-demo2... - Enter passphrase for repository key with ID ece554f: - Successfully removed alice from example/trust-demo2 - ``` + Removing signer "alice" from image example/trust-demo2... + Enter passphrase for repository key with ID ece554f: + Successfully removed alice from example/trust-demo2 + ``` - Run `docker trust inspect --pretty` to confirm that `alice` is no longer listed as a valid - signer of either `example/trust-demo` or `example/trust-demo2`: + Run `docker trust inspect --pretty` to confirm that `alice` is no longer listed as a valid + signer of either `example/trust-demo` or `example/trust-demo2`: - ```console - $ docker trust inspect --pretty example/trust-demo + ```console + $ docker trust inspect --pretty example/trust-demo - SIGNED TAG DIGEST SIGNERS - v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob + SIGNED TAG DIGEST SIGNERS + v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob - List of signers and their keys: + List of signers and their keys: - SIGNER KEYS - bob 5600f5ab76a2 + SIGNER KEYS + bob 5600f5ab76a2 - Administrative keys for example/trust-demo: - Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo: + Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - ```console - $ docker trust inspect --pretty example/trust-demo2 + ```console + $ docker trust inspect --pretty example/trust-demo2 - SIGNED TAG DIGEST SIGNERS - v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob + SIGNED TAG DIGEST SIGNERS + v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob - List of signers and their keys: + List of signers and their keys: - SIGNER KEYS - bob 5600f5ab76a2 + SIGNER KEYS + bob 5600f5ab76a2 - Administrative keys for example/trust-demo2: - Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d9268 - Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 - ``` + Administrative keys for example/trust-demo2: + Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d9268 + Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 + ``` - `docker trust signer remove` removes signers to repositories on a best effort - basis, so it will continue to remove the signer from subsequent repositories if - one attempt fails: + `docker trust signer remove` removes signers to repositories on a best effort + basis, so it will continue to remove the signer from subsequent repositories if + one attempt fails: - ```console - $ docker trust signer remove alice example/unauthorized example/authorized + ```console + $ docker trust signer remove alice example/unauthorized example/authorized - Removing signer "alice" from image example/unauthorized... - No signer alice for image example/unauthorized + Removing signer "alice" from image example/unauthorized... + No signer alice for image example/unauthorized - Removing signer "alice" from image example/authorized... - Enter passphrase for repository key with ID c6772a0: - Successfully removed alice from example/authorized + Removing signer "alice" from image example/authorized... + Enter passphrase for repository key with ID c6772a0: + Successfully removed alice from example/authorized - Error removing signer from: example/unauthorized - ``` + Error removing signer from: example/unauthorized + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_unpause.yaml b/_data/engine-cli/docker_unpause.yaml index 9eb3decc7e..97e157a896 100644 --- a/_data/engine-cli/docker_unpause.yaml +++ b/_data/engine-cli/docker_unpause.yaml @@ -1,20 +1,32 @@ command: docker unpause +aliases: docker container unpause, docker unpause short: Unpause all processes within one or more containers long: |- - The `docker unpause` command un-suspends all processes in the specified containers. - On Linux, it does this using the freezer cgroup. + The `docker unpause` command un-suspends all processes in the specified containers. + On Linux, it does this using the freezer cgroup. - See the - [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) - for further details. + See the + [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) + for further details. usage: docker unpause CONTAINER [CONTAINER...] pname: docker plink: docker.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker unpause my_container - my_container - ``` + ```console + $ docker unpause my_container + my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_update.yaml b/_data/engine-cli/docker_update.yaml index c44066c55c..f05b3bbe84 100644 --- a/_data/engine-cli/docker_update.yaml +++ b/_data/engine-cli/docker_update.yaml @@ -1,238 +1,268 @@ command: docker update +aliases: docker container update, docker update short: Update configuration of one or more containers long: |- - The `docker update` command dynamically updates container configuration. - You can use this command to prevent containers from consuming too many - resources from their Docker host. With a single command, you can place - limits on a single container or on many. To specify more than one container, - provide space-separated list of container names or IDs. + The `docker update` command dynamically updates container configuration. + You can use this command to prevent containers from consuming too many + resources from their Docker host. With a single command, you can place + limits on a single container or on many. To specify more than one container, + provide space-separated list of container names or IDs. - With the exception of the `--kernel-memory` option, you can specify these - options on a running or a stopped container. On kernel version older than - 4.6, you can only update `--kernel-memory` on a stopped container or on - a running container with kernel memory initialized. + With the exception of the `--kernel-memory` option, you can specify these + options on a running or a stopped container. On kernel version older than + 4.6, you can only update `--kernel-memory` on a stopped container or on + a running container with kernel memory initialized. - > **Warning** - > - > The `docker update` and `docker container update` commands are not supported - > for Windows containers. - {: .warning } + > **Warning** + > + > The `docker update` and `docker container update` commands are not supported + > for Windows containers. + {: .warning } usage: docker update [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml options: -- option: blkio-weight - value_type: uint16 - default_value: "0" - description: | - Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-period - value_type: int64 - default_value: "0" - description: Limit the CPU real-time period in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-rt-runtime - value_type: int64 - default_value: "0" - description: Limit the CPU real-time runtime in microseconds - deprecated: false - min_api_version: "1.25" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpus - value_type: decimal - description: Number of CPUs - deprecated: false - min_api_version: "1.29" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kernel-memory - value_type: bytes - default_value: "0" - description: Kernel memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: bytes - default_value: "0" - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-reservation - value_type: bytes - default_value: "0" - description: Memory soft limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: bytes - default_value: "0" - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pids-limit - value_type: int64 - default_value: "0" - description: Tune container pids limit (set -1 for unlimited) - deprecated: false - min_api_version: "1.40" - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: restart - value_type: string - description: Restart policy to apply when a container exits - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: blkio-weight + value_type: uint16 + default_value: "0" + description: | + Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-period + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-period + value_type: int64 + default_value: "0" + description: Limit the CPU real-time period in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-rt-runtime + value_type: int64 + default_value: "0" + description: Limit the CPU real-time runtime in microseconds + deprecated: false + hidden: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + details_url: '#cpu-shares' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpus + value_type: decimal + description: Number of CPUs + deprecated: false + hidden: false + min_api_version: "1.29" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: kernel-memory + value_type: bytes + default_value: "0" + description: Kernel memory limit (deprecated) + details_url: '#kernel-memory' + deprecated: true + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + details_url: '#memory' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-reservation + value_type: bytes + default_value: "0" + description: Memory soft limit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: memory-swap + value_type: bytes + default_value: "0" + description: 'Swap limit equal to memory plus swap: -1 to enable unlimited swap' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pids-limit + value_type: int64 + default_value: "0" + description: Tune container pids limit (set -1 for unlimited) + deprecated: false + hidden: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: restart + value_type: string + description: Restart policy to apply when a container exits + details_url: '#restart' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - The following sections illustrate ways to use this command. + The following sections illustrate ways to use this command. - ### Update a container's cpu-shares (--cpu-shares) + ### Update a container's cpu-shares (--cpu-shares) {#cpu-shares} - To limit a container's cpu-shares to 512, first identify the container - name or ID. You can use `docker ps` to find these values. You can also - use the ID returned from the `docker run` command. Then, do the following: + To limit a container's cpu-shares to 512, first identify the container + name or ID. You can use `docker ps` to find these values. You can also + use the ID returned from the `docker run` command. Then, do the following: - ```console - $ docker update --cpu-shares 512 abebf7571666 - ``` + ```console + $ docker update --cpu-shares 512 abebf7571666 + ``` - ### Update a container with cpu-shares and memory (-m, --memory) + ### Update a container with cpu-shares and memory (-m, --memory) {#memory} - To update multiple resource configurations for multiple containers: + To update multiple resource configurations for multiple containers: - ```console - $ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse - ``` + ```console + $ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse + ``` - ### Update a container's kernel memory constraints (--kernel-memory) + ### Update a container's kernel memory constraints (--kernel-memory) {#kernel-memory} - You can update a container's kernel memory limit using the `--kernel-memory` - option. On kernel version older than 4.6, this option can be updated on a - running container only if the container was started with `--kernel-memory`. - If the container was started *without* `--kernel-memory` you need to stop - the container before updating kernel memory. + You can update a container's kernel memory limit using the `--kernel-memory` + option. On kernel version older than 4.6, this option can be updated on a + running container only if the container was started with `--kernel-memory`. + If the container was started *without* `--kernel-memory` you need to stop + the container before updating kernel memory. - > **Note** - > - > The `--kernel-memory` option has been deprecated since Docker 20.10. + > **Note** + > + > The `--kernel-memory` option has been deprecated since Docker 20.10. - For example, if you started a container with this command: + For example, if you started a container with this command: - ```console - $ docker run -dit --name test --kernel-memory 50M ubuntu bash - ``` + ```console + $ docker run -dit --name test --kernel-memory 50M ubuntu bash + ``` - You can update kernel memory while the container is running: + You can update kernel memory while the container is running: - ```console - $ docker update --kernel-memory 80M test - ``` + ```console + $ docker update --kernel-memory 80M test + ``` - If you started a container *without* kernel memory initialized: + If you started a container *without* kernel memory initialized: - ```console - $ docker run -dit --name test2 --memory 300M ubuntu bash - ``` + ```console + $ docker run -dit --name test2 --memory 300M ubuntu bash + ``` - Update kernel memory of running container `test2` will fail. You need to stop - the container before updating the `--kernel-memory` setting. The next time you - start it, the container uses the new value. + Update kernel memory of running container `test2` will fail. You need to stop + the container before updating the `--kernel-memory` setting. The next time you + start it, the container uses the new value. - Kernel version newer than (include) 4.6 does not have this limitation, you - can use `--kernel-memory` the same way as other options. + Kernel version newer than (include) 4.6 does not have this limitation, you + can use `--kernel-memory` the same way as other options. - ### Update a container's restart policy (--restart) + ### Update a container's restart policy (--restart) {#restart} - You can change a container's restart policy on a running container. The new - restart policy takes effect instantly after you run `docker update` on a - container. + You can change a container's restart policy on a running container. The new + restart policy takes effect instantly after you run `docker update` on a + container. - To update restart policy for one or more containers: + To update restart policy for one or more containers: - ```console - $ docker update --restart=on-failure:3 abebf7571666 hopeful_morse - ``` + ```console + $ docker update --restart=on-failure:3 abebf7571666 hopeful_morse + ``` - Note that if the container is started with "--rm" flag, you cannot update the restart - policy for it. The `AutoRemove` and `RestartPolicy` are mutually exclusive for the - container. + Note that if the container is started with "--rm" flag, you cannot update the restart + policy for it. The `AutoRemove` and `RestartPolicy` are mutually exclusive for the + container. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_version.yaml b/_data/engine-cli/docker_version.yaml index 197174170c..d7fa9e6e8a 100644 --- a/_data/engine-cli/docker_version.yaml +++ b/_data/engine-cli/docker_version.yaml @@ -1,189 +1,199 @@ command: docker version short: Show the Docker version information long: |- - The version command prints the current version number for all independently - versioned Docker components. Use the [`--format`](#format) option to customize - the output. + The version command prints the current version number for all independently + versioned Docker components. Use the [`--format`](#format) option to customize + the output. - The version command (`docker version`) outputs the version numbers of Docker - components, while the `--version` flag (`docker --version`) outputs the version - number of the Docker CLI you are using. + The version command (`docker version`) outputs the version numbers of Docker + components, while the `--version` flag (`docker --version`) outputs the version + number of the Docker CLI you are using. - ### Default output + ### Default output - The default output renders all version information divided into two sections; - the "Client" section contains information about the Docker CLI and client - components, and the "Server" section contains information about the Docker - Engine and components used by the Engine, such as the "Containerd" and "Runc" - OCI Runtimes. + The default output renders all version information divided into two sections; + the "Client" section contains information about the Docker CLI and client + components, and the "Server" section contains information about the Docker + Engine and components used by the Engine, such as the "Containerd" and "Runc" + OCI Runtimes. - The information shown may differ depending on how you installed Docker and - what components are in use. The following example shows the output on a macOS - machine running Docker Desktop: + The information shown may differ depending on how you installed Docker and + what components are in use. The following example shows the output on a macOS + machine running Docker Desktop: - ```console - $ docker version + ```console + $ docker version - Client: - Version: 20.10.16 - API version: 1.41 - Go version: go1.17.10 - Git commit: aa7e414 - Built: Thu May 12 09:17:28 2022 - OS/Arch: darwin/amd64 - Context: default + Client: + Version: 20.10.16 + API version: 1.41 + Go version: go1.17.10 + Git commit: aa7e414 + Built: Thu May 12 09:17:28 2022 + OS/Arch: darwin/amd64 + Context: default - Server: Docker Desktop 4.8.2 (77141) - Engine: - Version: 20.10.16 - API version: 1.41 (minimum version 1.12) - Go version: go1.17.10 - Git commit: f756502 - Built: Thu May 12 09:15:33 2022 - OS/Arch: linux/amd64 - Experimental: false - containerd: - Version: 1.6.4 - GitCommit: 212e8b6fa2f44b9c21b2798135fc6fb7c53efc16 - runc: - Version: 1.1.1 - GitCommit: v1.1.1-0-g52de29d - docker-init: - Version: 0.19.0 - GitCommit: de40ad0 - ``` + Server: Docker Desktop 4.8.2 (77141) + Engine: + Version: 20.10.16 + API version: 1.41 (minimum version 1.12) + Go version: go1.17.10 + Git commit: f756502 + Built: Thu May 12 09:15:33 2022 + OS/Arch: linux/amd64 + Experimental: false + containerd: + Version: 1.6.4 + GitCommit: 212e8b6fa2f44b9c21b2798135fc6fb7c53efc16 + runc: + Version: 1.1.1 + GitCommit: v1.1.1-0-g52de29d + docker-init: + Version: 0.19.0 + GitCommit: de40ad0 + ``` - ### Client and server versions + ### Client and server versions - Docker uses a client/server architecture, which allows you to use the Docker CLI - on your local machine to control a Docker Engine running on a remote machine, - which can be (for example) a machine running in the Cloud or inside a Virtual Machine. + Docker uses a client/server architecture, which allows you to use the Docker CLI + on your local machine to control a Docker Engine running on a remote machine, + which can be (for example) a machine running in the Cloud or inside a Virtual Machine. - The following example switches the Docker CLI to use a [context](context.md) - named "remote-test-server", which runs an older version of the Docker Engine - on a Linux server: + The following example switches the Docker CLI to use a [context](context.md) + named "remote-test-server", which runs an older version of the Docker Engine + on a Linux server: - ```console - $ docker context use remote-test-server - remote-test-server + ```console + $ docker context use remote-test-server + remote-test-server - $ docker version + $ docker version - Client: - Version: 20.10.16 - API version: 1.40 (downgraded from 1.41) - Go version: go1.17.10 - Git commit: aa7e414 - Built: Thu May 12 09:17:28 2022 - OS/Arch: darwin/amd64 - Context: remote-test-server + Client: + Version: 20.10.16 + API version: 1.40 (downgraded from 1.41) + Go version: go1.17.10 + Git commit: aa7e414 + Built: Thu May 12 09:17:28 2022 + OS/Arch: darwin/amd64 + Context: remote-test-server - Server: Docker Engine - Community - Engine: - Version: 19.03.8 - API version: 1.40 (minimum version 1.12) - Go version: go1.12.17 - Git commit: afacb8b - Built: Wed Mar 11 01:29:16 2020 - OS/Arch: linux/amd64 - containerd: - Version: v1.2.13 - GitCommit: 7ad184331fa3e55e52b890ea95e65ba581ae3429 - runc: - Version: 1.0.0-rc10 - GitCommit: dc9208a3303feef5b3839f4323d9beb36df0a9dd - docker-init: - Version: 0.18.0 - GitCommit: fec3683 - ``` + Server: Docker Engine - Community + Engine: + Version: 19.03.8 + API version: 1.40 (minimum version 1.12) + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:29:16 2020 + OS/Arch: linux/amd64 + containerd: + Version: v1.2.13 + GitCommit: 7ad184331fa3e55e52b890ea95e65ba581ae3429 + runc: + Version: 1.0.0-rc10 + GitCommit: dc9208a3303feef5b3839f4323d9beb36df0a9dd + docker-init: + Version: 0.18.0 + GitCommit: fec3683 + ``` + + ### API version and version negotiation + + The API version used by the client depends on the Docker Engine that the Docker + CLI is connecting with. When connecting with the Docker Engine, the Docker CLI + and Docker Engine perform API version negotiation, and select the highest API + version that is supported by both the Docker CLI and the Docker Engine. + + For example, if the CLI is connecting with a Docker 19.03 engine, it downgrades + to API version 1.40 (refer to the [API version matrix](/engine/api/#api-version-matrix) + to learn about the supported API versions for Docker Engine): + + ```console + $ docker version --format '{{.Client.APIVersion}}' + + 1.40 + ``` + + Be aware that API version can also be overridden using the `DOCKER_API_VERSION` + environment variable, which can be useful for debugging purposes, and disables + API version negotiation. The following example illustrates an environment where + the `DOCKER_API_VERSION` environment variable is set. Unsetting the environment + variable removes the override, and re-enables API version negotiation: + + ```console + $ env | grep DOCKER_API_VERSION + DOCKER_API_VERSION=1.39 + + $ docker version --format '{{.Client.APIVersion}}' + 1.39 + + $ unset DOCKER_API_VERSION + $ docker version --format '{{.Client.APIVersion}}' + 1.41 + ``` usage: docker version [OPTIONS] pname: docker plink: docker.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: kubeconfig - value_type: string - description: Kubernetes config file - deprecated: true - experimental: false - experimentalcli: false - kubernetes: true - swarm: false + - option: format + shorthand: f + value_type: string + description: Format the output using the given Go template + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting option (`--format`) pretty-prints the output using a Go template, - which allows you to customize the output format, or to obtain specific information - from the output. Refer to the [format command and log output](https://docs.docker.com/config/formatting/) - page for details of the format. + The formatting option (`--format`) pretty-prints the output using a Go template, + which allows you to customize the output format, or to obtain specific information + from the output. Refer to the [format command and log output](/config/formatting/) + page for details of the format. - ### Get the server version + ### Get the server version - ```console - $ docker version --format '{{.Server.Version}}' + ```console + $ docker version --format '{{.Server.Version}}' - 20.10.16 - ``` + 20.10.16 + ``` - ### Dump raw JSON data + ### Get the client API version - ```console - $ docker version --format '{{json .}}' + The following example prints the API version that is used by the client: - {"Client":{"Platform":{"Name":"Docker Engine - Community"},"Version":"19.03.8","ApiVersion":"1.40","DefaultAPIVersion":"1.40","GitCommit":"afacb8b","GoVersion":"go1.12.17","Os":"darwin","Arch":"amd64","BuildTime":"Wed Mar 11 01:21:11 2020","Experimental":true},"Server":{"Platform":{"Name":"Docker Engine - Community"},"Components":[{"Name":"Engine","Version":"19.03.8","Details":{"ApiVersion":"1.40","Arch":"amd64","BuildTime":"Wed Mar 11 01:29:16 2020","Experimental":"true","GitCommit":"afacb8b","GoVersion":"go1.12.17","KernelVersion":"4.19.76-linuxkit","MinAPIVersion":"1.12","Os":"linux"}},{"Name":"containerd","Version":"v1.2.13","Details":{"GitCommit":"7ad184331fa3e55e52b890ea95e65ba581ae3429"}},{"Name":"runc","Version":"1.0.0-rc10","Details":{"GitCommit":"dc9208a3303feef5b3839f4323d9beb36df0a9dd"}},{"Name":"docker-init","Version":"0.18.0","Details":{"GitCommit":"fec3683"}}],"Version":"19.03.8","ApiVersion":"1.40","MinAPIVersion":"1.12","GitCommit":"afacb8b","GoVersion":"go1.12.17","Os":"linux","Arch":"amd64","KernelVersion":"4.19.76-linuxkit","Experimental":true,"BuildTime":"2020-03-11T01:29:16.000000000+00:00"}} - ``` + ```console + $ docker version --format '{{.Client.APIVersion}}' - ### Print the current context + 1.41 + ``` - The following example prints the currently used [`docker context`](context.md): + The version shown is the API version that is negotiated between the client + and the Docker Engine. Refer to [API version and version negotiation](#api-version-and-version-negotiation) + above for more information. - ```console - $ docker version --format='{{.Client.Context}}' - default - ``` + ### Dump raw JSON data - As an example, this output can be used to dynamically change your shell prompt - to indicate your active context. The example below illustrates how this output - could be used when using Bash as your shell. + ```console + $ docker version --format '{{json .}}' - Declare a function to obtain the current context in your `~/.bashrc`, and set - this command as your `PROMPT_COMMAND` - - ```console - function docker_context_prompt() { - PS1="context: $(docker version --format='{{.Client.Context}}')> " - } - - PROMPT_COMMAND=docker_context_prompt - ``` - - After reloading the `~/.bashrc`, the prompt now shows the currently selected - `docker context`: - - ```console - $ source ~/.bashrc - context: default> docker context create --docker host=unix:///var/run/docker.sock my-context - my-context - Successfully created context "my-context" - context: default> docker context use my-context - my-context - Current context is now "my-context" - context: my-context> docker context use default - default - Current context is now "default" - context: default> - ``` - - Refer to the [`docker context` section](context.md) in the command line reference - for more information about `docker context`. + {"Client":{"Platform":{"Name":"Docker Engine - Community"},"Version":"19.03.8","ApiVersion":"1.40","DefaultAPIVersion":"1.40","GitCommit":"afacb8b","GoVersion":"go1.12.17","Os":"darwin","Arch":"amd64","BuildTime":"Wed Mar 11 01:21:11 2020","Experimental":true},"Server":{"Platform":{"Name":"Docker Engine - Community"},"Components":[{"Name":"Engine","Version":"19.03.8","Details":{"ApiVersion":"1.40","Arch":"amd64","BuildTime":"Wed Mar 11 01:29:16 2020","Experimental":"true","GitCommit":"afacb8b","GoVersion":"go1.12.17","KernelVersion":"4.19.76-linuxkit","MinAPIVersion":"1.12","Os":"linux"}},{"Name":"containerd","Version":"v1.2.13","Details":{"GitCommit":"7ad184331fa3e55e52b890ea95e65ba581ae3429"}},{"Name":"runc","Version":"1.0.0-rc10","Details":{"GitCommit":"dc9208a3303feef5b3839f4323d9beb36df0a9dd"}},{"Name":"docker-init","Version":"0.18.0","Details":{"GitCommit":"fec3683"}}],"Version":"19.03.8","ApiVersion":"1.40","MinAPIVersion":"1.12","GitCommit":"afacb8b","GoVersion":"go1.12.17","Os":"linux","Arch":"amd64","KernelVersion":"4.19.76-linuxkit","Experimental":true,"BuildTime":"2020-03-11T01:29:16.000000000+00:00"}} + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_volume.yaml b/_data/engine-cli/docker_volume.yaml index 26aead5194..aed184450a 100644 --- a/_data/engine-cli/docker_volume.yaml +++ b/_data/engine-cli/docker_volume.yaml @@ -1,23 +1,36 @@ command: docker volume short: Manage volumes long: |- - Manage volumes. You can use subcommands to create, inspect, list, remove, or - prune volumes. + Manage volumes. You can use subcommands to create, inspect, list, remove, or + prune volumes. usage: docker volume COMMAND pname: docker plink: docker.yaml cname: -- docker volume create -- docker volume inspect -- docker volume ls -- docker volume prune -- docker volume rm + - docker volume create + - docker volume inspect + - docker volume ls + - docker volume prune + - docker volume rm + - docker volume update clink: -- docker_volume_create.yaml -- docker_volume_inspect.yaml -- docker_volume_ls.yaml -- docker_volume_prune.yaml -- docker_volume_rm.yaml + - docker_volume_create.yaml + - docker_volume_inspect.yaml + - docker_volume_ls.yaml + - docker_volume_prune.yaml + - docker_volume_rm.yaml + - docker_volume_update.yaml +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_volume_create.yaml b/_data/engine-cli/docker_volume_create.yaml index c38a4725e8..0714736c51 100644 --- a/_data/engine-cli/docker_volume_create.yaml +++ b/_data/engine-cli/docker_volume_create.yaml @@ -1,130 +1,254 @@ command: docker volume create short: Create a volume long: |- - Creates a new volume that containers can consume and store data in. If a name is - not specified, Docker generates a random name. + Creates a new volume that containers can consume and store data in. If a name is + not specified, Docker generates a random name. usage: docker volume create [OPTIONS] [VOLUME] pname: docker volume plink: docker_volume.yaml options: -- option: driver - shorthand: d - value_type: string - default_value: local - description: Specify volume driver name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - value_type: list - description: Set metadata for a volume - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: name - value_type: string - description: Specify volume name - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: opt - shorthand: o - value_type: map - default_value: map[] - description: Set driver specific options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: availability + value_type: string + default_value: active + description: Cluster Volume availability (`active`, `pause`, `drain`) + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: driver + shorthand: d + value_type: string + default_value: local + description: Specify volume driver name + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: group + value_type: string + description: Cluster Volume group (cluster volumes) + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: label + value_type: list + description: Set metadata for a volume + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: limit-bytes + value_type: bytes + default_value: "0" + description: Minimum size of the Cluster Volume in bytes + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: name + value_type: string + description: Specify volume name + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: opt + shorthand: o + value_type: map + default_value: map[] + description: Set driver specific options + details_url: '#opt' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: required-bytes + value_type: bytes + default_value: "0" + description: Maximum size of the Cluster Volume in bytes + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: scope + value_type: string + default_value: single + description: Cluster Volume access scope (`single`, `multi`) + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: secret + value_type: map + default_value: map[] + description: Cluster Volume secrets + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: sharing + value_type: string + default_value: none + description: | + Cluster Volume access sharing (`none`, `readonly`, `onewriter`, `all`) + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: topology-preferred + value_type: list + description: A topology that the Cluster Volume would be preferred in + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: topology-required + value_type: list + description: A topology that the Cluster Volume must be accessible from + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: type + value_type: string + default_value: block + description: Cluster Volume access type (`mount`, `block`) + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - Create a volume and then configure the container to use it: + Create a volume and then configure the container to use it: - ```console - $ docker volume create hello + ```console + $ docker volume create hello - hello + hello - $ docker run -d -v hello:/world busybox ls /world - ``` + $ docker run -d -v hello:/world busybox ls /world + ``` - The mount is created inside the container's `/world` directory. Docker does not - support relative paths for mount points inside the container. + The mount is created inside the container's `/world` directory. Docker does not + support relative paths for mount points inside the container. - Multiple containers can use the same volume in the same time period. This is - useful if two containers need access to shared data. For example, if one - container writes and the other reads the data. + Multiple containers can use the same volume in the same time period. This is + useful if two containers need access to shared data. For example, if one + container writes and the other reads the data. - Volume names must be unique among drivers. This means you cannot use the same - volume name with two different drivers. If you attempt this `docker` returns an - error: + Volume names must be unique among drivers. This means you cannot use the same + volume name with two different drivers. If you attempt this `docker` returns an + error: - ```console - A volume named "hello" already exists with the "some-other" driver. Choose a different volume name. - ``` + ```console + A volume named "hello" already exists with the "some-other" driver. Choose a different volume name. + ``` - If you specify a volume name already in use on the current driver, Docker - assumes you want to re-use the existing volume and does not return an error. + If you specify a volume name already in use on the current driver, Docker + assumes you want to re-use the existing volume and does not return an error. - ### Driver-specific options (-o, --opt) + ### Driver-specific options (-o, --opt) {#opt} - Some volume drivers may take options to customize the volume creation. Use the - `-o` or `--opt` flags to pass driver options: + Some volume drivers may take options to customize the volume creation. Use the + `-o` or `--opt` flags to pass driver options: - ```console - $ docker volume create --driver fake \ - --opt tardis=blue \ - --opt timey=wimey \ - foo - ``` + ```console + $ docker volume create --driver fake \ + --opt tardis=blue \ + --opt timey=wimey \ + foo + ``` - These options are passed directly to the volume driver. Options for - different volume drivers may do different things (or nothing at all). + These options are passed directly to the volume driver. Options for + different volume drivers may do different things (or nothing at all). - The built-in `local` driver on Windows does not support any options. + The built-in `local` driver on Windows does not support any options. - The built-in `local` driver on Linux accepts options similar to the linux - `mount` command. You can provide multiple options by passing the `--opt` flag - multiple times. Some `mount` options (such as the `o` option) can take a - comma-separated list of options. Complete list of available mount options can be - found [here](https://man7.org/linux/man-pages/man8/mount.8.html). + The built-in `local` driver on Linux accepts options similar to the linux + `mount` command. You can provide multiple options by passing the `--opt` flag + multiple times. Some `mount` options (such as the `o` option) can take a + comma-separated list of options. Complete list of available mount options can be + found [here](https://man7.org/linux/man-pages/man8/mount.8.html). - For example, the following creates a `tmpfs` volume called `foo` with a size of - 100 megabyte and `uid` of 1000. + For example, the following creates a `tmpfs` volume called `foo` with a size of + 100 megabyte and `uid` of 1000. - ```console - $ docker volume create --driver local \ - --opt type=tmpfs \ - --opt device=tmpfs \ - --opt o=size=100m,uid=1000 \ - foo - ``` + ```console + $ docker volume create --driver local \ + --opt type=tmpfs \ + --opt device=tmpfs \ + --opt o=size=100m,uid=1000 \ + foo + ``` - Another example that uses `btrfs`: + Another example that uses `btrfs`: - ```console - $ docker volume create --driver local \ - --opt type=btrfs \ - --opt device=/dev/sda2 \ - foo - ``` + ```console + $ docker volume create --driver local \ + --opt type=btrfs \ + --opt device=/dev/sda2 \ + foo + ``` - Another example that uses `nfs` to mount the `/path/to/dir` in `rw` mode from - `192.168.1.1`: + Another example that uses `nfs` to mount the `/path/to/dir` in `rw` mode from + `192.168.1.1`: - ```console - $ docker volume create --driver local \ - --opt type=nfs \ - --opt o=addr=192.168.1.1,rw \ - --opt device=:/path/to/dir \ - foo - ``` + ```console + $ docker volume create --driver local \ + --opt type=nfs \ + --opt o=addr=192.168.1.1,rw \ + --opt device=:/path/to/dir \ + foo + ``` deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_volume_inspect.yaml b/_data/engine-cli/docker_volume_inspect.yaml index 3fcc4af7fb..3a15ef3d4b 100644 --- a/_data/engine-cli/docker_volume_inspect.yaml +++ b/_data/engine-cli/docker_volume_inspect.yaml @@ -1,63 +1,80 @@ command: docker volume inspect short: Display detailed information on one or more volumes long: |- - Returns information about a volume. By default, this command renders all results - in a JSON array. You can specify an alternate format to execute a - given template for each result. Go's - [text/template](https://golang.org/pkg/text/template/) package describes all the - details of the format. + Returns information about a volume. By default, this command renders all results + in a JSON array. You can specify an alternate format to execute a + given template for each result. Go's + [text/template](https://golang.org/pkg/text/template/) package describes all the + details of the format. usage: docker volume inspect [OPTIONS] VOLUME [VOLUME...] pname: docker volume plink: docker_volume.yaml options: -- option: format - shorthand: f - value_type: string - description: Format the output using the given Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: format + shorthand: f + value_type: string + description: |- + Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ```console - $ docker volume create myvolume + ```console + $ docker volume create myvolume - myvolume - ``` + myvolume + ``` - Use the `docker volume inspect` comment to inspect the configuration of the volume: + Use the `docker volume inspect` comment to inspect the configuration of the volume: - ```console - $ docker volume inspect myvolume - ``` + ```console + $ docker volume inspect myvolume + ``` - The output is in JSON format, for example: + The output is in JSON format, for example: - ```json - [ - { - "CreatedAt": "2020-04-19T11:00:21Z", - "Driver": "local", - "Labels": {}, - "Mountpoint": "/var/lib/docker/volumes/8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5/_data", - "Name": "myvolume", - "Options": {}, - "Scope": "local" - } - ] - ``` + ```json + [ + { + "CreatedAt": "2020-04-19T11:00:21Z", + "Driver": "local", + "Labels": {}, + "Mountpoint": "/var/lib/docker/volumes/8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5/_data", + "Name": "myvolume", + "Options": {}, + "Scope": "local" + } + ] + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - Use the `--format` flag to format the output using a Go template, for example, - to print the `Mountpoint` property: + Use the `--format` flag to format the output using a Go template, for example, + to print the `Mountpoint` property: - ```console - $ docker volume inspect --format '{{ .Mountpoint }}' myvolume + ```console + $ docker volume inspect --format '{{ .Mountpoint }}' myvolume - /var/lib/docker/volumes/myvolume/_data - ``` + /var/lib/docker/volumes/myvolume/_data + ``` deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_volume_ls.yaml b/_data/engine-cli/docker_volume_ls.yaml index 0a1dd059e7..0763128e9a 100644 --- a/_data/engine-cli/docker_volume_ls.yaml +++ b/_data/engine-cli/docker_volume_ls.yaml @@ -1,190 +1,231 @@ command: docker volume ls -aliases: list +aliases: docker volume ls, docker volume list short: List volumes long: |- - List all the volumes known to Docker. You can filter using the `-f` or - `--filter` flag. Refer to the [filtering](#filter) section for more - information about available filter options. + List all the volumes known to Docker. You can filter using the `-f` or + `--filter` flag. Refer to the [filtering](#filter) section for more + information about available filter options. usage: docker volume ls [OPTIONS] pname: docker volume plink: docker_volume.yaml options: -- option: filter - shorthand: f - value_type: filter - description: Provide filter values (e.g. 'dangling=true') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: format - value_type: string - description: Pretty-print volumes using a Go template - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Only display volume names - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false + - option: cluster + value_type: bool + default_value: "false" + description: | + Display only cluster volumes, and use cluster volume list formatting + deprecated: false + hidden: false + min_api_version: "1.42" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true + - option: filter + shorthand: f + value_type: filter + description: Provide filter values (e.g. `dangling=true`) + details_url: '#filter' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: format + value_type: string + description: |- + Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + details_url: '#format' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display volume names + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: help + value_type: bool + default_value: "false" + description: Print usage + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- - ### Create a volume + ### Create a volume - ```console - $ docker volume create rosemary + ```console + $ docker volume create rosemary - rosemary + rosemary - $ docker volume create tyler + $ docker volume create tyler - tyler + tyler - $ docker volume ls + $ docker volume ls - DRIVER VOLUME NAME - local rosemary - local tyler - ``` + DRIVER VOLUME NAME + local rosemary + local tyler + ``` - ### Filtering (--filter) + ### Filtering (--filter) {#filter} - The filtering flag (`-f` or `--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 filtering flag (`-f` or `--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: + The currently supported filters are: - - dangling (boolean - true or false, 0 or 1) - - driver (a volume driver's name) - - label (`label=` or `label==`) - - name (a volume's name) + - dangling (boolean - true or false, 0 or 1) + - driver (a volume driver's name) + - label (`label=` or `label==`) + - name (a volume's name) - #### dangling + #### dangling - The `dangling` filter matches on all volumes not referenced by any containers + The `dangling` filter matches on all volumes not referenced by any containers - ```console - $ docker run -d -v tyler:/tmpwork busybox + ```console + $ docker run -d -v tyler:/tmpwork busybox - f86a7dd02898067079c99ceacd810149060a70528eff3754d0b0f1a93bd0af18 - $ docker volume ls -f dangling=true - DRIVER VOLUME NAME - local rosemary - ``` + f86a7dd02898067079c99ceacd810149060a70528eff3754d0b0f1a93bd0af18 + $ docker volume ls -f dangling=true + DRIVER VOLUME NAME + local rosemary + ``` - #### driver + #### driver - The `driver` filter matches volumes based on their driver. + The `driver` filter matches volumes based on their driver. - The following example matches volumes that are created with the `local` driver: + The following example matches volumes that are created with the `local` driver: - ```console - $ docker volume ls -f driver=local + ```console + $ docker volume ls -f driver=local - DRIVER VOLUME NAME - local rosemary - local tyler - ``` + DRIVER VOLUME NAME + local rosemary + local tyler + ``` - #### label + #### label - The `label` filter matches volumes based on the presence of a `label` alone or - a `label` and a value. + The `label` filter matches volumes based on the presence of a `label` alone or + a `label` and a value. - First, let's create some volumes to illustrate this; + First, let's create some volumes to illustrate this; - ```console - $ docker volume create the-doctor --label is-timelord=yes + ```console + $ docker volume create the-doctor --label is-timelord=yes - the-doctor - $ docker volume create daleks --label is-timelord=no + the-doctor + $ docker volume create daleks --label is-timelord=no - daleks - ``` + daleks + ``` - The following example filter matches volumes with the `is-timelord` label - regardless of its value. + The following example filter matches volumes with the `is-timelord` label + regardless of its value. - ```console - $ docker volume ls --filter label=is-timelord + ```console + $ docker volume ls --filter label=is-timelord - DRIVER VOLUME NAME - local daleks - local the-doctor - ``` + DRIVER VOLUME NAME + local daleks + local the-doctor + ``` - As the above example demonstrates, both volumes with `is-timelord=yes`, and - `is-timelord=no` are returned. + As the above example demonstrates, both volumes with `is-timelord=yes`, and + `is-timelord=no` are returned. - Filtering on both `key` *and* `value` of the label, produces the expected result: + Filtering on both `key` *and* `value` of the label, produces the expected result: - ```console - $ docker volume ls --filter label=is-timelord=yes + ```console + $ docker volume ls --filter label=is-timelord=yes - DRIVER VOLUME NAME - local the-doctor - ``` + DRIVER VOLUME NAME + local the-doctor + ``` - Specifying multiple label filter produces an "and" search; all conditions - should be met; + Specifying multiple label filter produces an "and" search; all conditions + should be met; - ```console - $ docker volume ls --filter label=is-timelord=yes --filter label=is-timelord=no + ```console + $ docker volume ls --filter label=is-timelord=yes --filter label=is-timelord=no - DRIVER VOLUME NAME - ``` + DRIVER VOLUME NAME + ``` - #### name + #### name - The `name` filter matches on all or part of a volume's name. + The `name` filter matches on all or part of a volume's name. - The following filter matches all volumes with a name containing the `rose` string. + The following filter matches all volumes with a name containing the `rose` string. - ```console - $ docker volume ls -f name=rose + ```console + $ docker volume ls -f name=rose - DRIVER VOLUME NAME - local rosemary - ``` + DRIVER VOLUME NAME + local rosemary + ``` - ### Format the output (--format) + ### Format the output (--format) {#format} - The formatting options (`--format`) pretty-prints volumes output - using a Go template. + The formatting options (`--format`) pretty-prints volumes output + using a Go template. - Valid placeholders for the Go template are listed below: + Valid placeholders for the Go template are listed below: - | Placeholder | Description | - |---------------|---------------------------------------------------------------------------------------| - | `.Name` | Volume name | - | `.Driver` | Volume driver | - | `.Scope` | Volume scope (local, global) | - | `.Mountpoint` | The mount point of the volume on the host | - | `.Labels` | All labels assigned to the volume | - | `.Label` | Value of a specific label for this volume. For example `{{.Label "project.version"}}` | + | Placeholder | Description | + |---------------|---------------------------------------------------------------------------------------| + | `.Name` | Volume name | + | `.Driver` | Volume driver | + | `.Scope` | Volume scope (local, global) | + | `.Mountpoint` | The mount point of the volume on the host | + | `.Labels` | All labels assigned to the volume | + | `.Label` | Value of a specific label for this volume. For example `{{.Label "project.version"}}` | - When using the `--format` option, the `volume ls` command will either - output the data exactly as the template declares or, when using the - `table` directive, includes column headers as well. + When using the `--format` option, the `volume ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. - The following example uses a template without headers and outputs the - `Name` and `Driver` entries separated by a colon (`:`) for all volumes: + The following example uses a template without headers and outputs the + `Name` and `Driver` entries separated by a colon (`:`) for all volumes: - ```console - $ docker volume ls --format "{{.Name}}: {{.Driver}}" + ```console + $ docker volume ls --format "{{.Name}}: {{.Driver}}" - vol1: local - vol2: local - vol3: local - ``` + vol1: local + vol2: local + vol3: local + ``` + + To list all volumes in JSON format, use the `json` directive: + + ```console + $ docker volume ls --format json + {"Driver":"local","Labels":"","Links":"N/A","Mountpoint":"/var/lib/docker/volumes/docker-cli-dev-cache/_data","Name":"docker-cli-dev-cache","Scope":"local","Size":"N/A"} + ``` deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_volume_prune.yaml b/_data/engine-cli/docker_volume_prune.yaml index 69d04e7ff3..582b8a8a55 100644 --- a/_data/engine-cli/docker_volume_prune.yaml +++ b/_data/engine-cli/docker_volume_prune.yaml @@ -1,55 +1,69 @@ command: docker volume prune short: Remove all unused local volumes -long: Remove all unused local volumes. Unused local volumes are those which are not - referenced by any containers +long: | + Remove all unused local volumes. Unused local volumes are those which are not referenced by any containers usage: docker volume prune [OPTIONS] pname: docker volume plink: docker_volume.yaml options: -- option: filter - value_type: filter - description: Provide filter values (e.g. 'label=